Re: [RFC PATCH v2 20/20] fwctl/cxl: Add documentation to FWCTL CXL

[Dave Jiang <dave.jiang@intel.com>]

On 11/22/24 8:26 AM, Jonathan Cameron wrote:
> On Fri, 15 Nov 2024 14:25:53 -0700
> Dave Jiang <dave.jiang@intel.com> wrote:
> 
>> Add policy and operational documentation for FWCTL CXL.
>>
>> Signed-off-by: Dave Jiang <dave.jiang@intel.com>
>> ---
>>  .../userspace-api/fwctl/fwctl-cxl.rst         | 91 +++++++++++++++++++
>>  Documentation/userspace-api/fwctl/index.rst   |  1 +
>>  2 files changed, 92 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..158e9aa45609
>> --- /dev/null
>> +++ b/Documentation/userspace-api/fwctl/fwctl-cxl.rst
>> @@ -0,0 +1,91 @@
>> +.. 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 Featuers" command falls under the fwctl policy
> spell check. Features
> 
>> +of FWCTL_RPC_CONFIGURATION.
> As per earlier feedback I think we need to reject get/set even if they are not
> listed in get supported features so that bad userspace doesn't get away
> with sending them anyway.  This is particularly necessary as I suspect we'll
> be removing features in the long run from what we let be accessed this way.
> 
> I'm not sure how we document the potential for removal of a feature that
> was reported by an earlier kernel.

Userspace should query the driver for whatever features that are "available". Given one feature may exist for a device while another does not? So maybe the expectation from the app should be feature does not exist unless reported by the driver that it exists. 

> 
> Jonathan
> 
> 
> 
>