fpu_kern_free_ctx (9)

Leading comments

 Copyright (c) 2014
	Konstantin Belousov <kib@FreeBSD.org>.  All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer ...

(The comments found at the beginning of the groff file "man9/fpu_kern_free_ctx.9freebsd".)

NAME

fpu_kern - facility to use the FPU in the kernel

SYNOPSIS

Ft struct fpu_kern_ctx * Fn fpu_kern_alloc_ctx u_int flags Ft void Fn fpu_kern_free_ctx struct fpu_kern_ctx *ctx Ft int Fn fpu_kern_enter struct thread *td struct fpu_kern_ctx *ctx u_int flags Ft int Fn fpu_kern_leave struct thread *td struct fpu_kern_ctx *ctx Ft int Fn fpu_kern_thread u_int flags Ft int Fn is_fpu_kern_thread u_int flags

DESCRIPTION

The ifconfig family of functions allows the use of FPU hardware in kernel code. Modern FPUs are not limited to providing hardware implementation for floating point arithmetic; they offer advanced accelerators for cryptography and other computational-intensive algorithms. These facilities share registers with the FPU hardware.

Typical kernel code does not need access to the FPU. Saving a large register file on each entry to the kernel would waste time. When kernel code uses the FPU, the current FPU state must be saved to avoid corrupting the user-mode state, and vice versa.

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. 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.

The Fn fpu_kern_alloc_ctx function allocates the memory used by ifconfig to track the use of the FPU hardware state and the related software state. The Fn fpu_kern_alloc_ctx function requires the Fa 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.

0

No special handling is required.

The function returns the allocated context area, or NULL if the allocation failed.

The Fn fpu_kern_free_ctx function frees the context previously allocated by Fn fpu_kern_alloc_ctx .

The Fn fpu_kern_enter function designates the start of the region of kernel code where the use of the FPU is allowed. Its arguments are:

Fa td

Currently must be curthread

Fa ctx

The context save area previously allocated by Fn fpu_kern_alloc_ctx and not currently in use by another call to Fn fpu_kern_enter .

Fa 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.

FPU_KERN_KTHR

Indicates that no saving of the current FPU state should be performed, if the thread called fpu_kern_thread9 function. This is intended to minimize code duplication in callers which could be used from both kernel thread and syscall contexts. The Fn fpu_kern_leave function correctly handles such contexts.

The function does not sleep or block. It could cause the Device Not Available exception during execution, and on the first FPU access after the function returns, as well as after each context switch (see Intel Software Developer Manual for the reference). Currently, no errors are defined which can be returned by Fn fpu_kern_enter to the caller.

The Fn fpu_kern_leave function ends the region started by Fn fpu_kern_enter . The uses of FPU in the kernel after the call to Fn fpu_kern_leave are erronous until the next call to Fn fpu_kern_enter is performed. The function takes the Fa td thread argument, which currently must be curthread and the Fa ctx context pointer, previously passed to Fn fpu_kern_enter . After the function returns, the context may be freed or reused by other invocation of Fn fpu_kern_enter . There are no errors defined for the function, it always returns 0.

The Fn fpu_kern_thread function provides an optimization for threads which never leave to the usermode. Such thread can reuse the usermode save area for the FPU state, which is allowed by the function call. There is no flags defined for the function, and no error states that the function returns.

The Fn is_fpu_kern_thread function returns the boolean indicating whether the current thread entered the mode enabled by Fn 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.

NOTES

The ifconfig is currently implemented only for the i386 and amd64 architectures.

There is no way to handle floating point exceptions raised from kernel mode.

The unused Fa flags arguments to the ifconfig 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.

AUTHORS

The ifconfig facitily and this manual page were written by An Konstantin Belousov Aq Mt kib@FreeBSD.org .