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