Debian Codegraph @

Documentation/userspace-api/fwctl/fwctl-cxl.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ================
4 fwctl cxl driver
5 ================
6
7 :Author: Dave Jiang
8
9 Overview
10 ========
11
12 The CXL spec defines a set of commands that can be issued to the mailbox of a
13 CXL device or switch. It also left room for vendor specific commands to be
14 issued to the mailbox as well. fwctl provides a path to issue a set of allowed
15 mailbox commands from user space to the device moderated by the kernel driver.
16
17 The following 3 commands will be used to support CXL Features:
18 CXL spec r3.1 8.2.9.6.1 Get Supported Features (Opcode 0500h)
19 CXL spec r3.1 8.2.9.6.2 Get Feature (Opcode 0501h)
20 CXL spec r3.1 8.2.9.6.3 Set Feature (Opcode 0502h)
21
22 The "Get Supported Features" return data may be filtered by the kernel driver to
23 drop any features that are forbidden by the kernel or being exclusively used by
24 the kernel. The driver will set the "Set Feature Size" of the "Get Supported
25 Features Supported Feature Entry" to 0 to indicate that the Feature cannot be
26 modified. The "Get Supported Features" command and the "Get Features" falls
27 under the fwctl policy of FWCTL_RPC_CONFIGURATION.
28
29 For "Set Feature" command, the access policy currently is broken down into two
30 categories depending on the Set Feature effects reported by the device. If the
31 Set Feature will cause immediate change to the device, the fwctl access policy
32 must be FWCTL_RPC_DEBUG_WRITE_FULL. The effects for this level are
33 "immediate config change", "immediate data change", "immediate policy change",
34 or "immediate log change" for the set effects mask. If the effects are "config
35 change with cold reset" or "config change with conventional reset", then the
36 fwctl access policy must be FWCTL_RPC_DEBUG_WRITE or higher.
37
38 fwctl cxl User API
39 ==================
40
41 .. kernel-doc:: include/uapi/fwctl/cxl.h
42
43 1. Driver info query
44 --------------------
45
46 First step for the app is to issue the ioctl(FWCTL_CMD_INFO). Successful
47 invocation of the ioctl implies the Features capability is operational and
48 returns an all zeros 32bit payload. A ``struct fwctl_info`` needs to be filled
49 out with the ``fwctl_info.out_device_type`` set to ``FWCTL_DEVICE_TYPE_CXL``.
50 The return data should be ``struct fwctl_info_cxl`` that contains a reserved
51 32bit field that should be all zeros.
52
53 2. Send hardware commands
54 -------------------------
55
56 Next step is to send the 'Get Supported Features' command to the driver from
57 user space via ioctl(FWCTL_RPC). A ``struct fwctl_rpc_cxl`` is pointed to
58 by ``fwctl_rpc.in``. ``struct fwctl_rpc_cxl.in_payload`` points to
59 the hardware input structure that is defined by the CXL spec. ``fwctl_rpc.out``
60 points to the buffer that contains a ``struct fwctl_rpc_cxl_out`` that includes
61 the hardware output data inlined as ``fwctl_rpc_cxl_out.payload``. This command
62 is called twice. First time to retrieve the number of features supported.
63 A second time to retrieve the specific feature details as the output data.
64
65 After getting the specific feature details, a Get/Set Feature command can be
66 appropriately programmed and sent. For a "Set Feature" command, the retrieved
67 feature info contains an effects field that details the resulting
68 "Set Feature" command will trigger. That will inform the user whether
69 the system is configured to allowed the "Set Feature" command or not.
70
71 Code 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
132 Take a look at CXL CLI test directory
133 <https://github.com/pmem/ndctl/tree/main/test/fwctl.c> for a detailed user code
134 for examples on how to exercise this path.
135
136
137 fwctl cxl Kernel API
138 ====================
139
140 .. kernel-doc:: drivers/cxl/core/features.c
141 :export:
142 .. kernel-doc:: include/cxl/features.h