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

[Jonathan Cameron <Jonathan.Cameron@huawei.com>]

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.

Jonathan