1.\" Copyright (c) 2014 2.\" Konstantin Belousov <kib@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 14.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 15.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 16.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 17.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 18.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 19.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 20.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 21.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 22.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd October 23, 2014 27.Dt FPU_KERN 9 28.Os 29.Sh NAME 30.Nm fpu_kern 31.Nd "facility to use the FPU in the kernel" 32.Sh SYNOPSIS 33.Ft struct fpu_kern_ctx * 34.Fn fpu_kern_alloc_ctx "u_int flags" 35.Ft void 36.Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx" 37.Ft int 38.Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags" 39.Ft int 40.Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx" 41.Ft int 42.Fn fpu_kern_thread "u_int flags" 43.Ft int 44.Fn is_fpu_kern_thread "u_int flags" 45.Sh DESCRIPTION 46The 47.Nm 48family of functions allows the use of FPU hardware in kernel code. 49Modern FPUs are not limited to providing hardware implementation for 50floating point arithmetic; they offer advanced accelerators for cryptography 51and other computational-intensive algorithms. 52These facilities share registers with the FPU hardware. 53.Pp 54Typical kernel code does not need access to the FPU. 55Saving a large register file on each entry to the kernel would waste 56time. 57When kernel code uses the FPU, the current FPU state must be saved to 58avoid corrupting the user-mode state, and vice versa. 59.Pp 60The management of the save and restore is automatic. 61The processor catches accesses to the FPU registers 62when the non-current context tries to access them. 63Explicit calls are required for the allocation of the save area and 64the notification of the start and end of the code using the FPU. 65.Pp 66The 67.Fn fpu_kern_alloc_ctx 68function allocates the memory used by 69.Nm 70to track the use of the FPU hardware state and the related software state. 71The 72.Fn fpu_kern_alloc_ctx 73function requires the 74.Fa flags 75argument, which currently accepts the following flags: 76.Bl -tag -width ".Dv FPU_KERN_NOWAIT" -offset indent 77.It Dv FPU_KERN_NOWAIT 78Do not wait for the available memory if the request could not be satisfied 79without sleep. 80.It 0 81No special handling is required. 82.El 83.Pp 84The function returns the allocated context area, or 85.Va NULL 86if the allocation failed. 87.Pp 88The 89.Fn fpu_kern_free_ctx 90function frees the context previously allocated by 91.Fn fpu_kern_alloc_ctx . 92.Pp 93The 94.Fn fpu_kern_enter 95function designates the start of the region of kernel code where the 96use of the FPU is allowed. 97Its arguments are: 98.Bl -tag -width ".Fa ctx" -offset indent 99.It Fa td 100Currently must be 101.Va curthread . 102.It Fa ctx 103The context save area previously allocated by 104.Fn fpu_kern_alloc_ctx 105and not currently in use by another call to 106.Fn fpu_kern_enter . 107.It Fa flags 108This argument currently accepts the following flags: 109.Bl -tag -width ".Dv FPU_KERN_NORMAL" -offset indent 110.It Dv FPU_KERN_NORMAL 111Indicates that the caller intends to access the full FPU state. 112Must be specified currently. 113.It Dv FPU_KERN_KTHR 114Indicates that no saving of the current FPU state should be performed, 115if the thread called 116.Xr fpu_kern_thread 9 117function. 118This is intended to minimize code duplication in callers which 119could be used from both kernel thread and syscall contexts. 120The 121.Fn fpu_kern_leave 122function correctly handles such contexts. 123.El 124.El 125.Pp 126The function does not sleep or block. 127It could cause the 128.Nm Device Not Available 129exception during execution, and on the first FPU access after the 130function returns, as well as after each context switch 131(see Intel Software Developer Manual for the reference). 132Currently, no errors are defined which can be returned by 133.Fn fpu_kern_enter 134to the caller. 135.Pp 136The 137.Fn fpu_kern_leave 138function ends the region started by 139.Fn fpu_kern_enter . 140The uses of FPU in the kernel after the call to 141.Fn fpu_kern_leave 142are erroneous until the next call to 143.Fn fpu_kern_enter 144is performed. 145The function takes the 146.Fa td 147thread argument, which currently must be 148.Va curthread , 149and the 150.Fa ctx 151context pointer, previously passed to 152.Fn fpu_kern_enter . 153After the function returns, the context may be freed or reused 154by other invocation of 155.Fn fpu_kern_enter . 156There are no errors defined for the function, it always returns 0. 157.Pp 158The 159.Fn fpu_kern_thread 160function enables an optimization for threads which never leave to 161the usermode. 162The current thread will reuse the usermode save area for the kernel FPU state 163instead of requiring an explicitly allocated context. 164There are no flags defined for the function, and no error states 165that the function returns. 166Once this function has been called, neither 167.Fn fpu_kern_enter 168nor 169.Fn fpu_kern_leave 170is required to be called and the fpu is available for use in the calling thread. 171.Pp 172The 173.Fn is_fpu_kern_thread 174function returns the boolean indicating whether the current thread 175entered the mode enabled by 176.Fn fpu_kern_thread . 177There is currently no flags defined for the function, the return 178value is true if the current thread have the permanent FPU save area, 179and false otherwise. 180.Sh NOTES 181The 182.Nm 183is currently implemented only for the i386 and amd64 architectures. 184.Pp 185There is no way to handle floating point exceptions raised from 186kernel mode. 187.Pp 188The unused 189.Fa flags 190arguments 191to the 192.Nm 193functions are to be extended to allow specification of the 194set of the FPU hardware state used by the code region. 195This would allow optimizations of saving and restoring the state. 196.Sh AUTHORS 197The 198.Nm 199facitily and this manual page were written by 200.An Konstantin Belousov Aq Mt kib@FreeBSD.org . 201