1 .. SPDX-License-Identifier: GPL-2.0+ 1 .. SPDX-License-Identifier: GPL-2.0+
2 2
3 Floating-point API 3 Floating-point API
4 ================== 4 ==================
5 5
6 Kernel code is normally prohibited from using 6 Kernel code is normally prohibited from using floating-point (FP) registers or
7 instructions, including the C float and double 7 instructions, including the C float and double data types. This rule reduces
8 system call overhead, because the kernel does 8 system call overhead, because the kernel does not need to save and restore the
9 userspace floating-point register state. 9 userspace floating-point register state.
10 10
11 However, occasionally drivers or library funct 11 However, occasionally drivers or library functions may need to include FP code.
12 This is supported by isolating the functions c 12 This is supported by isolating the functions containing FP code to a separate
13 translation unit (a separate source file), and 13 translation unit (a separate source file), and saving/restoring the FP register
14 state around calls to those functions. This cr 14 state around calls to those functions. This creates "critical sections" of
15 floating-point usage. 15 floating-point usage.
16 16
17 The reason for this isolation is to prevent th 17 The reason for this isolation is to prevent the compiler from generating code
18 touching the FP registers outside these critic 18 touching the FP registers outside these critical sections. Compilers sometimes
19 use FP registers to optimize inlined ``memcpy` 19 use FP registers to optimize inlined ``memcpy`` or variable assignment, as
20 floating-point registers may be wider than gen 20 floating-point registers may be wider than general-purpose registers.
21 21
22 Usability of floating-point code within the ke 22 Usability of floating-point code within the kernel is architecture-specific.
23 Additionally, because a single kernel may be c 23 Additionally, because a single kernel may be configured to support platforms
24 both with and without a floating-point unit, F 24 both with and without a floating-point unit, FPU availability must be checked
25 both at build time and at run time. 25 both at build time and at run time.
26 26
27 Several architectures implement the generic ke 27 Several architectures implement the generic kernel floating-point API from
28 ``linux/fpu.h``, as described below. Some othe 28 ``linux/fpu.h``, as described below. Some other architectures implement their
29 own unique APIs, which are documented separate 29 own unique APIs, which are documented separately.
30 30
31 Build-time API 31 Build-time API
32 -------------- 32 --------------
33 33
34 Floating-point code may be built if the option 34 Floating-point code may be built if the option ``ARCH_HAS_KERNEL_FPU_SUPPORT``
35 is enabled. For C code, such code must be plac 35 is enabled. For C code, such code must be placed in a separate file, and that
36 file must have its compilation flags adjusted 36 file must have its compilation flags adjusted using the following pattern::
37 37
38 CFLAGS_foo.o += $(CC_FLAGS_FPU) 38 CFLAGS_foo.o += $(CC_FLAGS_FPU)
39 CFLAGS_REMOVE_foo.o += $(CC_FLAGS_NO_FPU) 39 CFLAGS_REMOVE_foo.o += $(CC_FLAGS_NO_FPU)
40 40
41 Architectures are expected to define one or bo 41 Architectures are expected to define one or both of these variables in their
42 top-level Makefile as needed. For example:: 42 top-level Makefile as needed. For example::
43 43
44 CC_FLAGS_FPU := -mhard-float 44 CC_FLAGS_FPU := -mhard-float
45 45
46 or:: 46 or::
47 47
48 CC_FLAGS_NO_FPU := -msoft-float 48 CC_FLAGS_NO_FPU := -msoft-float
49 49
50 Normal kernel code is assumed to use the equiv 50 Normal kernel code is assumed to use the equivalent of ``CC_FLAGS_NO_FPU``.
51 51
52 Runtime API 52 Runtime API
53 ----------- 53 -----------
54 54
55 The runtime API is provided in ``linux/fpu.h`` 55 The runtime API is provided in ``linux/fpu.h``. This header cannot be included
56 from files implementing FP code (those with th 56 from files implementing FP code (those with their compilation flags adjusted as
57 above). Instead, it must be included when defi 57 above). Instead, it must be included when defining the FP critical sections.
58 58
59 .. c:function:: bool kernel_fpu_available( voi 59 .. c:function:: bool kernel_fpu_available( void )
60 60
61 This function reports if floating-poin 61 This function reports if floating-point code can be used on this CPU or
62 platform. The value returned by this f 62 platform. The value returned by this function is not expected to change
63 at runtime, so it only needs to be cal 63 at runtime, so it only needs to be called once, not before every
64 critical section. 64 critical section.
65 65
66 .. c:function:: void kernel_fpu_begin( void ) 66 .. c:function:: void kernel_fpu_begin( void )
67 void kernel_fpu_end( void ) 67 void kernel_fpu_end( void )
68 68
69 These functions create a floating-poin 69 These functions create a floating-point critical section. It is only
70 valid to call ``kernel_fpu_begin()`` a 70 valid to call ``kernel_fpu_begin()`` after a previous call to
71 ``kernel_fpu_available()`` returned `` 71 ``kernel_fpu_available()`` returned ``true``. These functions are only
72 guaranteed to be callable from (preemp 72 guaranteed to be callable from (preemptible or non-preemptible) process
73 context. 73 context.
74 74
75 Preemption may be disabled inside crit 75 Preemption may be disabled inside critical sections, so their size
76 should be minimized. They are *not* re 76 should be minimized. They are *not* required to be reentrant. If the
77 caller expects to nest critical sectio 77 caller expects to nest critical sections, it must implement its own
78 reference counting. 78 reference counting.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.