| Message ID | 20250122235159.2716036-20-dave.jiang@intel.com |
|---|---|
| State | New |
| Headers | show |
| Series | cxl: Add CXL feature commands support via fwctl | expand |
Dave Jiang wrote: > Add policy and operational documentation for FWCTL CXL. > > Signed-off-by: Dave Jiang <dave.jiang@intel.com> > --- > .../userspace-api/fwctl/fwctl-cxl.rst | 81 +++++++++++++++++++ > Documentation/userspace-api/fwctl/index.rst | 1 + > 2 files changed, 82 insertions(+) > create mode 100644 Documentation/userspace-api/fwctl/fwctl-cxl.rst > > diff --git a/Documentation/userspace-api/fwctl/fwctl-cxl.rst b/Documentation/userspace-api/fwctl/fwctl-cxl.rst > new file mode 100644 > index 000000000000..f774bf2ecb5f > --- /dev/null > +++ b/Documentation/userspace-api/fwctl/fwctl-cxl.rst > @@ -0,0 +1,81 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +================ > +fwctl cxl driver > +================ > + > +:Author: Dave Jiang > + > +Overview > +======== > + > +The CXL spec defines a set of commands that can be issued to the mailbox of a > +CXL device or switch. It also left room for vendor specific commands to be > +issued to the mailbox as well. fwctl provides a path to issue a set of allowed > +mailbox commands from user space to the device moderated by the kernel driver. > + > +While there are a large set of mailbox commands, only the feature related > +commands will be allowed to be issued through fwctl initially. No background > +commands will be supported at this time. Just describe what the CXL FWTCTL for Features Interface is, not what it would/could be. Someone reading this doc on docs.kernel.org without access to git history is going to wonder what "initially", and "at this time" means. That's better changelog fodder, not interface documentation. > + > +CXL spec r3.1 8.2.9.6.1 Get Supported Features (Opcode 0500h) > +CXL spec r3.1 8.2.9.6.2 Get Feature (Opcode 0501h) > +CXL spec r3.1 8.2.9.6.3 Set Feature (Opcode 0502h) > + > +The "Get Supported Features" return data may be filtered by the kernel driver to > +drop any features that are forbidden by the kernel or being exclusively used by > +the kernel. The "Get Supported Features" command and the "Get Features" falls > +under the fwctl policy of FWCTL_RPC_CONFIGURATION. > + > +For "Set Feature" command, the access policy currently is broken down into two > +categories depending on the set feature effects reported by the device. If the Capitalize Set Feature throughout when it is reference a specification term. > +set feature will cause immediate change to the device, the fwctl access policy > +must be FWCTL_RPC_DEBUG_WRITE_FULL. The effects for this level are > +"immediate config change", "immediate data change", "immediate policy change", > +or "immediate log change" for the set effects mask. If the effects are "config > +change with cold reset" or "config change with conventional reset", then the > +fwctl access policy must be FWCTL_RPC_DEBUG_WRITE or higher. > + > +fwctl cxl User API > +================== > + > +.. kernel-doc:: include/uapi/fwctl/cxl.h > +.. kernel-doc:: include/uapi/cxl/features.h > + > +1. Driver info query > +-------------------- > + > +First step for the app is to issue the ioctl(FWCTL_CMD_INFO) in order to retrieve > +the information from the driver. A ``struct fwctl_info`` needs to be filled out > +with the ``fwctl_info.out_device_type`` set to ``FWCTL_DEVICE_TYPE_CXL``. The > +return data should be ``struct fwctl_info_cxl`` that contains a command mask > +that indicates which of the commands are supported by the driver. Per the code review, succesful invocation of the info command implies the Features capability is operational and returns an all zeros payload to indicate first generation interface support. > + > +2. Send hardware command > +------------------------ > + > +Next step is to send the 'Get Supported Features' command to the driver from > +user space via ioctl(FWCTL_RPC). A ``struct fwctl_rpc_cxl`` should be pointed to > +by ``fwctl_rpc.in``. ``struct fwctl_rpc_cxl.in_payload`` should point to > +the hardware input structure that is defined by the CXL spec. ``fwctl_rpc.out`` > +points to the buffer that contains a ``struct fwctl_rpc_cxl_out`` that includes > +the hardware output data inlined as ``fwctl_rpc_cxl_out.payload``. This command > +can be called twice. First time to retrieve the number of features supported. > +A second time to retrieve the specific feature details. Please convert this from passive to active voice. I.e. s/should be pointed to by/points to/ Some sample code to enumerat and issue a Get/Set Feature for a made up Feature UUID would be welcome here. > + > +After getting the specific feature details, a get/set feature command can be > +appropriately programmed and sent. For a "set feature" command, the retrieved > +feature info contains an effects field that details the resulting > +"set feature" command will trigger. That should inform the user whether > +the system is configured to allowed the "set feature" command or not. > + > +It is recommended to take a look at CXL CLI test directory for a detailed > +user code example on how to exercise this path. Should be small enough to copy here directly. Otherwise provide a URL directly to github or similar for someone reading this on docs.kernel.org. > + > +fwctl cxl Kernel API > +==================== > + > +.. kernel-doc:: drivers/cxl/core/features.c > +.. kernel-doc:: drivers/cxl/features.c > + :export: > +.. kernel-doc:: include/cxl/features.h > diff --git a/Documentation/userspace-api/fwctl/index.rst b/Documentation/userspace-api/fwctl/index.rst > index 06959fbf1547..d9d40a468a31 100644 > --- a/Documentation/userspace-api/fwctl/index.rst > +++ b/Documentation/userspace-api/fwctl/index.rst > @@ -10,3 +10,4 @@ to securely construct and execute RPCs inside device firmware. > :maxdepth: 1 > > fwctl > + fwctl-cxl > -- > 2.47.1 > >
diff --git a/Documentation/userspace-api/fwctl/fwctl-cxl.rst b/Documentation/userspace-api/fwctl/fwctl-cxl.rst new file mode 100644 index 000000000000..f774bf2ecb5f --- /dev/null +++ b/Documentation/userspace-api/fwctl/fwctl-cxl.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +fwctl cxl driver +================ + +:Author: Dave Jiang + +Overview +======== + +The CXL spec defines a set of commands that can be issued to the mailbox of a +CXL device or switch. It also left room for vendor specific commands to be +issued to the mailbox as well. fwctl provides a path to issue a set of allowed +mailbox commands from user space to the device moderated by the kernel driver. + +While there are a large set of mailbox commands, only the feature related +commands will be allowed to be issued through fwctl initially. No background +commands will be supported at this time. + +CXL spec r3.1 8.2.9.6.1 Get Supported Features (Opcode 0500h) +CXL spec r3.1 8.2.9.6.2 Get Feature (Opcode 0501h) +CXL spec r3.1 8.2.9.6.3 Set Feature (Opcode 0502h) + +The "Get Supported Features" return data may be filtered by the kernel driver to +drop any features that are forbidden by the kernel or being exclusively used by +the kernel. The "Get Supported Features" command and the "Get Features" falls +under the fwctl policy of FWCTL_RPC_CONFIGURATION. + +For "Set Feature" command, the access policy currently is broken down into two +categories depending on the set feature effects reported by the device. If the +set feature will cause immediate change to the device, the fwctl access policy +must be FWCTL_RPC_DEBUG_WRITE_FULL. The effects for this level are +"immediate config change", "immediate data change", "immediate policy change", +or "immediate log change" for the set effects mask. If the effects are "config +change with cold reset" or "config change with conventional reset", then the +fwctl access policy must be FWCTL_RPC_DEBUG_WRITE or higher. + +fwctl cxl User API +================== + +.. kernel-doc:: include/uapi/fwctl/cxl.h +.. kernel-doc:: include/uapi/cxl/features.h + +1. Driver info query +-------------------- + +First step for the app is to issue the ioctl(FWCTL_CMD_INFO) in order to retrieve +the information from the driver. A ``struct fwctl_info`` needs to be filled out +with the ``fwctl_info.out_device_type`` set to ``FWCTL_DEVICE_TYPE_CXL``. The +return data should be ``struct fwctl_info_cxl`` that contains a command mask +that indicates which of the commands are supported by the driver. + +2. Send hardware command +------------------------ + +Next step is to send the 'Get Supported Features' command to the driver from +user space via ioctl(FWCTL_RPC). A ``struct fwctl_rpc_cxl`` should be pointed to +by ``fwctl_rpc.in``. ``struct fwctl_rpc_cxl.in_payload`` should point to +the hardware input structure that is defined by the CXL spec. ``fwctl_rpc.out`` +points to the buffer that contains a ``struct fwctl_rpc_cxl_out`` that includes +the hardware output data inlined as ``fwctl_rpc_cxl_out.payload``. This command +can be called twice. First time to retrieve the number of features supported. +A second time to retrieve the specific feature details. + +After getting the specific feature details, a get/set feature command can be +appropriately programmed and sent. For a "set feature" command, the retrieved +feature info contains an effects field that details the resulting +"set feature" command will trigger. That should inform the user whether +the system is configured to allowed the "set feature" command or not. + +It is recommended to take a look at CXL CLI test directory for a detailed +user code example on how to exercise this path. + +fwctl cxl Kernel API +==================== + +.. kernel-doc:: drivers/cxl/core/features.c +.. kernel-doc:: drivers/cxl/features.c + :export: +.. kernel-doc:: include/cxl/features.h diff --git a/Documentation/userspace-api/fwctl/index.rst b/Documentation/userspace-api/fwctl/index.rst index 06959fbf1547..d9d40a468a31 100644 --- a/Documentation/userspace-api/fwctl/index.rst +++ b/Documentation/userspace-api/fwctl/index.rst @@ -10,3 +10,4 @@ to securely construct and execute RPCs inside device firmware. :maxdepth: 1 fwctl + fwctl-cxl
Add policy and operational documentation for FWCTL CXL. Signed-off-by: Dave Jiang <dave.jiang@intel.com> --- .../userspace-api/fwctl/fwctl-cxl.rst | 81 +++++++++++++++++++ Documentation/userspace-api/fwctl/index.rst | 1 + 2 files changed, 82 insertions(+) create mode 100644 Documentation/userspace-api/fwctl/fwctl-cxl.rst