fwctl-cxl.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3================
  4fwctl cxl driver
  5================
  6
  7:Author: Dave Jiang
  8
  9Overview
 10========
 11
 12The CXL spec defines a set of commands that can be issued to the mailbox of a
 13CXL device or switch. It also left room for vendor specific commands to be
 14issued to the mailbox as well. fwctl provides a path to issue a set of allowed
 15mailbox commands from user space to the device moderated by the kernel driver.
 16
 17The following 3 commands will be used to support CXL Features:
 18CXL spec r3.1 8.2.9.6.1 Get Supported Features (Opcode 0500h)
 19CXL spec r3.1 8.2.9.6.2 Get Feature (Opcode 0501h)
 20CXL spec r3.1 8.2.9.6.3 Set Feature (Opcode 0502h)
 21
 22The "Get Supported Features" return data may be filtered by the kernel driver to
 23drop any features that are forbidden by the kernel or being exclusively used by
 24the kernel. The driver will set the "Set Feature Size" of the "Get Supported
 25Features Supported Feature Entry" to 0 to indicate that the Feature cannot be
 26modified. The "Get Supported Features" command and the "Get Features" falls
 27under the fwctl policy of FWCTL_RPC_CONFIGURATION.
 28
 29For "Set Feature" command, the access policy currently is broken down into two
 30categories depending on the Set Feature effects reported by the device. If the
 31Set Feature will cause immediate change to the device, the fwctl access policy
 32must be FWCTL_RPC_DEBUG_WRITE_FULL. The effects for this level are
 33"immediate config change", "immediate data change", "immediate policy change",
 34or "immediate log change" for the set effects mask. If the effects are "config
 35change with cold reset" or "config change with conventional reset", then the
 36fwctl access policy must be FWCTL_RPC_DEBUG_WRITE or higher.
 37
 38fwctl cxl User API
 39==================
 40
 41.. kernel-doc:: include/uapi/fwctl/cxl.h
 42
 431. Driver info query
 44--------------------
 45
 46First step for the app is to issue the ioctl(FWCTL_CMD_INFO). Successful
 47invocation of the ioctl implies the Features capability is operational and
 48returns an all zeros 32bit payload. A ``struct fwctl_info`` needs to be filled
 49out with the ``fwctl_info.out_device_type`` set to ``FWCTL_DEVICE_TYPE_CXL``.
 50The return data should be ``struct fwctl_info_cxl`` that contains a reserved
 5132bit field that should be all zeros.
 52
 532. Send hardware commands
 54-------------------------
 55
 56Next step is to send the 'Get Supported Features' command to the driver from
 57user space via ioctl(FWCTL_RPC). A ``struct fwctl_rpc_cxl`` is pointed to
 58by ``fwctl_rpc.in``. ``struct fwctl_rpc_cxl.in_payload`` points to
 59the hardware input structure that is defined by the CXL spec. ``fwctl_rpc.out``
 60points to the buffer that contains a ``struct fwctl_rpc_cxl_out`` that includes
 61the hardware output data inlined as ``fwctl_rpc_cxl_out.payload``. This command
 62is called twice. First time to retrieve the number of features supported.
 63A second time to retrieve the specific feature details as the output data.
 64
 65After getting the specific feature details, a Get/Set Feature command can be
 66appropriately programmed and sent. For a "Set Feature" command, the retrieved
 67feature info contains an effects field that details the resulting
 68"Set Feature" command will trigger. That will inform the user whether
 69the system is configured to allowed the "Set Feature" command or not.
 70
 71Code example of a Get Feature
 72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 73
 74.. code-block:: c
 75
 76        static int cxl_fwctl_rpc_get_test_feature(int fd, struct test_feature *feat_ctx,
 77                                                  const uint32_t expected_data)
 78        {
 79                struct cxl_mbox_get_feat_in *feat_in;
 80                struct fwctl_rpc_cxl_out *out;
 81                struct fwctl_rpc rpc = {0};
 82                struct fwctl_rpc_cxl *in;
 83                size_t out_size, in_size;
 84                uint32_t val;
 85                void *data;
 86                int rc;
 87
 88                in_size = sizeof(*in) + sizeof(*feat_in);
 89                rc = posix_memalign((void **)&in, 16, in_size);
 90                if (rc)
 91                        return -ENOMEM;
 92                memset(in, 0, in_size);
 93                feat_in = &in->get_feat_in;
 94
 95                uuid_copy(feat_in->uuid, feat_ctx->uuid);
 96                feat_in->count = feat_ctx->get_size;
 97
 98                out_size = sizeof(*out) + feat_ctx->get_size;
 99                rc = posix_memalign((void **)&out, 16, out_size);
100                if (rc)
101                        goto free_in;
102                memset(out, 0, out_size);
103
104                in->opcode = CXL_MBOX_OPCODE_GET_FEATURE;
105                in->op_size = sizeof(*feat_in);
106
107                rpc.size = sizeof(rpc);
108                rpc.scope = FWCTL_RPC_CONFIGURATION;
109                rpc.in_len = in_size;
110                rpc.out_len = out_size;
111                rpc.in = (uint64_t)(uint64_t *)in;
112                rpc.out = (uint64_t)(uint64_t *)out;
113
114                rc = send_command(fd, &rpc, out);
115                if (rc)
116                        goto free_all;
117
118                data = out->payload;
119                val = le32toh(*(__le32 *)data);
120                if (memcmp(&val, &expected_data, sizeof(val)) != 0) {
121                        rc = -ENXIO;
122                        goto free_all;
123                }
124
125        free_all:
126                free(out);
127        free_in:
128                free(in);
129                return rc;
130        }
131
132Take a look at CXL CLI test directory
133<https://github.com/pmem/ndctl/tree/main/test/fwctl.c> for a detailed user code
134for examples on how to exercise this path.
135
136
137fwctl cxl Kernel API
138====================
139
140.. kernel-doc:: drivers/cxl/core/features.c
141   :export:
142.. kernel-doc:: include/cxl/features.h