userspace-api/fwctl/fwctl.rst

1 .. SPDX-License-Identifier: GPL-2.0
13 software-defined pieces of hardware. The evolution of this approach is largely a
27 industry where single pieces of silicon are now configurable software-defined
33 Further, devices have become multi-functional and integrated to the point they
35 multi-functional devices have drivers, such as bnxt/ice/mlx5/pds, that span many
40 have an expansive FW environment that needs robust device-specific debugging
41 support, and FW-driven functionality that is not well suited to “generic”
43 user space in the areas of debuggability, management, and first-boot/nth-boot
49 and collect RPC responses from device FW. The in-kernel subsystem drivers that
70 ---------------
76 fwctl instances must operate on a well-defined device function, and the device
77 should have a well-defined security model for what scope within the physical
79 device today may broadly have several function-level scopes:
81  1. A privileged function with full access to the on-device global state and
100     transparent or non-disruptive to any driver or VM.
102  2. Read-only access to function debug information that may report on FW objects
117 ---------------
141 Operations exposed through fwctl's non-taining interfaces should be fully
151 .. kernel-doc:: include/uapi/fwctl/fwctl.h
152 .. kernel-doc:: include/uapi/fwctl/mlx5.h
153 .. kernel-doc:: include/uapi/fwctl/pds.h
156 -----------
175 --------------------
177 Drawing inspiration from nvme-cli, participating in the kernel side must come
179 kernel driver. Providing such an implementation is a pre-condition to merging a
186  - Device in-field debugging
188  - HW provisioning
190  - VFIO child device profiling before VM boot
192  - Confidential Compute topics (attestation, secure provisioning)
195 how an excellent user space experience can emerge out of kernel-side diversity.
200 .. kernel-doc:: drivers/fwctl/main.c
202 .. kernel-doc:: include/linux/fwctl.h
205 -------------------
207 In many cases a fwctl driver is going to be part of a larger cross-subsystem
261  - HW RAID controllers. This includes RPCs to do things like compose drives into
264  - Baseboard managers. RPCs for configuring settings in the device and more
266  - NVMe vendor command capsules. nvme-cli provides access to some monitoring
269  - CXL also has a NVMe-like vendor command system.
271  - DRM allows user space drivers to send commands to the device via kernel
274  - RDMA allows user space drivers to directly push commands to the device
277  - Various “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc.
284 common user space project to use as a pre-condition for obtaining a kernel