share/man/man9/fpu_kern.9

   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 13, 2020
  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 .In machine/fpu.h
  34 .Ft struct fpu_kern_ctx *
  35 .Fn fpu_kern_alloc_ctx "u_int flags"
  36 .Ft void
  37 .Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx"
  38 .Ft void
  39 .Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags"
  40 .Ft int
  41 .Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx"
  42 .Ft int
  43 .Fn fpu_kern_thread "u_int flags"
  44 .Ft int
  45 .Fn is_fpu_kern_thread "u_int flags"
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 family of functions allows the use of FPU hardware in kernel code.
  50 Modern FPUs are not limited to providing hardware implementation for
  51 floating point arithmetic; they offer advanced accelerators for cryptography
  52 and other computational-intensive algorithms.
  53 These facilities share registers with the FPU hardware.
  54 .Pp
  55 Typical kernel code does not need access to the FPU.
  56 Saving a large register file on each entry to the kernel would waste
  57 time.
  58 When kernel code uses the FPU, the current FPU state must be saved to
  59 avoid corrupting the user-mode state, and vice versa.
  60 .Pp
  61 The management of the save and restore is automatic.
  62 The processor catches accesses to the FPU registers
  63 when the non-current context tries to access them.
  64 Explicit calls are required for the allocation of the save area and
  65 the notification of the start and end of the code using the FPU.
  66 .Pp
  67 The
  68 .Fn fpu_kern_alloc_ctx
  69 function allocates the memory used by
  70 .Nm
  71 to track the use of the FPU hardware state and the related software state.
  72 The
  73 .Fn fpu_kern_alloc_ctx
  74 function requires the
  75 .Fa flags
  76 argument, which currently accepts the following flags:
  77 .Bl -tag -width ".Dv FPU_KERN_NOWAIT" -offset indent
  78 .It Dv FPU_KERN_NOWAIT
  79 Do not wait for the available memory if the request could not be satisfied
  80 without sleep.
  81 .It 0
  82 No special handling is required.
  83 .El
  84 .Pp
  85 The function returns the allocated context area, or
  86 .Va NULL
  87 if the allocation failed.
  88 .Pp
  89 The
  90 .Fn fpu_kern_free_ctx
  91 function frees the context previously allocated by
  92 .Fn fpu_kern_alloc_ctx .
  93 .Pp
  94 The
  95 .Fn fpu_kern_enter
  96 function designates the start of the region of kernel code where the
  97 use of the FPU is allowed.
  98 Its arguments are:
  99 .Bl -tag -width ".Fa ctx" -offset indent
 100 .It Fa td
 101 Currently must be
 102 .Va curthread .
 103 .It Fa ctx
 104 The context save area previously allocated by
 105 .Fn fpu_kern_alloc_ctx
 106 and not currently in use by another call to
 107 .Fn fpu_kern_enter .
 108 .It Fa flags
 109 This argument currently accepts the following flags:
 110 .Bl -tag -width ".Dv FPU_KERN_NORMAL" -offset indent
 111 .It Dv FPU_KERN_NORMAL
 112 Indicates that the caller intends to access the full FPU state.
 113 Must be specified currently.
 114 .It Dv FPU_KERN_KTHR
 115 Indicates that no saving of the current FPU state should be performed,
 116 if the thread called
 117 .Xr fpu_kern_thread 9
 118 function.
 119 This is intended to minimize code duplication in callers which
 120 could be used from both kernel thread and syscall contexts.
 121 The
 122 .Fn fpu_kern_leave
 123 function correctly handles such contexts.
 124 .It Dv FPU_KERN_NOCTX
 125 Avoid nesting save area.
 126 If the flag is specified, the
 127 .Fa ctx
 128 must be passed as
 129 .Va NULL .
 130 The flag should only be used for really short code blocks
 131 which can be executed in a critical section.
 132 It avoids the need to allocate the FPU context by the cost
 133 of increased system latency.
 134 .El
 135 .El
 136 .Pp
 137 The function does not sleep or block.
 138 It could cause an FPU trap during execution, and on the first FPU access
 139 after the function returns, as well as after each context switch.
 140 On i386 and amd64 this will be the
 141 .Nm Device Not Available
 142 exception (see Intel Software Developer Manual for the reference).
 143 .Pp
 144 The
 145 .Fn fpu_kern_leave
 146 function ends the region started by
 147 .Fn fpu_kern_enter .
 148 It is erroneous to use the FPU in the kernel before
 149 .Fn fpu_kern_enter
 150 or after
 151 .Fn fpu_kern_leave .
 152 The function takes the
 153 .Fa td
 154 thread argument, which currently must be
 155 .Va curthread ,
 156 and the
 157 .Fa ctx
 158 context pointer, previously passed to
 159 .Fn fpu_kern_enter .
 160 After the function returns, the context may be freed or reused
 161 by another invocation of
 162 .Fn fpu_kern_enter .
 163 The function always returns 0.
 164 .Pp
 165 The
 166 .Fn fpu_kern_thread
 167 function enables an optimization for threads which never leave to
 168 the usermode.
 169 The current thread will reuse the usermode save area for the kernel FPU state
 170 instead of requiring an explicitly allocated context.
 171 There are no flags defined for the function, and no error states
 172 that the function returns.
 173 Once this function has been called, neither
 174 .Fn fpu_kern_enter
 175 nor
 176 .Fn fpu_kern_leave
 177 is required to be called and the fpu is available for use in the calling thread.
 178 .Pp
 179 The
 180 .Fn is_fpu_kern_thread
 181 function returns the boolean indicating whether the current thread
 182 entered the mode enabled by
 183 .Fn fpu_kern_thread .
 184 There is currently no flags defined for the function, the return
 185 value is true if the current thread have the permanent FPU save area,
 186 and false otherwise.
 187 .Sh NOTES
 188 The
 189 .Nm
 190 is currently implemented only for the i386, amd64, and arm64 architectures.
 191 .Pp
 192 There is no way to handle floating point exceptions raised from
 193 kernel mode.
 194 .Pp
 195 The unused
 196 .Fa flags
 197 arguments
 198 to the
 199 .Nm
 200 functions are to be extended to allow specification of the
 201 set of the FPU hardware state used by the code region.
 202 This would allow optimizations of saving and restoring the state.
 203 .Sh AUTHORS
 204 The
 205 .Nm
 206 facitily and this manual page were written by
 207 .An Konstantin Belousov Aq Mt kib@FreeBSD.org .
 208 The arm64 support was added by
 209 .An Andrew Turner Aq Mt andrew@FreeBSD.org .
 210 .Sh BUGS
 211 .Fn fpu_kern_leave
 212 should probably have type
 213 .Ft void
 214 (like
 215 .Fn fpu_kern_enter ) .