Man

Command Section
FPU_KERN(9)            FreeBSD Kernel Developer's Manual           FPU_KERN(9)

NAME
     fpu_kern - facility to use the FPU in the kernel

SYNOPSIS
     struct fpu_kern_ctx *
     fpu_kern_alloc_ctx(u_int flags);

     void
     fpu_kern_free_ctx(struct fpu_kern_ctx *ctx);

     int
     fpu_kern_enter(struct thread *td, struct fpu_kern_ctx *ctx, u_int flags);

     int
     fpu_kern_leave(struct thread *td, struct fpu_kern_ctx *ctx);

     int
     fpu_kern_thread(u_int flags);

     int
     is_fpu_kern_thread(u_int flags);

DESCRIPTION
     The fpu_kern family of functions allows the use of FPU hardware in kernel
     code.  Modern FPUs are not limited to providing hardware implementation
     for floating point arithmetic; they offer advanced accelerators for
     cryptography and other computational-intensive algorithms.  These
     facilities share registers with the FPU hardware.

     Typical kernel code does not need access to the FPU.  Saving a large
     register file on each entry to the kernel would waste time.  When kernel
     code uses the FPU, the current FPU state must be saved to avoid
     corrupting the user-mode state, and vice versa.

     The management of the save and restore is automatic.  The processor
     catches accesses to the FPU registers when the non-current context tries
     to access them.  Explicit calls are required for the allocation of the
     save area and the notification of the start and end of the code using the
     FPU.

     The fpu_kern_alloc_ctx() function allocates the memory used by fpu_kern
     to track the use of the FPU hardware state and the related software
     state.  The fpu_kern_alloc_ctx() function requires the flags argument,
     which currently accepts the following flags:

           FPU_KERN_NOWAIT      Do not wait for the available memory if the
                                request could not be satisfied without sleep.

           0                    No special handling is required.

     The function returns the allocated context area, or NULL if the
     allocation failed.

     The fpu_kern_free_ctx() function frees the context previously allocated
     by fpu_kern_alloc_ctx().

     The fpu_kern_enter() function designates the start of the region of
     kernel code where the use of the FPU is allowed.  Its arguments are:

           td       Currently must be curthread.

           ctx      The context save area previously allocated by
                    fpu_kern_alloc_ctx() and not currently in use by another
                    call to fpu_kern_enter().

           flags    This argument currently accepts the following flags:

                          FPU_KERN_NORMAL      Indicates that the caller
                                               intends to access the full FPU
                                               state.  Must be specified
                                               currently.

                          FPU_KERN_KTHR        Indicates that no saving of the
                                               current FPU state should be
                                               performed, if the thread called
                                               fpu_kern_thread(9) function.
                                               This is intended to minimize
                                               code duplication in callers
                                               which could be used from both
                                               kernel thread and syscall
                                               contexts.  The fpu_kern_leave()
                                               function correctly handles such
                                               contexts.

                          FPU_KERN_NOCTX       Avoid nesting save area.  If
                                               the flag is specified, the ctx
                                               must be passed as NULL.  The
                                               flag should only be used for
                                               really short code blocks which
                                               can be executed in a critical
                                               section.  It avoids the need to
                                               allocate the FPU context by the
                                               cost of increased system
                                               latency.

     The function does not sleep or block.  It could cause the Device Not
     Available exception during execution, and on the first FPU access after
     the function returns, as well as after each context switch (see Intel
     Software Developer Manual for the reference).  Currently, no errors are
     defined which can be returned by fpu_kern_enter() to the caller.

     The fpu_kern_leave() function ends the region started by
     fpu_kern_enter().  The uses of FPU in the kernel after the call to
     fpu_kern_leave() are erroneous until the next call to fpu_kern_enter() is
     performed.  The function takes the td thread argument, which currently
     must be curthread, and the ctx context pointer, previously passed to
     fpu_kern_enter().  After the function returns, the context may be freed
     or reused by other invocation of fpu_kern_enter().  There are no errors
     defined for the function, it always returns 0.

     The fpu_kern_thread() function enables an optimization for threads which
     never leave to the usermode.  The current thread will reuse the usermode
     save area for the kernel FPU state instead of requiring an explicitly
     allocated context.  There are no flags defined for the function, and no
     error states that the function returns.  Once this function has been
     called, neither fpu_kern_enter() nor fpu_kern_leave() is required to be
     called and the fpu is available for use in the calling thread.

     The is_fpu_kern_thread() function returns the boolean indicating whether
     the current thread entered the mode enabled by fpu_kern_thread().  There
     is currently no flags defined for the function, the return value is true
     if the current thread have the permanent FPU save area, and false
     otherwise.

NOTES
     The fpu_kern is currently implemented only for the i386 and amd64
     architectures.

     There is no way to handle floating point exceptions raised from kernel
     mode.

     The unused flags arguments to the fpu_kern functions are to be extended
     to allow specification of the set of the FPU hardware state used by the
     code region.  This would allow optimizations of saving and restoring the
     state.

AUTHORS
     The fpu_kern facitily and this manual page were written by Konstantin
     Belousov <[email protected]>.

FreeBSD 11.1-RELEASE-p4        October 23, 2014        FreeBSD 11.1-RELEASE-p4
Command Section