Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

docs: Improve grammar in Userspace API/fwctl

Fix typos and improve grammar in the documentation for
fwctl subsystem.

Use the word user space consistently, instead of having
two variants (user space vs. userspace).

Change wording of denied behaviour to be disallowed
behaviour when describing the interface.

Reviewed-by: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Hanne-Lotta Mäenpää <hannelotta@gmail.com>
Link: https://lore.kernel.org/r/20250522115255.137450-3-hannelotta@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

authored by

Hanne-Lotta Mäenpää and committed by
Jonathan Corbet
b7833731 01167650

+15 -15
+15 -15
Documentation/userspace-api/fwctl/fwctl.rst
··· 54 54 construction of drives within the HW RAID. 55 55 56 56 In the past when devices were more single function, individual subsystems would 57 - grow different approaches to solving some of these common problems. For instance 57 + grow different approaches to solving some of these common problems. For instance, 58 58 monitoring device health, manipulating its FLASH, debugging the FW, 59 59 provisioning, all have various unique interfaces across the kernel. 60 60 ··· 87 87 3. Multiple VM functions tightly scoped within the VM 88 88 89 89 The device may create a logical parent/child relationship between these scopes. 90 - For instance a child VM's FW may be within the scope of the hypervisor FW. It is 90 + For instance, a child VM's FW may be within the scope of the hypervisor FW. It is 91 91 quite common in the VFIO world that the hypervisor environment has a complex 92 92 provisioning/profiling/configuration responsibility for the function VFIO 93 93 assigns to the VM. ··· 105 105 106 106 3. Write access to function & child debug information strictly compatible with 107 107 the principles of kernel lockdown and kernel integrity protection. Triggers 108 - a kernel Taint. 108 + a kernel taint. 109 109 110 - 4. Full debug device access. Triggers a kernel Taint, requires CAP_SYS_RAWIO. 110 + 4. Full debug device access. Triggers a kernel taint, requires CAP_SYS_RAWIO. 111 111 112 112 User space will provide a scope label on each RPC and the kernel must enforce the 113 113 above CAPs and taints based on that scope. A combination of kernel and FW can 114 114 enforce that RPCs are placed in the correct scope by user space. 115 115 116 - Denied behavior 117 - --------------- 116 + Disallowed behavior 117 + ------------------- 118 118 119 119 There are many things this interface must not allow user space to do (without a 120 - Taint or CAP), broadly derived from the principles of kernel lockdown. Some 120 + taint or CAP), broadly derived from the principles of kernel lockdown. Some 121 121 examples: 122 122 123 123 1. DMA to/from arbitrary memory, hang the system, compromise FW integrity with ··· 138 138 fwctl is not a replacement for device direct access subsystems like uacce or 139 139 VFIO. 140 140 141 - Operations exposed through fwctl's non-taining interfaces should be fully 142 - sharable with other users of the device. For instance exposing a RPC through 141 + Operations exposed through fwctl's non-tainting interfaces should be fully 142 + sharable with other users of the device. For instance, exposing a RPC through 143 143 fwctl should never prevent a kernel subsystem from also concurrently using that 144 144 same RPC or hardware unit down the road. In such cases fwctl will be less 145 145 important than proper kernel subsystems that eventually emerge. Mistakes in this ··· 225 225 226 226 Each device type must be mindful of Linux's philosophy for stable ABI. The FW 227 227 RPC interface does not have to meet a strictly stable ABI, but it does need to 228 - meet an expectation that userspace tools that are deployed and in significant 228 + meet an expectation that user space tools that are deployed and in significant 229 229 use don't needlessly break. FW upgrade and kernel upgrade should keep widely 230 230 deployed tooling working. 231 231 232 232 Development and debugging focused RPCs under more permissive scopes can have 233 - less stabilitiy if the tools using them are only run under exceptional 233 + less stability if the tools using them are only run under exceptional 234 234 circumstances and not for every day use of the device. Debugging tools may even 235 235 require exact version matching as they may require something similar to DWARF 236 236 debug information from the FW binary. ··· 261 261 - HW RAID controllers. This includes RPCs to do things like compose drives into 262 262 a RAID volume, configure RAID parameters, monitor the HW and more. 263 263 264 - - Baseboard managers. RPCs for configuring settings in the device and more 264 + - Baseboard managers. RPCs for configuring settings in the device and more. 265 265 266 266 - NVMe vendor command capsules. nvme-cli provides access to some monitoring 267 267 functions that different products have defined, but more exist. ··· 269 269 - CXL also has a NVMe-like vendor command system. 270 270 271 271 - DRM allows user space drivers to send commands to the device via kernel 272 - mediation 272 + mediation. 273 273 274 274 - RDMA allows user space drivers to directly push commands to the device 275 - without kernel involvement 275 + without kernel involvement. 276 276 277 277 - Various “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc. 278 278 279 279 The first 4 are examples of areas that fwctl intends to cover. The latter three 280 - are examples of denied behavior as they fully overlap with the primary purpose 280 + are examples of disallowed behavior as they fully overlap with the primary purpose 281 281 of a kernel subsystem. 282 282 283 283 Some key lessons learned from these past efforts are the importance of having a