History

cxl/mem: Add basic IOCTL interface

Add a straightforward IOCTL that provides a mechanism for userspace to query the supported memory device commands. CXL commands as they appear to userspace are described as part of the UAPI kerneldoc. The command list returned via this IOCTL will contain the full set of commands that the driver supports, however, some of those commands may not be available for use by userspace. Memory device commands first appear in the CXL 2.0 specification. They are submitted through a mailbox mechanism specified in the CXL 2.0 specification. The send command allows userspace to issue mailbox commands directly to the hardware. The list of available commands to send are the output of the query command. The driver verifies basic properties of the command and possibly inspect the input (or output) payload to determine whether or not the command is allowed (or might taint the kernel).

Ben Widawsky committed 5 years ago

Commit 583fa5e1 parent b39cb105 files · +452 −1Browse files

Showing the changes to include/uapi (1 of 5 files). Show all

Unified · Split

include/uapi/linux/cxl_mem.h+156−0
@@ -0,0 +1,156 @@
1+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2+/*
3+ * CXL IOCTLs for Memory Devices
4+ */
5+
6+#ifndef _UAPI_CXL_MEM_H_
7+#define _UAPI_CXL_MEM_H_
8+
9+#include <linux/types.h>
10+
11+/**
12+ * DOC: UAPI
13+ *
14+ * Not all of all commands that the driver supports are always available for use
15+ * by userspace. Userspace must check the results from the QUERY command in
16+ * order to determine the live set of commands.
17+ */
18+
19+#define CXL_MEM_QUERY_COMMANDS _IOR(0xCE, 1, struct cxl_mem_query_commands)
20+#define CXL_MEM_SEND_COMMAND _IOWR(0xCE, 2, struct cxl_send_command)
21+
22+#define CXL_CMDS \
23+ ___C(INVALID, "Invalid Command"), \
24+ ___C(IDENTIFY, "Identify Command"), \
25+ ___C(MAX, "invalid / last command")
26+
27+#define ___C(a, b) CXL_MEM_COMMAND_ID_##a
28+enum { CXL_CMDS };
29+
30+#undef ___C
31+#define ___C(a, b) { b }
32+static const struct {
33+ const char *name;
34+} cxl_command_names[] = { CXL_CMDS };
35+
36+/*
37+ * Here's how this actually breaks out:
38+ * cxl_command_names[] = {
39+ * [CXL_MEM_COMMAND_ID_INVALID] = { "Invalid Command" },
40+ * [CXL_MEM_COMMAND_ID_IDENTIFY] = { "Identify Command" },
41+ * ...
42+ * [CXL_MEM_COMMAND_ID_MAX] = { "invalid / last command" },
43+ * };
44+ */
45+
46+#undef ___C
47+
48+/**
49+ * struct cxl_command_info - Command information returned from a query.
50+ * @id: ID number for the command.
51+ * @flags: Flags that specify command behavior.
52+ * @size_in: Expected input size, or -1 if variable length.
53+ * @size_out: Expected output size, or -1 if variable length.
54+ *
55+ * Represents a single command that is supported by both the driver and the
56+ * hardware. This is returned as part of an array from the query ioctl. The
57+ * following would be a command that takes a variable length input and returns 0
58+ * bytes of output.
59+ *
60+ * - @id = 10
61+ * - @flags = 0
62+ * - @size_in = -1
63+ * - @size_out = 0
64+ *
65+ * See struct cxl_mem_query_commands.
66+ */
67+struct cxl_command_info {
68+ __u32 id;
69+
70+ __u32 flags;
71+#define CXL_MEM_COMMAND_FLAG_MASK GENMASK(0, 0)
72+
73+ __s32 size_in;
74+ __s32 size_out;
75+};
76+
77+/**
78+ * struct cxl_mem_query_commands - Query supported commands.
79+ * @n_commands: In/out parameter. When @n_commands is > 0, the driver will
80+ * return min(num_support_commands, n_commands). When @n_commands
81+ * is 0, driver will return the number of total supported commands.
82+ * @rsvd: Reserved for future use.
83+ * @commands: Output array of supported commands. This array must be allocated
84+ * by userspace to be at least min(num_support_commands, @n_commands)
85+ *
86+ * Allow userspace to query the available commands supported by both the driver,
87+ * and the hardware. Commands that aren't supported by either the driver, or the
88+ * hardware are not returned in the query.
89+ *
90+ * Examples:
91+ *
92+ * - { .n_commands = 0 } // Get number of supported commands
93+ * - { .n_commands = 15, .commands = buf } // Return first 15 (or less)
94+ * supported commands
95+ *
96+ * See struct cxl_command_info.
97+ */
98+struct cxl_mem_query_commands {
99+ /*
100+ * Input: Number of commands to return (space allocated by user)
101+ * Output: Number of commands supported by the driver/hardware
102+ *
103+ * If n_commands is 0, kernel will only return number of commands and
104+ * not try to populate commands[], thus allowing userspace to know how
105+ * much space to allocate
106+ */
107+ __u32 n_commands;
108+ __u32 rsvd;
109+
110+ struct cxl_command_info __user commands[]; /* out: supported commands */
111+};
112+
113+/**
114+ * struct cxl_send_command - Send a command to a memory device.
115+ * @id: The command to send to the memory device. This must be one of the
116+ * commands returned by the query command.
117+ * @flags: Flags for the command (input).
118+ * @rsvd: Must be zero.
119+ * @retval: Return value from the memory device (output).
120+ * @in: Parameters associated with input payload.
121+ * @in.size: Size of the payload to provide to the device (input).
122+ * @in.rsvd: Must be zero.
123+ * @in.payload: Pointer to memory for payload input, payload is little endian.
124+ * @out: Parameters associated with output payload.
125+ * @out.size: Size of the payload received from the device (input/output). This
126+ * field is filled in by userspace to let the driver know how much
127+ * space was allocated for output. It is populated by the driver to
128+ * let userspace know how large the output payload actually was.
129+ * @out.rsvd: Must be zero.
130+ * @out.payload: Pointer to memory for payload output, payload is little endian.
131+ *
132+ * Mechanism for userspace to send a command to the hardware for processing. The
133+ * driver will do basic validation on the command sizes. In some cases even the
134+ * payload may be introspected. Userspace is required to allocate large enough
135+ * buffers for size_out which can be variable length in certain situations.
136+ */
137+struct cxl_send_command {
138+ __u32 id;
139+ __u32 flags;
140+ __u32 rsvd;
141+ __u32 retval;
142+
143+ struct {
144+ __s32 size;
145+ __u32 rsvd;
146+ __u64 payload;
147+ } in;
148+
149+ struct {
150+ __s32 size;
151+ __u32 rsvd;
152+ __u64 payload;
153+ } out;
154+};
155+
156+#endif