2 .\" Konstantin Belousov <kib@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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.
31 .Nd "facility to use the FPU in the kernel"
34 .Ft struct fpu_kern_ctx *
35 .Fn fpu_kern_alloc_ctx "u_int flags"
37 .Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx"
39 .Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags"
41 .Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx"
43 .Fn fpu_kern_thread "u_int flags"
45 .Fn is_fpu_kern_thread "u_int flags"
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.
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
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.
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.
68 .Fn fpu_kern_alloc_ctx
69 function allocates the memory used by
71 to track the use of the FPU hardware state and the related software state.
73 .Fn fpu_kern_alloc_ctx
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
82 No special handling is required.
85 The function returns the allocated context area, or
87 if the allocation failed.
91 function frees the context previously allocated by
92 .Fn fpu_kern_alloc_ctx .
96 function designates the start of the region of kernel code where the
97 use of the FPU is allowed.
99 .Bl -tag -width ".Fa ctx" -offset indent
104 The context save area previously allocated by
105 .Fn fpu_kern_alloc_ctx
106 and not currently in use by another call to
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.
115 Indicates that no saving of the current FPU state should be performed,
117 .Xr fpu_kern_thread 9
119 This is intended to minimize code duplication in callers which
120 could be used from both kernel thread and syscall contexts.
123 function correctly handles such contexts.
124 .It Dv FPU_KERN_NOCTX
125 Avoid nesting save area.
126 If the flag is specified, the
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.
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).
146 function ends the region started by
148 It is erroneous to use the FPU in the kernel before
152 The function takes the
154 thread argument, which currently must be
158 context pointer, previously passed to
160 After the function returns, the context may be freed or reused
161 by another invocation of
163 The function always returns 0.
167 function enables an optimization for threads which never leave to
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
177 is required to be called and the fpu is available for use in the calling thread.
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,
190 is currently implemented only for the i386, amd64, and arm64 architectures.
192 There is no way to handle floating point exceptions raised from
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.
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 .
212 should probably have type
215 .Fn fpu_kern_enter ) .