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 20, 2016 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.It Dv FPU_KERN_NOCTX 124Avoid nesting save area. 125If the flag is specified, the 126.Fa ctx 127must be passed as 128.Va NULL . 129The flag should only be used for really short code blocks 130which can be executed in a critical section. 131It avoids the need to allocate the FPU context by the cost 132of increased system latency. 133.El 134.El 135.Pp 136The function does not sleep or block. 137It could cause an FPU trap during execution, and on the first FPU access 138after the function returns, as well as after each context switch. 139On i386 and amd64 this will be the 140.Nm Device Not Available 141exception (see Intel Software Developer Manual for the reference). 142Currently, no errors are defined which can be returned by 143.Fn fpu_kern_enter 144to the caller. 145.Pp 146The 147.Fn fpu_kern_leave 148function ends the region started by 149.Fn fpu_kern_enter . 150The uses of FPU in the kernel after the call to 151.Fn fpu_kern_leave 152are erroneous until the next call to 153.Fn fpu_kern_enter 154is performed. 155The function takes the 156.Fa td 157thread argument, which currently must be 158.Va curthread , 159and the 160.Fa ctx 161context pointer, previously passed to 162.Fn fpu_kern_enter . 163After the function returns, the context may be freed or reused 164by other invocation of 165.Fn fpu_kern_enter . 166There are no errors defined for the function, it always returns 0. 167.Pp 168The 169.Fn fpu_kern_thread 170function enables an optimization for threads which never leave to 171the usermode. 172The current thread will reuse the usermode save area for the kernel FPU state 173instead of requiring an explicitly allocated context. 174There are no flags defined for the function, and no error states 175that the function returns. 176Once this function has been called, neither 177.Fn fpu_kern_enter 178nor 179.Fn fpu_kern_leave 180is required to be called and the fpu is available for use in the calling thread. 181.Pp 182The 183.Fn is_fpu_kern_thread 184function returns the boolean indicating whether the current thread 185entered the mode enabled by 186.Fn fpu_kern_thread . 187There is currently no flags defined for the function, the return 188value is true if the current thread have the permanent FPU save area, 189and false otherwise. 190.Sh NOTES 191The 192.Nm 193is currently implemented only for the i386, amd64, and arm64 architectures. 194.Pp 195There is no way to handle floating point exceptions raised from 196kernel mode. 197.Pp 198The unused 199.Fa flags 200arguments 201to the 202.Nm 203functions are to be extended to allow specification of the 204set of the FPU hardware state used by the code region. 205This would allow optimizations of saving and restoring the state. 206.Sh AUTHORS 207The 208.Nm 209facitily and this manual page were written by 210.An Konstantin Belousov Aq Mt kib@FreeBSD.org . 211The arm64 support was added by 212.An Andrew Turner Aq Mt andrew@FreeBSD.org . 213