FPU_KERN(9)

💖 FPU_KERN 💖

ok so bestie, welcome to fpu_kern(9) — it's the Kernel Developer's Manual page for the facility that lets you use the FPU in the kernel. yes, the FPU, in the kernel, we're doing this 🫶

---

✨ NAME ✨

fpu_kern — the facility to use the FPU in the kernel. that's it, that's the vibe 💅

---

✨ SYNOPSIS ✨

struct fpu_kern_ctx *
fpu_kern_alloc_ctx(u_int flags);

void
fpu_kern_free_ctx(struct fpu_kern_ctx *ctx);

void
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 ✨

so the fpu_kern family of functions is literally the whole squad that lets kernel code use FPU hardware. and ngl, modern FPUs are NOT just doing floating point arithmetic anymore — they're out here offering advanced accelerators for cryptography and other computational-intensive algorithms, main character energy fr. the catch? all these facilities share registers with the FPU hardware. sharing is caring until it isn't 😭

ok so typical kernel code does not need access to the FPU. saving a big register file on every single entry to the kernel would just waste time, and we don't do that. but the moment kernel code does use the FPU, the current FPU state must be saved to avoid corrupting the user-mode state, and vice versa. it goes both ways bestie 🔄

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. so what do you actually have to do? 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. that's the whole job 💅

---

🎀 fpu_kern_alloc_ctx()

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. it 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. no waiting, we're busy 🏃♀️
• 0 — no special handling is required. the "just vibing" option 🌸

the function returns the allocated context area, or NULL if the allocation failed. (yes, check it. please. 🙈)

---

🎀 fpu_kern_free_ctx()

the fpu_kern_free_ctx() function frees the context previously allocated by fpu_kern_alloc_ctx(). give it back, it's not yours anymore ✨

---

🎀 fpu_kern_enter()

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(). don't share, it's not that kind of party 🚫
• 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. like, mandatory, no skipping 👑
  • FPU_KERN_KTHR — indicates that no saving of the current FPU state should be performed, if the thread called the 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. so like, one code path for two situations, we love efficiency 💖
  • 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. so, short and sweet, or the latency tax comes for you 💀

the function does not sleep or block. it could cause an FPU trap during execution, and on the first FPU access after the function returns, as well as after each context switch. on i386 and amd64 this will be the Device Not Available exception (see Intel Software Developer Manual for the reference). yeah, that's a real exception name, we don't make the rules 😭

---

🎀 fpu_kern_leave()

the fpu_kern_leave() function ends the region started by fpu_kern_enter().

⚠️ it is erroneous to use the FPU in the kernel before fpu_kern_enter() or after fpu_kern_leave(). do not do this. seriously. 🙅♀️

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 another invocation of fpu_kern_enter(). the function always returns 0. always. no drama, no surprises, we love that for us 🫶

---

🎀 fpu_kern_thread()

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. iconic behavior honestly ✨

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. permanent FPU access, it's giving main character 🌟

---

🎀 is_fpu_kern_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. a little vibe check for your thread 💅

---

✨ NOTES ✨

• the fpu_kern is currently implemented only for the i386, amd64, and arm64 architectures. if you're on something else, sorry bestie 😭
• there is no way to handle floating point exceptions raised from kernel mode. none. zero. it's just not happening. 💀
• 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. future glow-up pending ⏳✨

---

✨ AUTHORS ✨

the fpu_kern facitily and this manual page were written by Konstantin Belousov <kib@FreeBSD.org>. the arm64 support was added by Andrew Turner <andrew@FreeBSD.org>. absolute legends, we stan 👑💖

---

✨ BUGS ✨

• fpu_kern_leave() should probably have type void (like fpu_kern_enter()). yeah. it just should. 🙈

---

ok that's the whole page bestie, you're officially FPU-kernel-pilled 💅✨

this one's from the Debian edition of the Kernel Developer's Manual, dated March 7, 2018 — mwah, take care of her 🎀