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
21 The FW layer in devices has grown to incredible size and devices frequently
26 The availability of such a flexible layer has created quite a variety in the
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
47 communicate via an RPC message layer constructed with a queue or mailbox scheme.
48 In this case the driver will typically have some layer to deliver RPC messages
49 and collect RPC responses from device FW. The in-kernel subsystem drivers that
53 operated by the block layer but also comes with a set of RPCs to administer the
65 layer of discovery and a generic uAPI to deliver the RPCs and collect the
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
209 subsystems are going to be sharing the same device and FW interface layer so the
223 and RPC layer belongs under fwctl with auxiliary devices connecting to other
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