Debian Codegraph @

src/nvme/mi.h

raw
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 /*
3 * This file is part of libnvme.
4 * Copyright (c) 2021 Code Construct Pty Ltd
5 *
6 * Authors: Jeremy Kerr <[email protected]>
7 */
8
9 /**
10 * DOC: mi.h - NVMe Management Interface library (libnvme-mi) definitions.
11 *
12 * These provide an abstraction for the MI messaging between controllers
13 * and a host, typically over an MCTP-over-i2c link to a NVMe device, used
14 * as part of the out-of-band management of a system.
15 *
16 * We have a few data structures define here to reflect the topology
17 * of a MI connection with an NVMe subsystem:
18 *
19 * - &nvme_mi_ep_t: an MI endpoint - our mechanism of communication with a
20 * NVMe subsystem. For MCTP, an endpoint will be the component that
21 * holds the MCTP address (EID), and receives our request message.
22 *
23 * endpoints are defined in the NVMe-MI spec, and are specific to the MI
24 * interface.
25 *
26 * Each endpoint will provide access to one or more of:
27 *
28 * - &nvme_mi_ctrl_t: a NVMe controller, as defined by the NVMe base spec.
29 * The controllers are responsible for processing any NVMe standard
30 * commands (eg, the Admin command set). An endpoint (&nvme_mi_ep_t)
31 * may provide access to multiple controllers - so each of the controller-
32 * type commands will require a &nvme_mi_ctrl_t to be specified, rather than
33 * an endpoint
34 *
35 * A couple of conventions with the libnvme-mi API:
36 *
37 * - All types and functions have the nvme_mi prefix, to distinguish from
38 * the libnvme core.
39 *
40 * - We currently support either MI commands and Admin commands. The
41 * former adds a _mi prefix, the latter an _admin prefix. [This does
42 * result in the MI functions having a double _mi, like
43 * &nvme_mi_mi_subsystem_health_status_poll, which is apparently amusing
44 * for our German-speaking readers]
45 *
46 * For return values: unless specified in the per-function documentation,
47 * all functions:
48 *
49 * - return 0 on success
50 *
51 * - return -1, with errno set, for errors communicating with the MI device,
52 * either in request or response data
53 *
54 * - return >1 on MI status errors. This value is the 8-bit MI status
55 * value, represented by &enum nvme_mi_resp_status. Note that the
56 * status values may be vendor-defined above 0xe0.
57 *
58 * For the second case, we have a few conventions for errno values:
59 *
60 * - EPROTO: response data violated the MI protocol, and libnvme cannot
61 * validly interpret the response
62 *
63 * - EIO: Other I/O error communicating with device (eg., valid but
64 * unexpected response data)
65 *
66 * - EINVAL: invalid input arguments for a command
67 *
68 * In line with the core NVMe API, the Admin command functions take an
69 * `_args` structure to provide the command-specific parameters. However,
70 * for the MI interface, the fd and timeout members of these _args structs
71 * are ignored.
72 *
73 * References to the specifications here will either to be the NVM Express
74 * Management Interface ("NVMe-MI") or the NVM Express Base specification
75 * ("NVMe"). At the time of writing, the versions we're referencing here
76 * are:
77 * - NVMe-MI 1.2b
78 * - NVMe 2.0b
79 * with a couple of accommodations for older spec types, particularly NVMe-MI
80 * 1.1, where possible.
81 *
82 */
83
84 #ifndef _LIBNVME_MI_MI_H
85 #define _LIBNVME_MI_MI_H
86
87 #include <endian.h>
88 #include <stdint.h>
89
90 #include <nvme/types.h>
91 #include <nvme/tree.h>
92
93 /**
94 * NVME_MI_MSGTYPE_NVME - MCTP message type for NVMe-MI messages.
95 *
96 * This is defined by MCTP, but is referenced as part of the NVMe-MI message
97 * spec. This is the MCTP NVMe message type (0x4), with the message-integrity
98 * bit (0x80) set.
99 */
100 #define NVME_MI_MSGTYPE_NVME 0x84
101
102 /* Basic MI message definitions */
103
104 /**
105 * enum nvme_mi_message_type - NVMe-MI message type field.
106 * @NVME_MI_MT_CONTROL: NVME-MI Control Primitive
107 * @NVME_MI_MT_MI: NVMe-MI command
108 * @NVME_MI_MT_ADMIN: NVMe Admin command
109 * @NVME_MI_MT_PCIE: PCIe command
110 * @NVME_MI_MT_AE: Asynchronous Event
111 *
112 * Used as byte 1 of both request and response messages (NMIMT bits of NMP
113 * byte). Not to be confused with the MCTP message type in byte 0.
114 */
115 enum nvme_mi_message_type {
116 NVME_MI_MT_CONTROL = 0,
117 NVME_MI_MT_MI = 1,
118 NVME_MI_MT_ADMIN = 2,
119 NVME_MI_MT_PCIE = 4,
120 NVME_MI_MT_AE = 5,
121 };
122
123 /**
124 * enum nvme_mi_ror: Request or response field.
125 * @NVME_MI_ROR_REQ: request message
126 * @NVME_MI_ROR_RSP: response message
127 */
128 enum nvme_mi_ror {
129 NVME_MI_ROR_REQ = 0,
130 NVME_MI_ROR_RSP = 1,
131 };
132
133 /**
134 * enum nvme_mi_resp_status - values for the response status field
135 * @NVME_MI_RESP_SUCCESS: success
136 * @NVME_MI_RESP_MPR: More Processing Required
137 * @NVME_MI_RESP_INTERNAL_ERR: Internal Error
138 * @NVME_MI_RESP_INVALID_OPCODE: Invalid command opcode
139 * @NVME_MI_RESP_INVALID_PARAM: Invalid command parameter
140 * @NVME_MI_RESP_INVALID_CMD_SIZE: Invalid command size
141 * @NVME_MI_RESP_INVALID_INPUT_SIZE: Invalid command input data size
142 * @NVME_MI_RESP_ACCESS_DENIED: Access Denied
143 * @NVME_MI_RESP_VPD_UPDATES_EXCEEDED: More VPD updates than allowed
144 * @NVME_MI_RESP_PCIE_INACCESSIBLE: PCIe functionality currently unavailable
145 * @NVME_MI_RESP_MEB_SANITIZED: MEB has been cleared due to sanitize
146 * @NVME_MI_RESP_ENC_SERV_FAILURE: Enclosure services process failed
147 * @NVME_MI_RESP_ENC_SERV_XFER_FAILURE: Transfer with enclosure services failed
148 * @NVME_MI_RESP_ENC_FAILURE: Unreoverable enclosure failure
149 * @NVME_MI_RESP_ENC_XFER_REFUSED: Enclosure services transfer refused
150 * @NVME_MI_RESP_ENC_FUNC_UNSUP: Unsupported enclosure services function
151 * @NVME_MI_RESP_ENC_SERV_UNAVAIL: Enclosure services unavailable
152 * @NVME_MI_RESP_ENC_DEGRADED: Noncritical failure detected by enc. services
153 * @NVME_MI_RESP_SANITIZE_IN_PROGRESS: Command prohibited during sanitize
154 */
155 enum nvme_mi_resp_status {
156 NVME_MI_RESP_SUCCESS = 0x00,
157 NVME_MI_RESP_MPR = 0x01,
158 NVME_MI_RESP_INTERNAL_ERR = 0x02,
159 NVME_MI_RESP_INVALID_OPCODE = 0x03,
160 NVME_MI_RESP_INVALID_PARAM = 0x04,
161 NVME_MI_RESP_INVALID_CMD_SIZE = 0x05,
162 NVME_MI_RESP_INVALID_INPUT_SIZE = 0x06,
163 NVME_MI_RESP_ACCESS_DENIED = 0x07,
164 /* 0x08 - 0x1f: reserved */
165 NVME_MI_RESP_VPD_UPDATES_EXCEEDED = 0x20,
166 NVME_MI_RESP_PCIE_INACCESSIBLE = 0x21,
167 NVME_MI_RESP_MEB_SANITIZED = 0x22,
168 NVME_MI_RESP_ENC_SERV_FAILURE = 0x23,
169 NVME_MI_RESP_ENC_SERV_XFER_FAILURE = 0x24,
170 NVME_MI_RESP_ENC_FAILURE = 0x25,
171 NVME_MI_RESP_ENC_XFER_REFUSED = 0x26,
172 NVME_MI_RESP_ENC_FUNC_UNSUP = 0x27,
173 NVME_MI_RESP_ENC_SERV_UNAVAIL = 0x28,
174 NVME_MI_RESP_ENC_DEGRADED = 0x29,
175 NVME_MI_RESP_SANITIZE_IN_PROGRESS = 0x2a,
176 /* 0x2b - 0xdf: reserved */
177 /* 0xe0 - 0xff: vendor specific */
178 };
179
180 /**
181 * struct nvme_mi_msg_hdr - General MI message header.
182 * @type: MCTP message type, will always be NVME_MI_MSGTYPE_NVME
183 * @nmp: NVMe-MI message parameters (including MI message type)
184 * @meb: Management Endpoint Buffer flag; unused for libnvme-mi implementation
185 * @rsvd0: currently reserved
186 *
187 * Wire format shared by both request and response messages, per NVMe-MI
188 * section 3.1. This is used for all message types, MI and Admin.
189 */
190 struct nvme_mi_msg_hdr {
191 __u8 type;
192 __u8 nmp;
193 __u8 meb;
194 __u8 rsvd0;
195 } __attribute__((packed));
196
197 /**
198 * struct nvme_mi_msg_resp - Generic response type.
199 * @hdr: the general request/response message header
200 * @status: response status value (see &enum nvme_mi_resp_status)
201 * @rsvd0: reserved data, may be defined by specific response
202 *
203 * Every response will start with one of these; command-specific responses
204 * will define parts of the reserved data, and may add further fields.
205 */
206 struct nvme_mi_msg_resp {
207 struct nvme_mi_msg_hdr hdr;
208 __u8 status;
209 __u8 rsvd0[3];
210 };
211
212 /**
213 * enum nvme_mi_mi_opcode - Operation code for supported NVMe-MI commands.
214 * @nvme_mi_mi_opcode_mi_data_read: Read NVMe-MI Data Structure
215 * @nvme_mi_mi_opcode_subsys_health_status_poll: Subsystem Health Status Poll
216 * @nvme_mi_mi_opcode_configuration_set: MI Configuration Set
217 * @nvme_mi_mi_opcode_configuration_get: MI Configuration Get
218 */
219 enum nvme_mi_mi_opcode {
220 nvme_mi_mi_opcode_mi_data_read = 0x00,
221 nvme_mi_mi_opcode_subsys_health_status_poll = 0x01,
222 nvme_mi_mi_opcode_configuration_set = 0x03,
223 nvme_mi_mi_opcode_configuration_get = 0x04,
224 };
225
226 /**
227 * struct nvme_mi_mi_req_hdr - MI request message header.
228 * @hdr: generic MI message header
229 * @opcode: opcode (OPC) for the specific MI command
230 * @rsvd0: reserved bytes
231 * @cdw0: Management Request Doubleword 0 - command specific usage
232 * @cdw1: Management Request Doubleword 1 - command specific usage
233 *
234 * Wire format for MI request message headers, defined in section 5 of NVMe-MI.
235 */
236 struct nvme_mi_mi_req_hdr {
237 struct nvme_mi_msg_hdr hdr;
238 __u8 opcode;
239 __u8 rsvd0[3];
240 __le32 cdw0, cdw1;
241 };
242
243 /**
244 * struct nvme_mi_mi_resp_hdr - MI response message header.
245 * @hdr: generic MI message header
246 * @status: generic response status from command; non-zero on failure.
247 * @nmresp: NVMe Management Response: command-type-specific response data
248 *
249 * Wire format for MI response message header, defined in section 5 of NVMe-MI.
250 */
251 struct nvme_mi_mi_resp_hdr {
252 struct nvme_mi_msg_hdr hdr;
253 __u8 status;
254 __u8 nmresp[3];
255 };
256
257 /**
258 * enum nvme_mi_dtyp - Data Structure Type field.
259 * @nvme_mi_dtyp_subsys_info: NVM Subsystem Information
260 * @nvme_mi_dtyp_port_info: Port information
261 * @nvme_mi_dtyp_ctrl_list: Controller List
262 * @nvme_mi_dtyp_ctrl_info: Controller Information
263 * @nvme_mi_dtyp_opt_cmd_support: Optionally Supported Command List
264 * @nvme_mi_dtyp_meb_support: Management Endpoint Buffer Command Support List
265 *
266 * Data Structure Type field for Read NVMe-MI Data Structure command, used to
267 * indicate the particular structure to query from the endpoint.
268 */
269 enum nvme_mi_dtyp {
270 nvme_mi_dtyp_subsys_info = 0x00,
271 nvme_mi_dtyp_port_info = 0x01,
272 nvme_mi_dtyp_ctrl_list = 0x02,
273 nvme_mi_dtyp_ctrl_info = 0x03,
274 nvme_mi_dtyp_opt_cmd_support = 0x04,
275 nvme_mi_dtyp_meb_support = 0x05,
276 };
277
278 /**
279 * enum nvme_mi_config_id - NVMe-MI Configuration identifier.
280 * @NVME_MI_CONFIG_SMBUS_FREQ: Current SMBus/I2C frequency
281 * @NVME_MI_CONFIG_HEALTH_STATUS_CHANGE: Health Status change - used to clear
282 * health status bits in CCS bits of
283 * status poll. Only for Set ops.
284 * @NVME_MI_CONFIG_MCTP_MTU: MCTP maximum transmission unit size of port
285 * specified in dw 0
286 * @NVME_MI_CONFIG_AE: Asynchronous Events configuration
287 * Configuration parameters for the MI Get/Set Configuration commands.
288 *
289 * See &nvme_mi_mi_config_get() and &nvme_mi_config_set().
290 */
291 enum nvme_mi_config_id {
292 NVME_MI_CONFIG_SMBUS_FREQ = 0x1,
293 NVME_MI_CONFIG_HEALTH_STATUS_CHANGE = 0x2,
294 NVME_MI_CONFIG_MCTP_MTU = 0x3,
295 NVME_MI_CONFIG_AE = 0x4,
296 };
297
298 /**
299 * enum nvme_mi_config_smbus_freq - SMBus/I2C frequency values
300 * @NVME_MI_CONFIG_SMBUS_FREQ_100kHz: 100kHz
301 * @NVME_MI_CONFIG_SMBUS_FREQ_400kHz: 400kHz
302 * @NVME_MI_CONFIG_SMBUS_FREQ_1MHz: 1MHz
303 *
304 * Values used in the SMBus Frequency device configuration. See
305 * &nvme_mi_mi_config_get_smbus_freq() and &nvme_mi_mi_config_set_smbus_freq().
306 */
307 enum nvme_mi_config_smbus_freq {
308 NVME_MI_CONFIG_SMBUS_FREQ_100kHz = 0x1,
309 NVME_MI_CONFIG_SMBUS_FREQ_400kHz = 0x2,
310 NVME_MI_CONFIG_SMBUS_FREQ_1MHz = 0x3,
311 };
312
313 /* Asynchronous Event Message definitions*/
314
315 /**
316 * struct nvme_mi_aem_supported_list_header - Asynchronous Event Supported List Header.
317 * @numaes: Number of AE supported data structures that follow the header
318 * @aeslver: AE Supported List Version
319 * @aest: AE Supported list length (including this header)
320 * @aeslhl: AE Supported list header length
321 *
322 * This header preceeds a number, (&numaes), of AE supported data structures
323 */
324 struct nvme_mi_aem_supported_list_header {
325 __u8 numaes;
326 __u8 aeslver;//Should be zero
327 __le16 aest;
328 __u8 aeslhl; //Should be 5
329 } __attribute__((packed));
330
331 /**
332 * struct nvme_mi_aem_supported_item - AE Supported List Item
333 * @aesl: AE supported list item length
334 * @aesi: AE supported info
335 *
336 * Following this header should be hdr.numaes entries of
337 * nvme_mi_aem_supported_item structures
338 */
339 struct nvme_mi_aem_supported_item {
340 __u8 aesl;//Length of this item. Set to 3
341 __le16 aesi;
342 } __attribute__((packed));
343
344 /**
345 * nvme_mi_aem_aesi_get_aese() - return aese from aesi field
346 * @aesi: aesi field from @nvme_mi_aem_supported_item
347 *
348 * Returns: A bool representing the aese value
349 */
350 bool nvme_mi_aem_aesi_get_aese(__le16 aesi);
351
352 /**
353 * nvme_mi_aem_aesi_get_aesid() - return aesid from aesi field
354 * @aesi: aesi field from @nvme_mi_aem_supported_item
355 *
356 * Returns: aesid value
357 */
358 __u8 nvme_mi_aem_aesi_get_aesid(__le16 aesi);
359
360 /**
361 * nvme_mi_aem_aesi_set_aesid() - set aesid in the aesi field
362 * @item: Pointer to @nvme_mi_aem_supported_item to update the aesi field
363 * @aesid: aesid value to use
364 */
365 void nvme_mi_aem_aesi_set_aesid(struct nvme_mi_aem_supported_item *item, __u8 aesid);
366
367 /**
368 * nvme_mi_aem_aesi_set_aee() - set aee in the aesi field
369 * @item: Pointer to @nvme_mi_aem_supported_item to update the aesi field
370 * @enabled: aee value to use
371 */
372 void nvme_mi_aem_aesi_set_aee(struct nvme_mi_aem_supported_item *item, bool enabled);
373
374 /**
375 * struct nvme_mi_aem_supported_list - AE Supported List received with GET CONFIG Asynchronous Event
376 * @hdr: AE supported list header
377 *
378 * Following this header should be hdr.numaes entries of
379 * nvme_mi_aem_supported_item structures
380 */
381 struct nvme_mi_aem_supported_list {
382 struct nvme_mi_aem_supported_list_header hdr;
383 } __attribute__((packed));
384
385 /**
386 * struct nvme_mi_aem_enable_item - AE Enabled item entry
387 * @aeel: AE Enable Length (length of this structure which is 3)
388 * @aeei: AE Enable Info
389 *
390 */
391 struct nvme_mi_aem_enable_item {
392 __u8 aeel;
393 __le16 aeei;
394 } __attribute__((packed));
395
396 /**
397 * nvme_mi_aem_aeei_get_aee() - return aee from aeei field
398 * @aeei: aeei field from @nvme_mi_aem_enable_item
399 *
400 * Returns: aee value
401 */
402 bool nvme_mi_aem_aeei_get_aee(__le16 aeei);
403
404 /**
405 * nvme_mi_aem_aeei_get_aeeid() - return aeeid from aeei field
406 * @aeei: aeei field from @nvme_mi_aem_enable_item
407 *
408 * Returns: aeeid value
409 */
410 __u8 nvme_mi_aem_aeei_get_aeeid(__le16 aeei);
411
412 /**
413 * nvme_mi_aem_aeei_set_aeeid() - set aeeid in the aeei field
414 * @item: Pointer to @nvme_mi_aem_enable_item to update the aeei field
415 * @aeeid: aeeid value to use
416 */
417 void nvme_mi_aem_aeei_set_aeeid(struct nvme_mi_aem_enable_item *item, __u8 aeeid);
418
419 /**
420 * nvme_mi_aem_aeei_set_aee() - set aee in the aeei field
421 * @item: Pointer to @nvme_mi_aem_enable_item to update the aee field
422 * @enabled: aee value to use
423 */
424 void nvme_mi_aem_aeei_set_aee(struct nvme_mi_aem_enable_item *item, bool enabled);
425
426 /**
427 * struct nvme_mi_aem_enable_list_header - AE Enable list header
428 * @numaee: Number of AE enable items following the header
429 * @aeelver: Version of the AE enable list (zero)
430 * @aeetl: Total length of the AE enable list including header and items
431 * @aeelhl: Header length of this header (5)
432 */
433 struct nvme_mi_aem_enable_list_header {
434 __u8 numaee;
435 __u8 aeelver;
436 __le16 aeetl;
437 __u8 aeelhl;
438 } __attribute__((packed));
439
440 /**
441 * struct nvme_mi_aem_enable_list - AE enable list sent with SET CONFIG Asyncronous Event
442 * @hdr: AE enable list header
443 *
444 * Following this header should be hdr.numaee entries of nvme_mi_aem_enable_item structures
445 */
446 struct nvme_mi_aem_enable_list {
447 struct nvme_mi_aem_enable_list_header hdr;
448 } __attribute__((packed));
449
450 /**
451 * struct nvme_mi_aem_occ_data - AEM Message definition.
452 * @aelhlen: AE Occurrence Header Length
453 * @aeosil: AE Occurrence Specific Info Length
454 * @aeovsil: AE Occurrence Vendor Specific Info Length
455 * @aeoui: AE Occurrence Unique ID made up of other subfields
456 *
457 * A single entry of ae occurrence data that comes with an nvme_aem_msg.
458 * Following this structure is variable length AEOSI (occurrence specific
459 * info) and variable length AEVSI (vendor specific info). The length of
460 * AEOSI is specified by aeosil and the length of AEVSI is specified by
461 * AEVSI. Neither field is mandatory and shall be omitted if their length
462 * parameter is set to zero.
463 */
464 struct nvme_mi_aem_occ_data {
465 __u8 aelhlen;
466 __u8 aeosil;
467 __u8 aeovsil;
468 struct {
469 __u8 aeoi;
470 __le32 aeocidi;
471 __u8 aessi;
472 } __attribute__((packed)) aeoui;
473 } __attribute__((packed));
474
475 /**
476 * struct nvme_mi_aem_occ_list_hdr - AE occurrence list header
477 * @numaeo: Number of AE Occurrence Data Structures
478 * @aelver: AE Occurrence List Version Number
479 * @aeolli: AE Occurrence List Length Info (AEOLLI)
480 * @aeolhl: AE Occurrence List Header Length (shall be set to 7)
481 * @aemti: AEM Transmission Info
482 *
483 * The header for the occurrence list. numaeo defines how many
484 * nvme_mi_aem_occ_data structures (including variable payaloads) are included.
485 * Following this header is each of the numaeo occurrence data structures.
486 */
487 struct nvme_mi_aem_occ_list_hdr {
488 __u8 numaeo;
489 __u8 aelver;
490 __u8 aeolli[3];//24-bits
491 __u8 aeolhl;
492 __u8 aemti;
493 } __attribute__((packed));
494
495 /**
496 * nvme_mi_aem_aemti_get_aemgn() - return aemgn from aemti field
497 * @aemti: aemti field from @nvme_mi_aem_occ_list_hdr
498 *
499 * Returns: aemgn value
500 */
501 __u8 nvme_mi_aem_aemti_get_aemgn(__u8 aemti);
502
503 /**
504 * nvme_mi_aem_aeolli_get_aeoltl() - return aeoltl from aeolli field
505 * @aeolli: Pointer to 3 byte aeolli field from @nvme_mi_aem_occ_list_hdr
506 *
507 * Returns: aeoltl value
508 */
509 __u32 nvme_mi_aem_aeolli_get_aeoltl(__u8 *aeolli);
510
511 /**
512 * nvme_mi_aem_aeolli_set_aeoltl() - set aeoltl in the aeolli field
513 * @hdr:Pointer to @nvme_mi_aem_occ_list_hdr to set the aeolli field
514 * @aeoltl: aeoltl value to use
515 */
516 void nvme_mi_aem_aeolli_set_aeoltl(struct nvme_mi_aem_occ_list_hdr *hdr, __u32 aeoltl);
517
518 /**
519 * struct nvme_mi_aem_msg - AEM Message definition.
520 * @hdr: the general response message header
521 * @occ_list_hdr: ae occurrence list header.
522 *
523 * Every ae message will start with one of these. The occ_list_hder wil define
524 * information about how many ae occ data entries are included. Each entry is
525 * defined by the nvme_mi_aem_occ_data structure which will follow the
526 * occ_list_hdr. Each nvme_mi_aem_occ_data structure has a fixed length header
527 * but a variable length payload ude to occurrence specific and vendor specific
528 * info. For this reason, do not index the nvme_mi_ae_occ data structures by
529 * array or fixed offset.
530 */
531 struct nvme_mi_aem_msg {
532 struct nvme_mi_msg_hdr hdr;
533 struct nvme_mi_aem_occ_list_hdr occ_list_hdr;
534 } __attribute__((packed));
535
536 /* Admin command definitions */
537
538 /**
539 * struct nvme_mi_admin_req_hdr - Admin command request header.
540 * @hdr: Generic MI message header
541 * @opcode: Admin command opcode (using enum nvme_admin_opcode)
542 * @flags: Command Flags, indicating dlen and doff validity; Only defined in
543 * NVMe-MI version 1.1, no fields defined in 1.2 (where the dlen/doff
544 * are always considered valid).
545 * @ctrl_id: Controller ID target of command
546 * @cdw1: Submission Queue Entry doubleword 1
547 * @cdw2: Submission Queue Entry doubleword 2
548 * @cdw3: Submission Queue Entry doubleword 3
549 * @cdw4: Submission Queue Entry doubleword 4
550 * @cdw5: Submission Queue Entry doubleword 5
551 * @doff: Offset of data to return from command
552 * @dlen: Length of sent/returned data
553 * @rsvd0: Reserved
554 * @rsvd1: Reserved
555 * @cdw10: Submission Queue Entry doubleword 10
556 * @cdw11: Submission Queue Entry doubleword 11
557 * @cdw12: Submission Queue Entry doubleword 12
558 * @cdw13: Submission Queue Entry doubleword 13
559 * @cdw14: Submission Queue Entry doubleword 14
560 * @cdw15: Submission Queue Entry doubleword 15
561 *
562 * Wire format for Admin command message headers, defined in section 6 of
563 * NVMe-MI.
564 */
565 struct nvme_mi_admin_req_hdr {
566 struct nvme_mi_msg_hdr hdr;
567 __u8 opcode;
568 __u8 flags;
569 __le16 ctrl_id;
570 __le32 cdw1, cdw2, cdw3, cdw4, cdw5;
571 __le32 doff;
572 __le32 dlen;
573 __le32 rsvd0, rsvd1;
574 __le32 cdw10, cdw11, cdw12, cdw13, cdw14, cdw15;
575 } __attribute((packed));
576
577 /**
578 * struct nvme_mi_admin_resp_hdr - Admin command response header.
579 * @hdr: Generic MI message header
580 * @status: Generic response code, non-zero on failure
581 * @rsvd0: Reserved
582 * @cdw0: Completion Queue Entry doubleword 0
583 * @cdw1: Completion Queue Entry doubleword 1
584 * @cdw3: Completion Queue Entry doubleword 3
585 *
586 * This is the generic response format with the three doublewords of completion
587 * queue data, plus optional response data.
588 */
589 struct nvme_mi_admin_resp_hdr {
590 struct nvme_mi_msg_hdr hdr;
591 __u8 status;
592 __u8 rsvd0[3];
593 __le32 cdw0, cdw1, cdw3;
594 } __attribute__((packed));
595
596 /**
597 * enum nvme_mi_control_opcode - Operation code for Control Primitives.
598 * @nvme_mi_control_opcode_pause: Suspend response transmission/timeout
599 * @nvme_mi_control_opcode_resume: Resume from a paused condition
600 * @nvme_mi_control_opcode_abort: Re-initialize a Command Slot to the Idle state
601 * @nvme_mi_control_opcode_get_state: Get the state of a Command Slot
602 * @nvme_mi_control_opcode_replay: Retransmit the Response Message
603 */
604 enum nvme_mi_control_opcode {
605 nvme_mi_control_opcode_pause = 0x00,
606 nvme_mi_control_opcode_resume = 0x01,
607 nvme_mi_control_opcode_abort = 0x02,
608 nvme_mi_control_opcode_get_state = 0x03,
609 nvme_mi_control_opcode_replay = 0x04,
610 };
611
612 /**
613 * struct nvme_mi_control_req - The Control Primitive request.
614 * @hdr: Generic MI message header
615 * @opcode: Control Primitive Opcodes (using &enum nvme_mi_control_opcode)
616 * @tag: flag - Opaque value passed from request to response
617 * @cpsp: Control Primitive Specific Parameter
618 *
619 */
620 struct nvme_mi_control_req {
621 struct nvme_mi_msg_hdr hdr;
622 __u8 opcode;
623 __u8 tag;
624 __le16 cpsp;
625 } __attribute((packed));
626
627 /** struct nvme_mi_control_resp - The Control Primitive response.
628 * @hdr: Generic MI message header
629 * @status: Generic response code, non-zero on failure
630 * @tag: flag - Opaque value passed from request to response
631 * @cpsr: Control Primitive Specific Response
632 *
633 */
634
635 struct nvme_mi_control_resp {
636 struct nvme_mi_msg_hdr hdr;
637 __u8 status;
638 __u8 tag;
639 __le16 cpsr;
640 } __attribute((packed));
641
642 /**
643 * nvme_mi_status_to_string() - return a string representation of the MI
644 * status.
645 * @status: MI response status
646 *
647 * Gives a string description of @status, as per section 4.1.2 of the NVMe-MI
648 * spec. The status value should be of type NVME_STATUS_MI, and extracted
649 * from the return value using nvme_status_get_value().
650 *
651 * Returned string is const, and should not be free()ed.
652 *
653 * Returns: A string representing the status value
654 */
655 const char *nvme_mi_status_to_string(int status);
656
657 /**
658 * nvme_mi_create_root() - Create top-level MI (root) handle.
659 * @fp: File descriptor for logging messages
660 * @log_level: Logging level to use
661 *
662 * Create the top-level (library) handle for creating subsequent endpoint
663 * objects. Similar to nvme_create_root(), but we provide this to allow linking
664 * without the core libnvme.
665 *
666 * Return: new root object, or NULL on failure.
667 *
668 * See &nvme_create_root.
669 */
670 nvme_root_t nvme_mi_create_root(FILE *fp, int log_level);
671
672 /**
673 * nvme_mi_free_root() - Free root object.
674 * @root: root to free
675 */
676 void nvme_mi_free_root(nvme_root_t root);
677
678 /**
679 * nvme_mi_set_probe_enabled() - enable/disable the probe for new endpoints
680 * @root: &nvme_root_t object
681 * @enabled: whether to probe new endpoints
682 *
683 * Controls whether newly-created endpoints are probed for quirks on creation.
684 * Defaults to enabled, which results in some initial messaging with the
685 * endpoint to determine model-specific details.
686 */
687 void nvme_mi_set_probe_enabled(nvme_root_t root, bool enabled);
688
689 /* Top level management object: NVMe-MI Management Endpoint */
690 struct nvme_mi_ep;
691
692 /**
693 * typedef nvme_mi_ep_t - MI Endpoint object.
694 *
695 * Represents our communication endpoint on the remote MI-capable device.
696 * To be used for direct MI commands for the endpoint (through the
697 * nvme_mi_mi_* functions(), or to communicate with individual controllers
698 * (see &nvme_mi_init_ctrl).
699 *
700 * Endpoints are created through a transport-specific constructor; currently
701 * only MCTP-connected endpoints are supported, through &nvme_mi_open_mctp.
702 * Subsequent operations on the endpoint (and related controllers) are
703 * transport-independent.
704 */
705 typedef struct nvme_mi_ep * nvme_mi_ep_t;
706
707 /**
708 * nvme_mi_set_csi - Assign a CSI to an endpoint.
709 * @ep: Endpoint
710 * @csi: value to use for CSI bit in NMP (0 or 1) for this endpoint
711 *
712 * Return: 0 if successful, -1 otherwise (some endpoints may not support)
713 *
714 */
715 int nvme_mi_set_csi(nvme_mi_ep_t ep, uint8_t csi);
716
717 /**
718 * nvme_mi_first_endpoint - Start endpoint iterator
719 * @m: &nvme_root_t object
720 *
721 * Return: first MI endpoint object under this root, or NULL if no endpoints
722 * are present.
723 *
724 * See: &nvme_mi_next_endpoint, &nvme_mi_for_each_endpoint
725 */
726 nvme_mi_ep_t nvme_mi_first_endpoint(nvme_root_t m);
727
728 /**
729 * nvme_mi_next_endpoint - Continue endpoint iterator
730 * @m: &nvme_root_t object
731 * @e: &nvme_mi_ep_t current position of iterator
732 *
733 * Return: next endpoint MI endpoint object after @e under this root, or NULL
734 * if no further endpoints are present.
735 *
736 * See: &nvme_mi_first_endpoint, &nvme_mi_for_each_endpoint
737 */
738 nvme_mi_ep_t nvme_mi_next_endpoint(nvme_root_t m, nvme_mi_ep_t e);
739
740 /**
741 * nvme_mi_for_each_endpoint - Iterator for NVMe-MI endpoints.
742 * @m: &nvme_root_t containing endpoints
743 * @e: &nvme_mi_ep_t object, set on each iteration
744 */
745 #define nvme_mi_for_each_endpoint(m, e) \
746 for (e = nvme_mi_first_endpoint(m); e != NULL; \
747 e = nvme_mi_next_endpoint(m, e))
748
749 /**
750 * nvme_mi_for_each_endpoint_safe - Iterator for NVMe-MI endpoints, allowing
751 * deletion during traversal
752 * @m: &nvme_root_t containing endpoints
753 * @e: &nvme_mi_ep_t object, set on each iteration
754 * @_e: &nvme_mi_ep_t object used as temporary storage
755 */
756 #define nvme_mi_for_each_endpoint_safe(m, e, _e) \
757 for (e = nvme_mi_first_endpoint(m), _e = nvme_mi_next_endpoint(m, e); \
758 e != NULL; \
759 e = _e, _e = nvme_mi_next_endpoint(m, e))
760
761 /**
762 * nvme_mi_ep_set_timeout - set a timeout for NVMe-MI responses
763 * @ep: MI endpoint object
764 * @timeout_ms: Timeout for MI responses, given in milliseconds
765 */
766 int nvme_mi_ep_set_timeout(nvme_mi_ep_t ep, unsigned int timeout_ms);
767
768 /**
769 * nvme_mi_ep_set_mprt_max - set the maximum wait time for a More Processing
770 * Required response
771 * @ep: MI endpoint object
772 * @mprt_max_ms: Maximum more processing required wait time
773 *
774 * NVMe-MI endpoints may respond to a request with a "More Processing Required"
775 * response; this also includes a hint on the worst-case processing time for
776 * the eventual response data, with a specification-defined maximum of 65.535
777 * seconds.
778 *
779 * This function provides a way to limit the maximum time we're prepared to
780 * wait for the final response. Specify zero in @mprt_max_ms for no limit.
781 * This should be larger than the command/response timeout set in
782 * &nvme_mi_ep_set_timeout().
783 */
784 void nvme_mi_ep_set_mprt_max(nvme_mi_ep_t ep, unsigned int mprt_max_ms);
785
786 /**
787 * nvme_mi_ep_get_timeout - get the current timeout value for NVMe-MI responses
788 * @ep: MI endpoint object
789 *
790 * Returns the current timeout value, in milliseconds, for this endpoint.
791 */
792 unsigned int nvme_mi_ep_get_timeout(nvme_mi_ep_t ep);
793
794 struct nvme_mi_ctrl;
795
796 /**
797 * typedef nvme_mi_ctrl_t - NVMe-MI Controller object.
798 *
799 * Provides NVMe command functionality, through the MI interface.
800 */
801 typedef struct nvme_mi_ctrl * nvme_mi_ctrl_t;
802
803 /**
804 * nvme_mi_first_ctrl - Start controller iterator
805 * @ep: &nvme_mi_ep_t object
806 *
807 * Return: first MI controller object under this root, or NULL if no controllers
808 * are present.
809 *
810 * See: &nvme_mi_next_ctrl, &nvme_mi_for_each_ctrl
811 */
812 nvme_mi_ctrl_t nvme_mi_first_ctrl(nvme_mi_ep_t ep);
813
814 /**
815 * nvme_mi_next_ctrl - Continue ctrl iterator
816 * @ep: &nvme_mi_ep_t object
817 * @c: &nvme_mi_ctrl_t current position of iterator
818 *
819 * Return: next MI controller object after @c under this endpoint, or NULL
820 * if no further controllers are present.
821 *
822 * See: &nvme_mi_first_ctrl, &nvme_mi_for_each_ctrl
823 */
824 nvme_mi_ctrl_t nvme_mi_next_ctrl(nvme_mi_ep_t ep, nvme_mi_ctrl_t c);
825
826 /**
827 * nvme_mi_for_each_ctrl - Iterator for NVMe-MI controllers.
828 * @ep: &nvme_mi_ep_t containing endpoints
829 * @c: &nvme_mi_ctrl_t object, set on each iteration
830 *
831 * Allows iteration of the list of controllers behind an endpoint. Unless the
832 * controllers have already been created explicitly, you'll probably want to
833 * call &nvme_mi_scan_ep() to scan for the controllers first.
834 *
835 * See: &nvme_mi_scan_ep()
836 */
837 #define nvme_mi_for_each_ctrl(ep, c) \
838 for (c = nvme_mi_first_ctrl(ep); c != NULL; \
839 c = nvme_mi_next_ctrl(ep, c))
840
841 /**
842 * nvme_mi_for_each_ctrl_safe - Iterator for NVMe-MI controllers, allowing
843 * deletion during traversal
844 * @ep: &nvme_mi_ep_t containing controllers
845 * @c: &nvme_mi_ctrl_t object, set on each iteration
846 * @_c: &nvme_mi_ctrl_t object used as temporary storage
847 *
848 * Allows iteration of the list of controllers behind an endpoint, safe against
849 * deletion during iteration. Unless the controllers have already been created
850 * explicitly (or you're just iterating to destroy controllers) you'll probably
851 * want to call &nvme_mi_scan_ep() to scan for the controllers first.
852 *
853 * See: &nvme_mi_scan_ep()
854 */
855 #define nvme_mi_for_each_ctrl_safe(ep, c, _c) \
856 for (c = nvme_mi_first_ctrl(ep), _c = nvme_mi_next_ctrl(ep, c); \
857 c != NULL; \
858 c = _c, _c = nvme_mi_next_ctrl(ep, c))
859
860 /**
861 * nvme_mi_open_mctp() - Create an endpoint using a MCTP connection.
862 * @root: root object to create under
863 * @netid: MCTP network ID on this system
864 * @eid: MCTP endpoint ID
865 *
866 * Transport-specific endpoint initialization for MI-connected endpoints. Once
867 * an endpoint is created, the rest of the API is transport-independent.
868 *
869 * Return: New endpoint object for @netid & @eid, or NULL on failure.
870 *
871 * See &nvme_mi_close
872 */
873 nvme_mi_ep_t nvme_mi_open_mctp(nvme_root_t root, unsigned int netid, uint8_t eid);
874
875 /**
876 * nvme_mi_aem_open() - Prepare an existing endpoint to receive AEMs
877 * @ep: Endpoint to configure for AEMs
878 *
879 * Return: 0 if success, -1 otherwise
880 */
881 int nvme_mi_aem_open(nvme_mi_ep_t ep);
882
883 /**
884 * nvme_mi_close() - Close an endpoint connection and release resources,
885 * including controller objects.
886 *
887 * @ep: Endpoint object to close
888 */
889 void nvme_mi_close(nvme_mi_ep_t ep);
890
891 /**
892 * nvme_mi_scan_mctp - look for MCTP-connected NVMe-MI endpoints.
893 *
894 * Description: This function queries the system MCTP daemon ("mctpd") over
895 * D-Bus, to find MCTP endpoints that report support for NVMe-MI over MCTP.
896 *
897 * This requires libvnme-mi to be compiled with D-Bus support; if not, this
898 * will return NULL.
899 *
900 * Return: A @nvme_root_t populated with a set of MCTP-connected endpoints,
901 * or NULL on failure
902 */
903 nvme_root_t nvme_mi_scan_mctp(void);
904
905 /**
906 * nvme_mi_scan_ep - query an endpoint for its NVMe controllers.
907 * @ep: Endpoint to scan
908 * @force_rescan: close existing controllers and rescan
909 *
910 * This function queries an MI endpoint for the controllers available, by
911 * performing an MI Read MI Data Structure command (requesting the
912 * controller list). The controllers are stored in the endpoint's internal
913 * list, and can be iterated with nvme_mi_for_each_ctrl.
914 *
915 * This will only scan the endpoint once, unless @force_rescan is set. If
916 * so, all existing controller objects will be freed - the caller must not
917 * hold a reference to those across this call.
918 *
919 * Return: The nvme command status if a response was received (see
920 * &enum nvme_status_field) or -1 with errno set otherwise.
921 *
922 * See: &nvme_mi_for_each_ctrl
923 */
924 int nvme_mi_scan_ep(nvme_mi_ep_t ep, bool force_rescan);
925
926 /**
927 * nvme_mi_init_ctrl() - initialise a NVMe controller.
928 * @ep: Endpoint to create under
929 * @ctrl_id: ID of controller to initialize.
930 *
931 * Create a connection to a controller behind the endpoint specified in @ep.
932 * Controller IDs may be queried from the endpoint through
933 * &nvme_mi_mi_read_mi_data_ctrl_list.
934 *
935 * Return: New controller object, or NULL on failure.
936 *
937 * See &nvme_mi_close_ctrl
938 */
939 nvme_mi_ctrl_t nvme_mi_init_ctrl(nvme_mi_ep_t ep, __u16 ctrl_id);
940
941 /**
942 * nvme_mi_close_ctrl() - free a controller
943 * @ctrl: controller to free
944 */
945 void nvme_mi_close_ctrl(nvme_mi_ctrl_t ctrl);
946
947 /**
948 * nvme_mi_ctrl_id() - get the ID of a controller
949 * @ctrl: controller to query
950 *
951 * Retrieve the ID of the controller, as defined by hardware, and available
952 * in the Identify (Controller List) data. This is the value passed to
953 * @nvme_mi_init_ctrl, but may have been created internally via
954 * @nvme_mi_scan_ep.
955 *
956 * Return: the (locally-stored) ID of this controller.
957 */
958 __u16 nvme_mi_ctrl_id(nvme_mi_ctrl_t ctrl);
959
960
961 /**
962 * nvme_mi_endpoint_desc - Get a string describing a MI endpoint.
963 * @ep: endpoint to describe
964 *
965 * Generates a human-readable string describing the endpoint, with possibly
966 * transport-specific data. The string is allocated during the call, and the
967 * caller is responsible for free()-ing the string.
968 *
969 * Return: a newly-allocated string containing the endpoint description, or
970 * NULL on failure.
971 */
972 char *nvme_mi_endpoint_desc(nvme_mi_ep_t ep);
973
974 /* MI Command API: nvme_mi_mi_ prefix */
975
976 /**
977 * nvme_mi_mi_xfer() - Raw mi transfer interface.
978 * @ep: endpoint to send the MI command to
979 * @mi_req: request data
980 * @req_data_size: size of request data payload
981 * @mi_resp: buffer for response data
982 * @resp_data_size: size of response data buffer, updated to received size
983 *
984 * Performs an arbitrary NVMe MI command, using the provided request data,
985 * in @mi_req. The size of the request data *payload* is specified in
986 * @req_data_size - this does not include the standard header length (so a
987 * header-only request would have a size of 0). Note that the Management
988 * Request Doublewords are considered part of the header data.
989 *
990 * On success, response data is stored in @mi_resp, which has an optional
991 * appended payload buffer of @resp_data_size bytes. The actual payload
992 * size transferred will be stored in @resp_data_size. This size does not
993 * include the MI response header, so 0 represents no payload.
994 *
995 * See: &struct nvme_mi_mi_req_hdr and &struct nvme_mi_mi_resp_hdr.
996 *
997 * Return: The nvme command status if a response was received (see
998 * &enum nvme_status_field) or -1 with errno set otherwise..
999 */
1000 int nvme_mi_mi_xfer(nvme_mi_ep_t ep,
1001 struct nvme_mi_mi_req_hdr *mi_req,
1002 size_t req_data_size,
1003 struct nvme_mi_mi_resp_hdr *mi_resp,
1004 size_t *resp_data_size);
1005
1006 /**
1007 * nvme_mi_mi_read_mi_data_subsys() - Perform a Read MI Data Structure command,
1008 * retrieving subsystem data.
1009 * @ep: endpoint for MI communication
1010 * @s: subsystem information to populate
1011 *
1012 * Retrieves the Subsystem information - number of external ports and
1013 * NVMe version information. See &struct nvme_mi_read_nvm_ss_info.
1014 *
1015 * Return: The nvme command status if a response was received (see
1016 * &enum nvme_status_field) or -1 with errno set otherwise..
1017 */
1018 int nvme_mi_mi_read_mi_data_subsys(nvme_mi_ep_t ep,
1019 struct nvme_mi_read_nvm_ss_info *s);
1020
1021 /**
1022 * nvme_mi_mi_read_mi_data_port() - Perform a Read MI Data Structure command,
1023 * retrieving port data.
1024 * @ep: endpoint for MI communication
1025 * @portid: id of port data to retrieve
1026 * @p: port information to populate
1027 *
1028 * Retrieves the Port information, for the specified port ID. The subsystem
1029 * data (from &nvme_mi_mi_read_mi_data_subsys) nmp field contains the allowed
1030 * range of port IDs.
1031 *
1032 * See &struct nvme_mi_read_port_info.
1033 *
1034 * Return: The nvme command status if a response was received (see
1035 * &enum nvme_status_field) or -1 with errno set otherwise..
1036 */
1037 int nvme_mi_mi_read_mi_data_port(nvme_mi_ep_t ep, __u8 portid,
1038 struct nvme_mi_read_port_info *p);
1039
1040 /**
1041 * nvme_mi_mi_read_mi_data_ctrl_list() - Perform a Read MI Data Structure
1042 * command, retrieving the list of attached controllers.
1043 * @ep: endpoint for MI communication
1044 * @start_ctrlid: starting controller ID
1045 * @list: controller list to populate
1046 *
1047 * Retrieves the list of attached controllers, with IDs greater than or
1048 * equal to @start_ctrlid.
1049 *
1050 * See &struct nvme_ctrl_list.
1051 *
1052 * Return: The nvme command status if a response was received (see
1053 * &enum nvme_status_field) or -1 with errno set otherwise..
1054 */
1055 int nvme_mi_mi_read_mi_data_ctrl_list(nvme_mi_ep_t ep, __u8 start_ctrlid,
1056 struct nvme_ctrl_list *list);
1057
1058 /**
1059 * nvme_mi_mi_read_mi_data_ctrl() - Perform a Read MI Data Structure command,
1060 * retrieving controller information
1061 * @ep: endpoint for MI communication
1062 * @ctrl_id: ID of controller to query
1063 * @ctrl: controller data to populate
1064 *
1065 * Retrieves the Controller Information Data Structure for the attached
1066 * controller with ID @ctrlid.
1067 *
1068 * See &struct nvme_mi_read_ctrl_info.
1069 *
1070 * Return: The nvme command status if a response was received (see
1071 * &enum nvme_status_field) or -1 with errno set otherwise..
1072 */
1073 int nvme_mi_mi_read_mi_data_ctrl(nvme_mi_ep_t ep, __u16 ctrl_id,
1074 struct nvme_mi_read_ctrl_info *ctrl);
1075
1076 /**
1077 * nvme_mi_mi_subsystem_health_status_poll() - Read the Subsystem Health
1078 * Data Structure from the NVM subsystem
1079 * @ep: endpoint for MI communication
1080 * @clear: flag to clear the Composite Controller Status state
1081 * @nshds: subsystem health status data to populate
1082 *
1083 * Retrieves the Subsystem Health Data Structure into @nshds. If @clear is
1084 * set, requests that the Composite Controller Status bits are cleared after
1085 * the read. See NVMe-MI section 5.6 for details on the CCS bits.
1086 *
1087 * See &struct nvme_mi_nvm_ss_health_status.
1088 *
1089 * Return: The nvme command status if a response was received (see
1090 * &enum nvme_status_field) or -1 with errno set otherwise..
1091 */
1092 int nvme_mi_mi_subsystem_health_status_poll(nvme_mi_ep_t ep, bool clear,
1093 struct nvme_mi_nvm_ss_health_status *nshds);
1094
1095 /**
1096 * nvme_mi_mi_config_get - query a configuration parameter
1097 * @ep: endpoint for MI communication
1098 * @dw0: management doubleword 0, containing configuration identifier, plus
1099 * config-specific fields
1100 * @dw1: management doubleword 0, config-specific.
1101 * @nmresp: set to queried configuration data in NMRESP field of response.
1102 *
1103 * Performs a MI Configuration Get command, with the configuration identifier
1104 * as the LSB of @dw0. Other @dw0 and @dw1 data is configuration-identifier
1105 * specific.
1106 *
1107 * On a successful Configuration Get, the @nmresp pointer will be populated with
1108 * the bytes from the 3-byte NMRESP field, converted to native endian.
1109 *
1110 * See &enum nvme_mi_config_id for identifiers.
1111 *
1112 * Return: The nvme command status if a response was received (see
1113 * &enum nvme_status_field) or -1 with errno set otherwise..
1114 */
1115 int nvme_mi_mi_config_get(nvme_mi_ep_t ep, __u32 dw0, __u32 dw1,
1116 __u32 *nmresp);
1117
1118 /**
1119 * nvme_mi_mi_config_set - set a configuration parameter
1120 * @ep: endpoint for MI communication
1121 * @dw0: management doubleword 0, containing configuration identifier, plus
1122 * config-specific fields
1123 * @dw1: management doubleword 0, config-specific.
1124 *
1125 * Performs a MI Configuration Set command, with the command as the LSB of
1126 * @dw0. Other @dw0 and @dw1 data is configuration-identifier specific.
1127 *
1128 * See &enum nvme_mi_config_id for identifiers.
1129 *
1130 * Return: The nvme command status if a response was received (see
1131 * &enum nvme_status_field) or -1 with errno set otherwise..
1132 */
1133 int nvme_mi_mi_config_set(nvme_mi_ep_t ep, __u32 dw0, __u32 dw1);
1134
1135 /**
1136 * nvme_mi_mi_config_get_smbus_freq - get configuration: SMBus port frequency
1137 * @ep: endpoint for MI communication
1138 * @port: port ID to query
1139 * @freq: output value for current frequency configuration
1140 *
1141 * Performs a MI Configuration Get, to query the current SMBus frequency of
1142 * the port specified in @port. On success, populates @freq with the port
1143 * frequency
1144 *
1145 * Return: The nvme command status if a response was received (see
1146 * &enum nvme_status_field) or -1 with errno set otherwise..
1147 */
1148 static inline int nvme_mi_mi_config_get_smbus_freq(nvme_mi_ep_t ep, __u8 port,
1149 enum nvme_mi_config_smbus_freq *freq)
1150 {
1151 __u32 tmp, dw0;
1152 int rc;
1153
1154 dw0 = port << 24 | NVME_MI_CONFIG_SMBUS_FREQ;
1155
1156 rc = nvme_mi_mi_config_get(ep, dw0, 0, &tmp);
1157 if (!rc)
1158 *freq = (enum nvme_mi_config_smbus_freq)(tmp & 0x3);
1159 return rc;
1160 }
1161
1162 /**
1163 * nvme_mi_mi_config_set_smbus_freq - set configuration: SMBus port frequency
1164 * @ep: endpoint for MI communication
1165 * @port: port ID to set
1166 * @freq: new frequency configuration
1167 *
1168 * Performs a MI Configuration Set, to update the current SMBus frequency of
1169 * the port specified in @port.
1170 *
1171 * See &struct nvme_mi_read_port_info for the maximum supported SMBus frequency
1172 * for the port.
1173 *
1174 * Return: The nvme command status if a response was received (see
1175 * &enum nvme_status_field) or -1 with errno set otherwise..
1176 */
1177 static inline int nvme_mi_mi_config_set_smbus_freq(nvme_mi_ep_t ep, __u8 port,
1178 enum nvme_mi_config_smbus_freq freq)
1179 {
1180 __u32 dw0 = port << 24 |
1181 (freq & 0x3) << 8 |
1182 NVME_MI_CONFIG_SMBUS_FREQ;
1183
1184 return nvme_mi_mi_config_set(ep, dw0, 0);
1185 }
1186
1187 /**
1188 * nvme_mi_mi_config_set_health_status_change - clear CCS bits in health status
1189 * @ep: endpoint for MI communication
1190 * @mask: bitmask to clear
1191 *
1192 * Performs a MI Configuration Set, to update the current health status poll
1193 * values of the Composite Controller Status bits. Bits set in @mask will
1194 * be cleared from future health status poll data, and may be re-triggered by
1195 * a future health change event.
1196 *
1197 * See &nvme_mi_mi_subsystem_health_status_poll(), &enum nvme_mi_ccs for
1198 * values in @mask.
1199 *
1200 * Return: The nvme command status if a response was received (see
1201 * &enum nvme_status_field) or -1 with errno set otherwise..
1202 */
1203 static inline int nvme_mi_mi_config_set_health_status_change(nvme_mi_ep_t ep,
1204 __u32 mask)
1205 {
1206 return nvme_mi_mi_config_set(ep, NVME_MI_CONFIG_HEALTH_STATUS_CHANGE,
1207 mask);
1208 }
1209
1210 /**
1211 * nvme_mi_mi_config_get_mctp_mtu - get configuration: MCTP MTU
1212 * @ep: endpoint for MI communication
1213 * @port: port ID to query
1214 * @mtu: output value for current MCTP MTU configuration
1215 *
1216 * Performs a MI Configuration Get, to query the current MCTP Maximum
1217 * Transmission Unit size (MTU) of the port specified in @port. On success,
1218 * populates @mtu with the MTU.
1219 *
1220 * The default reset value is 64, corresponding to the MCTP baseline MTU.
1221 *
1222 * Some controllers may also use this as the maximum receive unit size, and
1223 * may not accept MCTP messages larger than the configured MTU.
1224 *
1225 * Return: The nvme command status if a response was received (see
1226 * &enum nvme_status_field) or -1 with errno set otherwise..
1227 */
1228 static inline int nvme_mi_mi_config_get_mctp_mtu(nvme_mi_ep_t ep, __u8 port,
1229 __u16 *mtu)
1230 {
1231 __u32 tmp, dw0;
1232 int rc;
1233
1234 dw0 = port << 24 | NVME_MI_CONFIG_MCTP_MTU;
1235
1236 rc = nvme_mi_mi_config_get(ep, dw0, 0, &tmp);
1237 if (!rc)
1238 *mtu = tmp & 0xffff;
1239 return rc;
1240 }
1241
1242 /**
1243 * nvme_mi_mi_config_set_mctp_mtu - set configuration: MCTP MTU
1244 * @ep: endpoint for MI communication
1245 * @port: port ID to set
1246 * @mtu: new MTU configuration
1247 *
1248 * Performs a MI Configuration Set, to update the current MCTP MTU value for
1249 * the port specified in @port.
1250 *
1251 * Some controllers may also use this as the maximum receive unit size, and
1252 * may not accept MCTP messages larger than the configured MTU. When setting
1253 * this value, you will likely need to change the MTU of the local MCTP
1254 * interface(s) to match.
1255 *
1256 * Return: The nvme command status if a response was received (see
1257 * &enum nvme_status_field) or -1 with errno set otherwise..
1258 */
1259 static inline int nvme_mi_mi_config_set_mctp_mtu(nvme_mi_ep_t ep, __u8 port,
1260 __u16 mtu)
1261 {
1262 __u32 dw0 = port << 24 | NVME_MI_CONFIG_MCTP_MTU;
1263
1264 return nvme_mi_mi_config_set(ep, dw0, mtu);
1265 }
1266
1267
1268 /**
1269 * nvme_mi_mi_config_get_async_event - get configuration: Asynchronous Event
1270 * @ep: endpoint for MI communication
1271 * @aeelver: Asynchronous Event Enable List Version Number
1272 * @list: AE Supported list header and list contents
1273 * @list_num_bytes: number of bytes in the list header and contents buffer.
1274 * This will be populated with returned size of list and contents if successful.
1275 *
1276 * Performs a MI Configuration Get, to query the current enable Asynchronous
1277 * Events. On success, populates @aeelver and the @list with current info,
1278 *
1279 * Return: The nvme command status if a response was received (see
1280 * &enum nvme_status_field) or -1 with errno set otherwise..
1281 */
1282 int nvme_mi_mi_config_get_async_event(nvme_mi_ep_t ep,
1283 __u8 *aeelver,
1284 struct nvme_mi_aem_supported_list *list,
1285 size_t *list_num_bytes);
1286
1287 /**
1288 * nvme_mi_mi_config_set_async_event - set configuration: Asynchronous Event
1289 * @ep: endpoint for MI communication
1290 * @envfa: Enable SR-IOV Virtual Functions AE
1291 * @empfa: Enable SR-IOV Physical Functions AE
1292 * @encfa: Enable PCI Functions AE.
1293 * @aemd: AEM Delay Interval (for Sync only)
1294 * @aerd: AEM Retry Delay (for Sync only; time in 100s of ms)
1295 * @enable_list: nvme_mi_aem_enable_listucture containing header and items
1296 * of events to be enabled or disabled. This is taken as a delta change
1297 * from the current configuration.
1298 * @enable_list_size: Size of the enable_list including header and data.
1299 * Meant to catch overrun issues.
1300 * @occ_list: Pointer to populate with the occurrence list (header and data)
1301 * @occ_list_size: Total size of provided occ_list buffer. Will be updated
1302 * with received size if successful
1303 *
1304 * Performs a MI Configuration Set, to ACK (sent after an AEM) or Sync (at anytime to enable
1305 * or disable Asynchronous Events).
1306 *
1307 * On success, populates @occ_list. See TP6035a for details on how occ_list is populated in
1308 * ACK versus Sync conditions
1309 *
1310 * Return: The nvme command status if a response was received (see
1311 * &enum nvme_status_field) or -1 with errno set otherwise..
1312 */
1313 int nvme_mi_mi_config_set_async_event(nvme_mi_ep_t ep,
1314 bool envfa,
1315 bool empfa,
1316 bool encfa,
1317 __u8 aemd,
1318 __u8 aerd,
1319 struct nvme_mi_aem_enable_list *enable_list,
1320 size_t enable_list_size,
1321 struct nvme_mi_aem_occ_list_hdr *occ_list,
1322 size_t *occ_list_size);
1323
1324 static inline int nvme_mi_aem_ack(nvme_mi_ep_t ep,
1325 struct nvme_mi_aem_occ_list_hdr *occ_list,
1326 size_t *occ_list_size)
1327 {
1328 //An AEM Ack is defined as a SET CONFIG AE with no AE enable items
1329 struct nvme_mi_aem_enable_list list = {0};
1330
1331 list.hdr.aeelhl = sizeof(struct nvme_mi_aem_enable_list_header);
1332 list.hdr.aeelver = 0;
1333 list.hdr.aeetl = sizeof(struct nvme_mi_aem_enable_list_header);
1334 list.hdr.numaee = 0;
1335
1336 return nvme_mi_mi_config_set_async_event(ep, false, false, false, 0, 0,
1337 &list, sizeof(list), occ_list,
1338 occ_list_size);
1339 }
1340
1341 /* Admin channel functions */
1342
1343 /**
1344 * nvme_mi_admin_xfer() - Raw admin transfer interface.
1345 * @ctrl: controller to send the admin command to
1346 * @admin_req: request data
1347 * @req_data_size: size of request data payload
1348 * @admin_resp: buffer for response data
1349 * @resp_data_offset: offset into request data to retrieve from controller
1350 * @resp_data_size: size of response data buffer, updated to received size
1351 *
1352 * Performs an arbitrary NVMe Admin command, using the provided request data,
1353 * in @admin_req. The size of the request data *payload* is specified in
1354 * @req_data_size - this does not include the standard header length (so a
1355 * header-only request would have a size of 0).
1356 *
1357 * On success, response data is stored in @admin_resp, which has an optional
1358 * appended payload buffer of @resp_data_size bytes. The actual payload
1359 * transferred will be stored in @resp_data_size. These sizes do not include
1360 * the Admin request header, so 0 represents no payload.
1361 *
1362 * As with all Admin commands, we can request partial data from the Admin
1363 * Response payload, offset by @resp_data_offset.
1364 *
1365 * See: &struct nvme_mi_admin_req_hdr and &struct nvme_mi_admin_resp_hdr.
1366 *
1367 * Return: The nvme command status if a response was received (see
1368 * &enum nvme_status_field) or -1 with errno set otherwise..
1369 */
1370 int nvme_mi_admin_xfer(nvme_mi_ctrl_t ctrl,
1371 struct nvme_mi_admin_req_hdr *admin_req,
1372 size_t req_data_size,
1373 struct nvme_mi_admin_resp_hdr *admin_resp,
1374 off_t resp_data_offset,
1375 size_t *resp_data_size);
1376
1377 /**
1378 * nvme_mi_admin_admin_passthru() - Submit an nvme admin passthrough command
1379 * @ctrl: Controller to send command to
1380 * @opcode: The nvme admin command to send
1381 * @flags: NVMe command flags (not used)
1382 * @rsvd: Reserved for future use
1383 * @nsid: Namespace identifier
1384 * @cdw2: Command dword 2
1385 * @cdw3: Command dword 3
1386 * @cdw10: Command dword 10
1387 * @cdw11: Command dword 11
1388 * @cdw12: Command dword 12
1389 * @cdw13: Command dword 13
1390 * @cdw14: Command dword 14
1391 * @cdw15: Command dword 15
1392 * @data_len: Length of the data transferred in this command in bytes
1393 * @data: Pointer to user address of the data buffer
1394 * @metadata_len:Length of metadata transferred in this command(not used)
1395 * @metadata: Pointer to user address of the metadata buffer(not used)
1396 * @timeout_ms: How long to wait for the command to complete
1397 * @result: Optional field to return the result from the CQE dword 0
1398 *
1399 * Send a customized NVMe Admin command request message and get the corresponding
1400 * response message.
1401 *
1402 * This interface supports no data, host to controller and controller to
1403 * host but it doesn't support bidirectional data transfer.
1404 * Also this interface only supports data transfer size range [0, 4096] (bytes)
1405 * so the & data_len parameter must be less than 4097.
1406 *
1407 * Return: The nvme command status if a response was received (see
1408 * &enum nvme_status_field) or -1 with errno set otherwise.
1409 */
1410 int nvme_mi_admin_admin_passthru(nvme_mi_ctrl_t ctrl, __u8 opcode, __u8 flags,
1411 __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3,
1412 __u32 cdw10, __u32 cdw11, __u32 cdw12,
1413 __u32 cdw13, __u32 cdw14, __u32 cdw15,
1414 __u32 data_len, void *data, __u32 metadata_len,
1415 void *metadata, __u32 timeout_ms, __u32 *result);
1416
1417 /**
1418 * nvme_mi_admin_identify_partial() - Perform an Admin identify command,
1419 * and retrieve partial response data.
1420 * @ctrl: Controller to process identify command
1421 * @args: Identify command arguments
1422 * @offset: offset of identify data to retrieve from response
1423 * @size: size of identify data to return
1424 *
1425 * Perform an Identify command, using the Identify command parameters in @args.
1426 * The @offset and @size arguments allow the caller to retrieve part of
1427 * the identify response. See NVMe-MI section 6.2 for the semantics (and some
1428 * handy diagrams) of the offset & size parameters.
1429 *
1430 * Will return an error if the length of the response data (from the controller)
1431 * did not match @size.
1432 *
1433 * Unless you're performing a vendor-unique identify command, You'll probably
1434 * want to use one of the identify helpers (nvme_mi_admin_identify,
1435 * nvme_mi_admin_identify_cns_nsid, or nvme_mi_admin_identify_<type>) instead
1436 * of this. If the type of your identify command is standardized but not
1437 * yet supported by libnvme-mi, please contact the maintainers.
1438 *
1439 * Return: The nvme command status if a response was received (see
1440 * &enum nvme_status_field) or -1 with errno set otherwise.
1441 *
1442 * See: &struct nvme_identify_args
1443 */
1444 int nvme_mi_admin_identify_partial(nvme_mi_ctrl_t ctrl,
1445 struct nvme_identify_args *args,
1446 off_t offset, size_t size);
1447
1448 /**
1449 * nvme_mi_admin_identify() - Perform an Admin identify command.
1450 * @ctrl: Controller to process identify command
1451 * @args: Identify command arguments
1452 *
1453 * Perform an Identify command, using the Identify command parameters in @args.
1454 * Stores the identify data in ->data, and (if set) the result from cdw0
1455 * into args->result.
1456 *
1457 * Will return an error if the length of the response data (from the
1458 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE.
1459 *
1460 * Return: The nvme command status if a response was received (see
1461 * &enum nvme_status_field) or -1 with errno set otherwise.
1462 *
1463 * See: &struct nvme_identify_args
1464 */
1465 static inline int nvme_mi_admin_identify(nvme_mi_ctrl_t ctrl,
1466 struct nvme_identify_args *args)
1467 {
1468 return nvme_mi_admin_identify_partial(ctrl, args,
1469 0, NVME_IDENTIFY_DATA_SIZE);
1470 }
1471
1472 /**
1473 * nvme_mi_control() - Perform a Control Primitive command
1474 * @ep: endpoint for MI communication
1475 * @opcode: Control Primitive opcode (using &enum nvme_mi_control_opcode)
1476 * @cpsp: Control Primitive Specific Parameter
1477 * @result_cpsr: Optional field to return the result from the CPSR field
1478 *
1479 * Perform a Control Primitive command, using the opcode specified in @opcode
1480 * Stores the result from the CPSR field in @result_cpsr if set.
1481 *
1482 * Return: 0 on success, non-zero on failure
1483 *
1484 * See: &enum nvme_mi_control_opcode
1485 *
1486 */
1487 int nvme_mi_control(nvme_mi_ep_t ep, __u8 opcode,
1488 __u16 cpsp, __u16 *result_cpsr);
1489
1490 /**
1491 * nvme_mi_admin_identify_cns_nsid() - Perform an Admin identify command using
1492 * specific CNS/NSID parameters.
1493 * @ctrl: Controller to process identify command
1494 * @cns: Controller or Namespace Structure, specifying identified object
1495 * @nsid: namespace ID
1496 * @data: buffer for identify data response
1497 *
1498 * Perform an Identify command, using the CNS specifier @cns, and the
1499 * namespace ID @nsid if required by the CNS type.
1500 *
1501 * Stores the identify data in @data, which is expected to be a buffer of
1502 * &NVME_IDENTIFY_DATA_SIZE bytes.
1503 *
1504 * Will return an error if the length of the response data (from the
1505 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE.
1506 *
1507 * Return: The nvme command status if a response was received (see
1508 * &enum nvme_status_field) or -1 with errno set otherwise.
1509 */
1510 static inline int nvme_mi_admin_identify_cns_nsid(nvme_mi_ctrl_t ctrl,
1511 enum nvme_identify_cns cns,
1512 __u32 nsid, void *data)
1513 {
1514 struct nvme_identify_args args = {
1515 .result = NULL,
1516 .data = data,
1517 .args_size = sizeof(args),
1518 .cns = cns,
1519 .csi = NVME_CSI_NVM,
1520 .nsid = nsid,
1521 .cntid = NVME_CNTLID_NONE,
1522 .cns_specific_id = NVME_CNSSPECID_NONE,
1523 .uuidx = NVME_UUID_NONE,
1524 };
1525
1526 return nvme_mi_admin_identify(ctrl, &args);
1527 }
1528
1529 /**
1530 * nvme_mi_admin_identify_ns() - Perform an Admin identify command for a
1531 * namespace
1532 * @ctrl: Controller to process identify command
1533 * @nsid: namespace ID
1534 * @ns: Namespace identification to populate
1535 *
1536 * Perform an Identify (namespace) command, setting the namespace id data
1537 * in @ns. The namespace is expected to active and allocated.
1538 *
1539 * Return: The nvme command status if a response was received (see
1540 * &enum nvme_status_field) or -1 with errno set otherwise.
1541 */
1542 static inline int nvme_mi_admin_identify_ns(nvme_mi_ctrl_t ctrl, __u32 nsid,
1543 struct nvme_id_ns *ns)
1544 {
1545 return nvme_mi_admin_identify_cns_nsid(ctrl, NVME_IDENTIFY_CNS_NS,
1546 nsid, ns);
1547 }
1548
1549 /**
1550 * nvme_mi_admin_identify_ns_descs() - Perform an Admin identify Namespace
1551 * Identification Descriptor list command for a namespace
1552 * @ctrl: Controller to process identify command
1553 * @nsid: Namespace ID
1554 * @descs: Namespace Identification Descriptor list to populate
1555 *
1556 * Perform an Identify namespace identification description list command,
1557 * setting the namespace identification description list in @descs
1558 *
1559 * Return: The nvme command status if a response was received (see
1560 * &enum nvme_status_field) or -1 with errno set otherwise.
1561 */
1562 static inline int nvme_mi_admin_identify_ns_descs(nvme_mi_ctrl_t ctrl,
1563 __u32 nsid,
1564 struct nvme_ns_id_desc *descs)
1565 {
1566 return nvme_mi_admin_identify_cns_nsid(ctrl, NVME_IDENTIFY_CNS_NS_DESC_LIST,
1567 nsid, descs);
1568 }
1569
1570 /**
1571 * nvme_mi_admin_identify_allocated_ns() - Perform an Admin identify command
1572 * for an allocated namespace
1573 * @ctrl: Controller to process identify command
1574 * @nsid: namespace ID
1575 * @ns: Namespace identification to populate
1576 *
1577 * Perform an Identify (namespace) command, setting the namespace id data
1578 * in @ns.
1579 *
1580 * Return: The nvme command status if a response was received (see
1581 * &enum nvme_status_field) or -1 with errno set otherwise.
1582 */
1583 static inline int nvme_mi_admin_identify_allocated_ns(nvme_mi_ctrl_t ctrl,
1584 __u32 nsid,
1585 struct nvme_id_ns *ns)
1586 {
1587 return nvme_mi_admin_identify_cns_nsid(ctrl,
1588 NVME_IDENTIFY_CNS_ALLOCATED_NS,
1589 nsid, ns);
1590 }
1591
1592 /**
1593 * nvme_mi_admin_identify_ctrl() - Perform an Admin identify for a controller
1594 * @ctrl: Controller to process identify command
1595 * @id: Controller identify data to populate
1596 *
1597 * Perform an Identify command, for the controller specified by @ctrl,
1598 * writing identify data to @id.
1599 *
1600 * Will return an error if the length of the response data (from the
1601 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @id will be
1602 * fully populated on success.
1603 *
1604 * Return: The nvme command status if a response was received (see
1605 * &enum nvme_status_field) or -1 with errno set otherwise.
1606 *
1607 * See: &struct nvme_id_ctrl
1608 */
1609 static inline int nvme_mi_admin_identify_ctrl(nvme_mi_ctrl_t ctrl,
1610 struct nvme_id_ctrl *id)
1611 {
1612 return nvme_mi_admin_identify_cns_nsid(ctrl, NVME_IDENTIFY_CNS_CTRL,
1613 NVME_NSID_NONE, id);
1614 }
1615
1616 /**
1617 * nvme_mi_admin_identify_ctrl_list() - Perform an Admin identify for a
1618 * controller list.
1619 * @ctrl: Controller to process identify command
1620 * @cntid: Controller ID to specify list start
1621 * @list: List data to populate
1622 *
1623 * Perform an Identify command, for the controller list starting with
1624 * IDs greater than or equal to @cntid.
1625 *
1626 * Will return an error if the length of the response data (from the
1627 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @id will be
1628 * fully populated on success.
1629 *
1630 * Return: The nvme command status if a response was received (see
1631 * &enum nvme_status_field) or -1 with errno set otherwise.
1632 *
1633 * See: &struct nvme_ctrl_list
1634 */
1635 static inline int nvme_mi_admin_identify_ctrl_list(nvme_mi_ctrl_t ctrl,
1636 __u16 cntid,
1637 struct nvme_ctrl_list *list)
1638 {
1639 struct nvme_identify_args args = {
1640 .result = NULL,
1641 .data = list,
1642 .args_size = sizeof(args),
1643 .cns = NVME_IDENTIFY_CNS_CTRL_LIST,
1644 .csi = NVME_CSI_NVM,
1645 .nsid = NVME_NSID_NONE,
1646 .cntid = cntid,
1647 .cns_specific_id = NVME_CNSSPECID_NONE,
1648 .uuidx = NVME_UUID_NONE,
1649 };
1650
1651 return nvme_mi_admin_identify(ctrl, &args);
1652 }
1653
1654 /**
1655 * nvme_mi_admin_identify_nsid_ctrl_list() - Perform an Admin identify for a
1656 * controller list with specific namespace ID
1657 * @ctrl: Controller to process identify command
1658 * @nsid: Namespace identifier
1659 * @cntid: Controller ID to specify list start
1660 * @list: List data to populate
1661 *
1662 * Perform an Identify command, for the controller list for @nsid, starting
1663 * with IDs greater than or equal to @cntid.
1664 *
1665 * Will return an error if the length of the response data (from the
1666 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @id will be
1667 * fully populated on success.
1668 *
1669 * Return: The nvme command status if a response was received (see
1670 * &enum nvme_status_field) or -1 with errno set otherwise.
1671 *
1672 * See: &struct nvme_ctrl_list
1673 */
1674 static inline int nvme_mi_admin_identify_nsid_ctrl_list(nvme_mi_ctrl_t ctrl,
1675 __u32 nsid, __u16 cntid,
1676 struct nvme_ctrl_list *list)
1677 {
1678 struct nvme_identify_args args = {
1679 .result = NULL,
1680 .data = list,
1681 .args_size = sizeof(args),
1682 .cns = NVME_IDENTIFY_CNS_NS_CTRL_LIST,
1683 .csi = NVME_CSI_NVM,
1684 .nsid = nsid,
1685 .cntid = cntid,
1686 .cns_specific_id = NVME_CNSSPECID_NONE,
1687 .uuidx = NVME_UUID_NONE,
1688 };
1689
1690 return nvme_mi_admin_identify(ctrl, &args);
1691 }
1692
1693 /**
1694 * nvme_mi_admin_identify_allocated_ns_list() - Perform an Admin identify for
1695 * an allocated namespace list
1696 * @ctrl: Controller to process identify command
1697 * @nsid: Namespace ID to specify list start
1698 * @list: List data to populate
1699 *
1700 * Perform an Identify command, for the allocated namespace list starting with
1701 * IDs greater than or equal to @nsid. Specify &NVME_NSID_NONE for the start
1702 * of the list.
1703 *
1704 * Will return an error if the length of the response data (from the
1705 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @list will be
1706 * be fully populated on success.
1707 *
1708 * Return: The nvme command status if a response was received (see
1709 * &enum nvme_status_field) or -1 with errno set otherwise.
1710 *
1711 * See: &struct nvme_ns_list
1712 */
1713 static inline int nvme_mi_admin_identify_allocated_ns_list(nvme_mi_ctrl_t ctrl,
1714 __u32 nsid,
1715 struct nvme_ns_list *list)
1716 {
1717 struct nvme_identify_args args = {
1718 .result = NULL,
1719 .data = list,
1720 .args_size = sizeof(args),
1721 .cns = NVME_IDENTIFY_CNS_ALLOCATED_NS_LIST,
1722 .csi = NVME_CSI_NVM,
1723 .nsid = nsid,
1724 .cns_specific_id = NVME_CNSSPECID_NONE,
1725 .uuidx = NVME_UUID_NONE,
1726 };
1727
1728 return nvme_mi_admin_identify(ctrl, &args);
1729 }
1730
1731 /**
1732 * nvme_mi_admin_identify_active_ns_list() - Perform an Admin identify for an
1733 * active namespace list
1734 * @ctrl: Controller to process identify command
1735 * @nsid: Namespace ID to specify list start
1736 * @list: List data to populate
1737 *
1738 * Perform an Identify command, for the active namespace list starting with
1739 * IDs greater than or equal to @nsid. Specify &NVME_NSID_NONE for the start
1740 * of the list.
1741 *
1742 * Will return an error if the length of the response data (from the
1743 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @list will be
1744 * be fully populated on success.
1745 *
1746 * Return: The nvme command status if a response was received (see
1747 * &enum nvme_status_field) or -1 with errno set otherwise.
1748 *
1749 * See: &struct nvme_ns_list
1750 */
1751 static inline int nvme_mi_admin_identify_active_ns_list(nvme_mi_ctrl_t ctrl,
1752 __u32 nsid,
1753 struct nvme_ns_list *list)
1754 {
1755 struct nvme_identify_args args = {
1756 .result = NULL,
1757 .data = list,
1758 .args_size = sizeof(args),
1759 .cns = NVME_IDENTIFY_CNS_NS_ACTIVE_LIST,
1760 .csi = NVME_CSI_NVM,
1761 .nsid = nsid,
1762 .cns_specific_id = NVME_CNSSPECID_NONE,
1763 .uuidx = NVME_UUID_NONE,
1764 };
1765
1766 return nvme_mi_admin_identify(ctrl, &args);
1767 }
1768
1769 /**
1770 * nvme_mi_admin_identify_primary_ctrl() - Perform an Admin identify for
1771 * primary controller capabilities data structure.
1772 * @ctrl: Controller to process identify command
1773 * @cntid: Controller ID to specify
1774 * @cap: Primary Controller Capabilities data structure to populate
1775 *
1776 * Perform an Identify command to get the Primary Controller Capabilities data
1777 * for the controller specified by @cntid
1778 *
1779 * Will return an error if the length of the response data (from the
1780 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @cap will be
1781 * be fully populated on success.
1782 *
1783 * Return: 0 on success, non-zero on failure
1784 *
1785 * See: &struct nvme_primary_ctrl_cap
1786 */
1787 static inline int nvme_mi_admin_identify_primary_ctrl(nvme_mi_ctrl_t ctrl,
1788 __u16 cntid,
1789 struct nvme_primary_ctrl_cap *cap)
1790 {
1791 struct nvme_identify_args args = {
1792 .result = NULL,
1793 .data = cap,
1794 .args_size = sizeof(args),
1795 .cns = NVME_IDENTIFY_CNS_PRIMARY_CTRL_CAP,
1796 .csi = NVME_CSI_NVM,
1797 .nsid = NVME_NSID_NONE,
1798 .cntid = cntid,
1799 .cns_specific_id = NVME_CNSSPECID_NONE,
1800 .uuidx = NVME_UUID_NONE,
1801 };
1802
1803 return nvme_mi_admin_identify(ctrl, &args);
1804 }
1805
1806 /**
1807 * nvme_mi_admin_identify_secondary_ctrl_list() - Perform an Admin identify for
1808 * a secondary controller list.
1809 * @ctrl: Controller to process identify command
1810 * @cntid: Controller ID to specify list start
1811 * @list: List data to populate
1812 *
1813 * Perform an Identify command, for the secondary controllers associated with
1814 * the current primary controller. Only entries with IDs greater than or
1815 * equal to @cntid are returned.
1816 *
1817 * Will return an error if the length of the response data (from the
1818 * controller) is not a full &NVME_IDENTIFY_DATA_SIZE, so @list will be
1819 * be fully populated on success.
1820 *
1821 * Return: 0 on success, non-zero on failure
1822 *
1823 * See: &struct nvme_secondary_ctrl_list
1824 */
1825 static inline int nvme_mi_admin_identify_secondary_ctrl_list(nvme_mi_ctrl_t ctrl,
1826 __u16 cntid,
1827 struct nvme_secondary_ctrl_list *list)
1828 {
1829 struct nvme_identify_args args = {
1830 .result = NULL,
1831 .data = list,
1832 .args_size = sizeof(args),
1833 .cns = NVME_IDENTIFY_CNS_SECONDARY_CTRL_LIST,
1834 .csi = NVME_CSI_NVM,
1835 .nsid = NVME_NSID_NONE,
1836 .cntid = cntid,
1837 .cns_specific_id = NVME_CNSSPECID_NONE,
1838 .uuidx = NVME_UUID_NONE,
1839 };
1840
1841 return nvme_mi_admin_identify(ctrl, &args);
1842 }
1843
1844 /**
1845 * nvme_mi_admin_get_log_page() - Retrieve log page data from controller
1846 * @ctrl: Controller to query
1847 * @xfer_len: The chunk size of the read
1848 * @args: Get Log Page command arguments
1849 *
1850 * Performs a Get Log Page Admin command as specified by @args. Response data
1851 * is stored in @args->data, which should be a buffer of @args->data_len bytes.
1852 * Resulting data length is stored in @args->data_len on successful
1853 * command completion.
1854 *
1855 * This request may be implemented as multiple log page commands, in order
1856 * to fit within MI message-size limits.
1857 *
1858 * Return: The nvme command status if a response was received (see
1859 * &enum nvme_status_field) or -1 with errno set otherwise.
1860 *
1861 * See: &struct nvme_get_log_args
1862 */
1863 int nvme_mi_admin_get_log_page(nvme_mi_ctrl_t ctrl, __u32 xfer_len,
1864 struct nvme_get_log_args *args);
1865
1866 /**
1867 * nvme_mi_admin_get_log() - Retrieve log page data from controller
1868 * @ctrl: Controller to query
1869 * @args: Get Log Page command arguments
1870 *
1871 * Performs a Get Log Page Admin command as specified by @args. Response data
1872 * is stored in @args->data, which should be a buffer of @args->data_len bytes.
1873 * Resulting data length is stored in @args->data_len on successful
1874 * command completion.
1875 *
1876 * This request may be implemented as multiple log page commands, in order
1877 * to fit within MI message-size limits.
1878 *
1879 * Return: The nvme command status if a response was received (see
1880 * &enum nvme_status_field) or -1 with errno set otherwise.
1881 *
1882 * See: &struct nvme_get_log_args
1883 */
1884 int nvme_mi_admin_get_log(nvme_mi_ctrl_t ctrl, struct nvme_get_log_args *args);
1885
1886 /**
1887 * nvme_mi_admin_get_nsid_log() - Helper for Get Log Page functions
1888 * @ctrl: Controller to query
1889 * @rae: Retain Asynchronous Events
1890 * @lid: Log identifier
1891 * @nsid: Namespace ID
1892 * @len: length of log buffer
1893 * @log: pointer for resulting log data
1894 *
1895 * Performs a Get Log Page Admin command for a specific log ID @lid and
1896 * namespace ID @nsid. Log data is expected to be @len bytes, and is stored
1897 * in @log on success. The @rae flag is passed as-is to the Get Log Page
1898 * command, and is specific to the Log Page requested.
1899 *
1900 * Return: The nvme command status if a response was received (see
1901 * &enum nvme_status_field) or -1 with errno set otherwise.
1902 */
1903 static inline int nvme_mi_admin_get_nsid_log(nvme_mi_ctrl_t ctrl, bool rae,
1904 enum nvme_cmd_get_log_lid lid,
1905 __u32 nsid, __u32 len, void *log)
1906 {
1907 struct nvme_get_log_args args = {
1908 .lpo = 0,
1909 .result = NULL,
1910 .log = log,
1911 .args_size = sizeof(args),
1912 .lid = lid,
1913 .len = len,
1914 .nsid = nsid,
1915 .csi = NVME_CSI_NVM,
1916 .lsi = NVME_LOG_LSI_NONE,
1917 .lsp = NVME_LOG_LSP_NONE,
1918 .uuidx = NVME_UUID_NONE,
1919 .rae = rae,
1920 .ot = false,
1921 };
1922
1923 return nvme_mi_admin_get_log(ctrl, &args);
1924 }
1925
1926 /**
1927 * nvme_mi_admin_get_endgid_log() - Helper for Get Endurance Group ID Log Page functions
1928 * @ctrl: Controller to query
1929 * @rae: Retain Asynchronous Events
1930 * @lid: Log identifier
1931 * @endgid: Endurance Group ID
1932 * @len: length of log buffer
1933 * @log: pointer for resulting log data
1934 *
1935 * Performs a Get Log Page Admin command for a specific log ID @lid and
1936 * endurance group ID @endgid. Log data is expected to be @len bytes, and is stored
1937 * in @log on success. The @rae flag is passed as-is to the Get Log Page
1938 * command, and is specific to the Log Page requested.
1939 *
1940 * Return: The nvme command status if a response was received (see
1941 * &enum nvme_status_field) or -1 with errno set otherwise.
1942 */
1943 static inline int nvme_mi_admin_get_endgid_log(nvme_mi_ctrl_t ctrl, bool rae,
1944 enum nvme_cmd_get_log_lid lid, __u16 endgid,
1945 __u32 len, void *log)
1946 {
1947 struct nvme_get_log_args args = {
1948 .lpo = 0,
1949 .result = NULL,
1950 .log = log,
1951 .args_size = sizeof(args),
1952 .timeout = NVME_DEFAULT_IOCTL_TIMEOUT,
1953 .lid = lid,
1954 .len = len,
1955 .nsid = NVME_NSID_NONE,
1956 .csi = NVME_CSI_NVM,
1957 .lsi = endgid,
1958 .lsp = NVME_LOG_LSP_NONE,
1959 .uuidx = NVME_LOG_LSP_NONE,
1960 .rae = rae,
1961 .ot = false,
1962 };
1963
1964 return nvme_mi_admin_get_log(ctrl, &args);
1965 }
1966
1967 /**
1968 * nvme_mi_admin_get_log_simple() - Helper for Get Log Page functions with no
1969 * NSID or RAE requirements
1970 * @ctrl: Controller to query
1971 * @lid: Log identifier
1972 * @len: length of log buffer
1973 * @log: pointer for resulting log data
1974 *
1975 * Performs a Get Log Page Admin command for a specific log ID @lid, using
1976 * NVME_NSID_ALL for the namespace identifier, and rae set to false.
1977 *
1978 * Return: The nvme command status if a response was received (see
1979 * &enum nvme_status_field) or -1 with errno set otherwise.
1980 */
1981 static inline int nvme_mi_admin_get_log_simple(nvme_mi_ctrl_t ctrl,
1982 enum nvme_cmd_get_log_lid lid,
1983 __u32 len, void *log)
1984 {
1985 return nvme_mi_admin_get_nsid_log(ctrl, false, lid, NVME_NSID_ALL,
1986 len, log);
1987 }
1988
1989 /**
1990 * nvme_mi_admin_get_log_supported_log_pages() - Retrieve nmve supported log
1991 * pages
1992 * @ctrl: Controller to query
1993 * @rae: Retain asynchronous events
1994 * @log: Array of LID supported and Effects data structures
1995 *
1996 * Return: The nvme command status if a response was received (see
1997 * &enum nvme_status_field) or -1 with errno set otherwise.
1998 */
1999 static inline int nvme_mi_admin_get_log_supported_log_pages(nvme_mi_ctrl_t ctrl,
2000 bool rae,
2001 struct nvme_supported_log_pages *log)
2002 {
2003 return nvme_mi_admin_get_nsid_log(ctrl, rae,
2004 NVME_LOG_LID_SUPPORTED_LOG_PAGES,
2005 NVME_NSID_ALL, sizeof(*log), log);
2006 }
2007
2008 /**
2009 * nvme_mi_admin_get_log_error() - Retrieve nvme error log
2010 * @ctrl: Controller to query
2011 * @nr_entries: Number of error log entries allocated
2012 * @rae: Retain asynchronous events
2013 * @err_log: Array of error logs of size 'entries'
2014 *
2015 * This log page describes extended error information for a command that
2016 * completed with error, or may report an error that is not specific to a
2017 * particular command.
2018 *
2019 * Return: The nvme command status if a response was received (see
2020 * &enum nvme_status_field) or -1 with errno set otherwise.
2021 */
2022 static inline int nvme_mi_admin_get_log_error(nvme_mi_ctrl_t ctrl,
2023 unsigned int nr_entries, bool rae,
2024 struct nvme_error_log_page *err_log)
2025 {
2026 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_ERROR,
2027 NVME_NSID_ALL, sizeof(*err_log) * nr_entries,
2028 err_log);
2029 }
2030
2031 /**
2032 * nvme_mi_admin_get_log_smart() - Retrieve nvme smart log
2033 * @ctrl: Controller to query
2034 * @nsid: Optional namespace identifier
2035 * @rae: Retain asynchronous events
2036 * @smart_log: User address to store the smart log
2037 *
2038 * This log page provides SMART and general health information. The information
2039 * provided is over the life of the controller and is retained across power
2040 * cycles. To request the controller log page, the namespace identifier
2041 * specified is FFFFFFFFh. The controller may also support requesting the log
2042 * page on a per namespace basis, as indicated by bit 0 of the LPA field in the
2043 * Identify Controller data structure.
2044 *
2045 * Return: The nvme command status if a response was received (see
2046 * &enum nvme_status_field) or -1 with errno set otherwise.
2047 */
2048 static inline int nvme_mi_admin_get_log_smart(nvme_mi_ctrl_t ctrl, __u32 nsid,
2049 bool rae,
2050 struct nvme_smart_log *smart_log)
2051 {
2052 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_SMART,
2053 nsid, sizeof(*smart_log), smart_log);
2054 }
2055
2056 /**
2057 * nvme_mi_admin_get_log_fw_slot() - Retrieves the controller firmware log
2058 * @ctrl: Controller to query
2059 * @rae: Retain asynchronous events
2060 * @fw_log: User address to store the log page
2061 *
2062 * This log page describes the firmware revision stored in each firmware slot
2063 * supported. The firmware revision is indicated as an ASCII string. The log
2064 * page also indicates the active slot number.
2065 *
2066 * Return: The nvme command status if a response was received (see
2067 * &enum nvme_status_field) or -1 with errno set otherwise.
2068 */
2069 static inline int nvme_mi_admin_get_log_fw_slot(nvme_mi_ctrl_t ctrl, bool rae,
2070 struct nvme_firmware_slot *fw_log)
2071 {
2072 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_FW_SLOT,
2073 NVME_NSID_ALL, sizeof(*fw_log), fw_log);
2074 }
2075
2076 /**
2077 * nvme_mi_admin_get_log_changed_ns_list() - Retrieve namespace changed list
2078 * @ctrl: Controller to query
2079 * @rae: Retain asynchronous events
2080 * @ns_log: User address to store the log page
2081 *
2082 * This log page describes namespaces attached to this controller that have
2083 * changed since the last time the namespace was identified, been added, or
2084 * deleted.
2085 *
2086 * Return: The nvme command status if a response was received (see
2087 * &enum nvme_status_field) or -1 with errno set otherwise.
2088 */
2089 static inline int nvme_mi_admin_get_log_changed_ns_list(nvme_mi_ctrl_t ctrl,
2090 bool rae,
2091 struct nvme_ns_list *ns_log)
2092 {
2093 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_CHANGED_NS,
2094 NVME_NSID_ALL, sizeof(*ns_log), ns_log);
2095 }
2096
2097 /**
2098 * nvme_mi_admin_get_log_cmd_effects() - Retrieve nvme command effects log
2099 * @ctrl: Controller to query
2100 * @csi: Command Set Identifier
2101 * @effects_log: User address to store the effects log
2102 *
2103 * This log page describes the commands that the controller supports and the
2104 * effects of those commands on the state of the NVM subsystem.
2105 *
2106 * Return: The nvme command status if a response was received (see
2107 * &enum nvme_status_field) or -1 with errno set otherwise.
2108 */
2109 static inline int nvme_mi_admin_get_log_cmd_effects(nvme_mi_ctrl_t ctrl,
2110 enum nvme_csi csi,
2111 struct nvme_cmd_effects_log *effects_log)
2112 {
2113 struct nvme_get_log_args args = {
2114 .lpo = 0,
2115 .result = NULL,
2116 .log = effects_log,
2117 .args_size = sizeof(args),
2118 .lid = NVME_LOG_LID_CMD_EFFECTS,
2119 .len = sizeof(*effects_log),
2120 .nsid = NVME_NSID_ALL,
2121 .csi = csi,
2122 .lsi = NVME_LOG_LSI_NONE,
2123 .lsp = NVME_LOG_LSP_NONE,
2124 .uuidx = NVME_UUID_NONE,
2125 .rae = false,
2126 .ot = false,
2127 };
2128 return nvme_mi_admin_get_log(ctrl, &args);
2129 }
2130
2131 /**
2132 * nvme_mi_admin_get_log_device_self_test() - Retrieve the device self test log
2133 * @ctrl: Controller to query
2134 * @log: Userspace address of the log payload
2135 *
2136 * The log page indicates the status of an in progress self test and the
2137 * percent complete of that operation, and the results of the previous 20
2138 * self-test operations.
2139 *
2140 * Return: The nvme command status if a response was received (see
2141 * &enum nvme_status_field) or -1 with errno set otherwise.
2142 */
2143 static inline int nvme_mi_admin_get_log_device_self_test(nvme_mi_ctrl_t ctrl,
2144 struct nvme_self_test_log *log)
2145 {
2146 return nvme_mi_admin_get_nsid_log(ctrl, false,
2147 NVME_LOG_LID_DEVICE_SELF_TEST,
2148 NVME_NSID_ALL, sizeof(*log), log);
2149 }
2150
2151 /**
2152 * nvme_mi_admin_get_log_create_telemetry_host_mcda() - Create host telemetry log
2153 * @ctrl: Controller to query
2154 * @mcda: Maximum Created Data Area
2155 * @log: Userspace address of the log payload
2156 *
2157 * Return: The nvme command status if a response was received (see
2158 * &enum nvme_status_field) or -1 with errno set otherwise.
2159 */
2160 static inline int nvme_mi_admin_get_log_create_telemetry_host_mcda(nvme_mi_ctrl_t ctrl,
2161 enum nvme_telemetry_da mcda,
2162 struct nvme_telemetry_log *log)
2163 {
2164 struct nvme_get_log_args args = {
2165 .lpo = 0,
2166 .result = NULL,
2167 .log = log,
2168 .args_size = sizeof(args),
2169 .lid = NVME_LOG_LID_TELEMETRY_HOST,
2170 .len = sizeof(*log),
2171 .nsid = NVME_NSID_NONE,
2172 .csi = NVME_CSI_NVM,
2173 .lsi = NVME_LOG_LSI_NONE,
2174 .lsp = (__u8)((mcda << 1) | NVME_LOG_TELEM_HOST_LSP_CREATE),
2175 .uuidx = NVME_UUID_NONE,
2176 .rae = false,
2177 .ot = false,
2178 };
2179 return nvme_mi_admin_get_log(ctrl, &args);
2180 }
2181
2182 /**
2183 * nvme_mi_admin_get_log_create_telemetry_host() - Create host telemetry log
2184 * @ctrl: Controller to query
2185 * @log: Userspace address of the log payload
2186 *
2187 * Return: The nvme command status if a response was received (see
2188 * &enum nvme_status_field) or -1 with errno set otherwise.
2189 */
2190 static inline int nvme_mi_admin_get_log_create_telemetry_host(nvme_mi_ctrl_t ctrl,
2191 struct nvme_telemetry_log *log)
2192 {
2193 return nvme_mi_admin_get_log_create_telemetry_host_mcda(ctrl, NVME_TELEMETRY_DA_CTRL_DETERMINE, log);
2194 }
2195
2196 /**
2197 * nvme_mi_admin_get_log_telemetry_host() - Get Telemetry Host-Initiated log
2198 * page
2199 * @ctrl: Controller to query
2200 * @offset: Offset into the telemetry data
2201 * @len: Length of provided user buffer to hold the log data in bytes
2202 * @log: User address for log page data
2203 *
2204 * Retrieves the Telemetry Host-Initiated log page at the requested offset
2205 * using the previously existing capture.
2206 *
2207 * Return: The nvme command status if a response was received (see
2208 * &enum nvme_status_field) or -1 with errno set otherwise.
2209 */
2210 static inline int nvme_mi_admin_get_log_telemetry_host(nvme_mi_ctrl_t ctrl,
2211 __u64 offset, __u32 len,
2212 void *log)
2213 {
2214 struct nvme_get_log_args args = {
2215 .lpo = offset,
2216 .result = NULL,
2217 .log = log,
2218 .args_size = sizeof(args),
2219 .lid = NVME_LOG_LID_TELEMETRY_HOST,
2220 .len = len,
2221 .nsid = NVME_NSID_NONE,
2222 .csi = NVME_CSI_NVM,
2223 .lsi = NVME_LOG_LSI_NONE,
2224 .lsp = NVME_LOG_TELEM_HOST_LSP_RETAIN,
2225 .uuidx = NVME_UUID_NONE,
2226 .rae = false,
2227 .ot = false,
2228 };
2229 return nvme_mi_admin_get_log(ctrl, &args);
2230 }
2231
2232 /**
2233 * nvme_mi_admin_get_log_telemetry_ctrl() - Get Telemetry Controller-Initiated
2234 * log page
2235 * @ctrl: Controller to query
2236 * @rae: Retain asynchronous events
2237 * @offset: Offset into the telemetry data
2238 * @len: Length of provided user buffer to hold the log data in bytes
2239 * @log: User address for log page data
2240 *
2241 * Retrieves the Telemetry Controller-Initiated log page at the requested offset
2242 * using the previously existing capture.
2243 *
2244 * Return: The nvme command status if a response was received (see
2245 * &enum nvme_status_field) or -1 with errno set otherwise.
2246 */
2247 static inline int nvme_mi_admin_get_log_telemetry_ctrl(nvme_mi_ctrl_t ctrl,
2248 bool rae,
2249 __u64 offset, __u32 len,
2250 void *log)
2251 {
2252 struct nvme_get_log_args args = {
2253 .lpo = offset,
2254 .result = NULL,
2255 .log = log,
2256 .args_size = sizeof(args),
2257 .lid = NVME_LOG_LID_TELEMETRY_CTRL,
2258 .len = len,
2259 .nsid = NVME_NSID_NONE,
2260 .csi = NVME_CSI_NVM,
2261 .lsi = NVME_LOG_LSI_NONE,
2262 .lsp = NVME_LOG_LSP_NONE,
2263 .uuidx = NVME_UUID_NONE,
2264 .rae = rae,
2265 .ot = false,
2266 };
2267 return nvme_mi_admin_get_log(ctrl, &args);
2268 }
2269
2270 /**
2271 * nvme_mi_admin_get_log_endurance_group() - Get Endurance Group log
2272 * @ctrl: Controller to query
2273 * @endgid: Starting group identifier to return in the list
2274 * @log: User address to store the endurance log
2275 *
2276 * This log page indicates if an Endurance Group Event has occurred for a
2277 * particular Endurance Group. If an Endurance Group Event has occurred, the
2278 * details of the particular event are included in the Endurance Group
2279 * Information log page for that Endurance Group. An asynchronous event is
2280 * generated when an entry for an Endurance Group is newly added to this log
2281 * page.
2282 *
2283 * Return: The nvme command status if a response was received (see
2284 * &enum nvme_status_field) or -1 with errno set otherwise.
2285 */
2286 static inline int nvme_mi_admin_get_log_endurance_group(nvme_mi_ctrl_t ctrl,
2287 __u16 endgid,
2288 struct nvme_endurance_group_log *log)
2289 {
2290 struct nvme_get_log_args args = {
2291 .lpo = 0,
2292 .result = NULL,
2293 .log = log,
2294 .args_size = sizeof(args),
2295 .lid = NVME_LOG_LID_ENDURANCE_GROUP,
2296 .len = sizeof(*log),
2297 .nsid = NVME_NSID_NONE,
2298 .csi = NVME_CSI_NVM,
2299 .lsi = endgid,
2300 .lsp = NVME_LOG_LSP_NONE,
2301 .uuidx = NVME_UUID_NONE,
2302 .rae = false,
2303 .ot = false,
2304 };
2305 return nvme_mi_admin_get_log(ctrl, &args);
2306 }
2307
2308 /**
2309 * nvme_mi_admin_get_log_predictable_lat_nvmset() - Predictable Latency Per NVM
2310 * Set
2311 * @ctrl: Controller to query
2312 * @nvmsetid: NVM set id
2313 * @log: User address to store the predictable latency log
2314 *
2315 * Return: The nvme command status if a response was received (see
2316 * &enum nvme_status_field) or -1 with errno set otherwise.
2317 */
2318 static inline int nvme_mi_admin_get_log_predictable_lat_nvmset(nvme_mi_ctrl_t ctrl,
2319 __u16 nvmsetid,
2320 struct nvme_nvmset_predictable_lat_log *log)
2321 {
2322 struct nvme_get_log_args args = {
2323 .lpo = 0,
2324 .result = NULL,
2325 .log = log,
2326 .args_size = sizeof(args),
2327 .lid = NVME_LOG_LID_PREDICTABLE_LAT_NVMSET,
2328 .len = sizeof(*log),
2329 .nsid = NVME_NSID_NONE,
2330 .csi = NVME_CSI_NVM,
2331 .lsi = nvmsetid,
2332 .lsp = NVME_LOG_LSP_NONE,
2333 .uuidx = NVME_UUID_NONE,
2334 .rae = false,
2335 .ot = false,
2336 };
2337 return nvme_mi_admin_get_log(ctrl, &args);
2338 }
2339
2340 /**
2341 * nvme_mi_admin_get_log_predictable_lat_event() - Retrieve Predictable Latency
2342 * Event Aggregate Log Page
2343 * @ctrl: Controller to query
2344 * @rae: Retain asynchronous events
2345 * @offset: Offset into the predictable latency event
2346 * @len: Length of provided user buffer to hold the log data in bytes
2347 * @log: User address for log page data
2348 *
2349 * Return: The nvme command status if a response was received (see
2350 * &enum nvme_status_field) or -1 with errno set otherwise.
2351 */
2352 static inline int nvme_mi_admin_get_log_predictable_lat_event(nvme_mi_ctrl_t ctrl,
2353 bool rae,
2354 __u32 offset,
2355 __u32 len,
2356 void *log)
2357 {
2358 struct nvme_get_log_args args = {
2359 .lpo = offset,
2360 .result = NULL,
2361 .log = log,
2362 .args_size = sizeof(args),
2363 .lid = NVME_LOG_LID_PREDICTABLE_LAT_AGG,
2364 .len = len,
2365 .nsid = NVME_NSID_NONE,
2366 .csi = NVME_CSI_NVM,
2367 .lsi = NVME_LOG_LSI_NONE,
2368 .lsp = NVME_LOG_LSP_NONE,
2369 .uuidx = NVME_UUID_NONE,
2370 .rae = rae,
2371 .ot = false,
2372 };
2373 return nvme_mi_admin_get_log(ctrl, &args);
2374 }
2375
2376 /**
2377 * nvme_mi_admin_get_log_ana() - Retrieve Asymmetric Namespace Access log page
2378 * @ctrl: Controller to query
2379 * @lsp: Log specific, see &enum nvme_get_log_ana_lsp
2380 * @rae: Retain asynchronous events
2381 * @offset: Offset to the start of the log page
2382 * @len: The allocated length of the log page
2383 * @log: User address to store the ana log
2384 *
2385 * This log consists of a header describing the log and descriptors containing
2386 * the asymmetric namespace access information for ANA Groups that contain
2387 * namespaces that are attached to the controller processing the command.
2388 *
2389 * See &struct nvme_ana_log for the definition of the returned structure.
2390 *
2391 * Return: The nvme command status if a response was received (see
2392 * &enum nvme_status_field) or -1 with errno set otherwise.
2393 */
2394 static inline int nvme_mi_admin_get_log_ana(nvme_mi_ctrl_t ctrl,
2395 enum nvme_log_ana_lsp lsp, bool rae,
2396 __u64 offset, __u32 len, void *log)
2397 {
2398 struct nvme_get_log_args args = {
2399 .lpo = offset,
2400 .result = NULL,
2401 .log = log,
2402 .args_size = sizeof(args),
2403 .lid = NVME_LOG_LID_ANA,
2404 .len = len,
2405 .nsid = NVME_NSID_NONE,
2406 .csi = NVME_CSI_NVM,
2407 .lsi = NVME_LOG_LSI_NONE,
2408 .lsp = (__u8)lsp,
2409 .uuidx = NVME_UUID_NONE,
2410 .rae = rae,
2411 .ot = false,
2412 };
2413 return nvme_mi_admin_get_log(ctrl, &args);
2414 }
2415
2416 /**
2417 * nvme_mi_admin_get_log_ana_groups() - Retrieve Asymmetric Namespace Access
2418 * groups only log page
2419 * @ctrl: Controller to query
2420 * @rae: Retain asynchronous events
2421 * @len: The allocated length of the log page
2422 * @log: User address to store the ana group log
2423 *
2424 * See &struct nvme_ana_group_desc for the definition of the returned structure.
2425 *
2426 * Return: The nvme command status if a response was received (see
2427 * &enum nvme_status_field) or -1 with errno set otherwise.
2428 */
2429 static inline int nvme_mi_admin_get_log_ana_groups(nvme_mi_ctrl_t ctrl,
2430 bool rae, __u32 len,
2431 struct nvme_ana_group_desc *log)
2432 {
2433 return nvme_mi_admin_get_log_ana(ctrl, NVME_LOG_ANA_LSP_RGO_GROUPS_ONLY, rae, 0,
2434 len, log);
2435 }
2436
2437 /**
2438 * nvme_mi_admin_get_ana_log_atomic() - Retrieve Asymmetric Namespace Access
2439 * log page atomically
2440 * @ctrl: Controller to query
2441 * @rgo: Whether to retrieve ANA groups only (no NSIDs)
2442 * @rae: Whether to retain asynchronous events
2443 * @retries: The maximum number of times to retry on log page changes
2444 * @log: Pointer to a buffer to receive the ANA log page
2445 * @len: Input: the length of the log page buffer.
2446 * Output: the actual length of the ANA log page.
2447 *
2448 * See &struct nvme_ana_log for the definition of the returned structure.
2449 *
2450 * Return: If successful, returns 0 and sets *len to the actual log page length.
2451 * If unsuccessful, returns the nvme command status if a response was received
2452 * (see &enum nvme_status_field) or -1 with errno set otherwise.
2453 * Sets errno = EINVAL if retries == 0.
2454 * Sets errno = EAGAIN if unable to read the log page atomically
2455 * because chgcnt changed during each of the retries attempts.
2456 * Sets errno = ENOSPC if the full log page does not fit in the provided buffer.
2457 */
2458 int nvme_mi_admin_get_ana_log_atomic(nvme_mi_ctrl_t ctrl, bool rgo, bool rae,
2459 unsigned int retries,
2460 struct nvme_ana_log *log, __u32 *len);
2461
2462 /**
2463 * nvme_mi_admin_get_log_lba_status() - Retrieve LBA Status
2464 * @ctrl: Controller to query
2465 * @rae: Retain asynchronous events
2466 * @offset: Offset to the start of the log page
2467 * @len: The allocated length of the log page
2468 * @log: User address to store the log page
2469 *
2470 * Return: The nvme command status if a response was received (see
2471 * &enum nvme_status_field) or -1 with errno set otherwise.
2472 */
2473 static inline int nvme_mi_admin_get_log_lba_status(nvme_mi_ctrl_t ctrl, bool rae,
2474 __u64 offset, __u32 len,
2475 void *log)
2476 {
2477 struct nvme_get_log_args args = {
2478 .lpo = offset,
2479 .result = NULL,
2480 .log = log,
2481 .args_size = sizeof(args),
2482 .lid = NVME_LOG_LID_LBA_STATUS,
2483 .len = len,
2484 .nsid = NVME_NSID_NONE,
2485 .csi = NVME_CSI_NVM,
2486 .lsi = NVME_LOG_LSI_NONE,
2487 .lsp = NVME_LOG_LSP_NONE,
2488 .uuidx = NVME_UUID_NONE,
2489 .rae = rae,
2490 .ot = false,
2491 };
2492 return nvme_mi_admin_get_log(ctrl, &args);
2493 }
2494
2495 /**
2496 * nvme_mi_admin_get_log_endurance_grp_evt() - Retrieve Rotational Media
2497 * Information
2498 * @ctrl: Controller to query
2499 * @rae: Retain asynchronous events
2500 * @offset: Offset to the start of the log page
2501 * @len: The allocated length of the log page
2502 * @log: User address to store the log page
2503 *
2504 * Return: The nvme command status if a response was received (see
2505 * &enum nvme_status_field) or -1 with errno set otherwise.
2506 */
2507 static inline int nvme_mi_admin_get_log_endurance_grp_evt(nvme_mi_ctrl_t ctrl,
2508 bool rae,
2509 __u32 offset,
2510 __u32 len,
2511 void *log)
2512 {
2513 struct nvme_get_log_args args = {
2514 .lpo = offset,
2515 .result = NULL,
2516 .log = log,
2517 .args_size = sizeof(args),
2518 .lid = NVME_LOG_LID_ENDURANCE_GRP_EVT,
2519 .len = len,
2520 .nsid = NVME_NSID_NONE,
2521 .csi = NVME_CSI_NVM,
2522 .lsi = NVME_LOG_LSI_NONE,
2523 .lsp = NVME_LOG_LSP_NONE,
2524 .uuidx = NVME_UUID_NONE,
2525 .rae = rae,
2526 .ot = false,
2527 };
2528 return nvme_mi_admin_get_log(ctrl, &args);
2529 }
2530
2531 /**
2532 * nvme_mi_admin_get_log_fid_supported_effects() - Retrieve Feature Identifiers
2533 * Supported and Effects
2534 * @ctrl: Controller to query
2535 * @rae: Retain asynchronous events
2536 * @log: FID Supported and Effects data structure
2537 *
2538 * Return: The nvme command status if a response was received (see
2539 * &enum nvme_status_field) or -1 with errno set otherwise.
2540 */
2541 static inline int nvme_mi_admin_get_log_fid_supported_effects(nvme_mi_ctrl_t ctrl,
2542 bool rae,
2543 struct nvme_fid_supported_effects_log *log)
2544 {
2545 return nvme_mi_admin_get_nsid_log(ctrl, rae,
2546 NVME_LOG_LID_FID_SUPPORTED_EFFECTS,
2547 NVME_NSID_NONE, sizeof(*log), log);
2548 }
2549
2550 /**
2551 * nvme_mi_admin_get_log_mi_cmd_supported_effects() - displays the MI Commands
2552 * Supported by the controller
2553 * @ctrl: Controller to query
2554 * @rae: Retain asynchronous events
2555 * @log: MI Command Supported and Effects data structure
2556 *
2557 * Return: The nvme command status if a response was received (see
2558 * &enum nvme_status_field) or -1 with errno set otherwise.
2559 */
2560 static inline int nvme_mi_admin_get_log_mi_cmd_supported_effects(nvme_mi_ctrl_t ctrl,
2561 bool rae,
2562 struct nvme_mi_cmd_supported_effects_log *log)
2563 {
2564 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_MI_CMD_SUPPORTED_EFFECTS,
2565 NVME_NSID_NONE, sizeof(*log), log);
2566 }
2567
2568 /**
2569 * nvme_mi_admin_get_log_boot_partition() - Retrieve Boot Partition
2570 * @ctrl: Controller to query
2571 * @rae: Retain asynchronous events
2572 * @lsp: The log specified field of LID
2573 * @len: The allocated size, minimum
2574 * struct nvme_boot_partition
2575 * @part: User address to store the log page
2576 *
2577 * Return: The nvme command status if a response was received (see
2578 * &enum nvme_status_field) or -1 with errno set otherwise.
2579 */
2580 static inline int nvme_mi_admin_get_log_boot_partition(nvme_mi_ctrl_t ctrl,
2581 bool rae, __u8 lsp,
2582 __u32 len,
2583 struct nvme_boot_partition *part)
2584 {
2585 struct nvme_get_log_args args = {
2586 .lpo = 0,
2587 .result = NULL,
2588 .log = part,
2589 .args_size = sizeof(args),
2590 .lid = NVME_LOG_LID_BOOT_PARTITION,
2591 .len = len,
2592 .nsid = NVME_NSID_NONE,
2593 .csi = NVME_CSI_NVM,
2594 .lsi = NVME_LOG_LSI_NONE,
2595 .lsp = NVME_LOG_LSP_NONE,
2596 .uuidx = NVME_UUID_NONE,
2597 .rae = rae,
2598 .ot = false,
2599 };
2600 return nvme_mi_admin_get_log(ctrl, &args);
2601 }
2602
2603 /**
2604 * nvme_mi_admin_get_log_rotational_media_info() - Retrieve Rotational Media Information Log
2605 * @ctrl: Controller to query
2606 * @endgid: Endurance Group Identifier
2607 * @len: The allocated length of the log page
2608 * @log: User address to store the log page
2609 *
2610 * Return: The nvme command status if a response was received (see
2611 * &enum nvme_status_field) or -1 with errno set otherwise
2612 */
2613 static inline int nvme_mi_admin_get_log_rotational_media_info(nvme_mi_ctrl_t ctrl, __u16 endgid,
2614 __u32 len,
2615 struct nvme_rotational_media_info_log *log)
2616 {
2617 return nvme_mi_admin_get_endgid_log(ctrl, false, NVME_LOG_LID_ROTATIONAL_MEDIA_INFO, endgid,
2618 len, log);
2619 }
2620
2621 /**
2622 * nvme_mi_admin_get_log_dispersed_ns_participating_nss() - Retrieve Dispersed Namespace
2623 * Participating NVM Subsystems Log
2624 * @ctrl: Controller to query
2625 * @nsid: Namespace Identifier
2626 * @len: The allocated length of the log page
2627 * @log: User address to store the log page
2628 *
2629 * Return: The nvme command status if a response was received (see
2630 * &enum nvme_status_field) or -1 with errno set otherwise
2631 */
2632 static inline int nvme_mi_admin_get_log_dispersed_ns_participating_nss(nvme_mi_ctrl_t ctrl,
2633 __u32 nsid, __u32 len,
2634 struct nvme_dispersed_ns_participating_nss_log *log)
2635 {
2636 return nvme_mi_admin_get_nsid_log(ctrl, false, NVME_LOG_LID_DISPERSED_NS_PARTICIPATING_NSS,
2637 nsid, len, log);
2638 }
2639
2640 /**
2641 * nvme_mi_admin_get_log_mgmt_addr_list() - Retrieve Management Address List Log
2642 * @ctrl: Controller to query
2643 * @len: The allocated length of the log page
2644 * @log: User address to store the log page
2645 *
2646 * Return: The nvme command status if a response was received (see
2647 * &enum nvme_status_field) or -1 with errno set otherwise
2648 */
2649 static inline int nvme_mi_admin_get_log_mgmt_addr_list(nvme_mi_ctrl_t ctrl, __u32 len,
2650 struct nvme_mgmt_addr_list_log *log)
2651 {
2652 return nvme_mi_admin_get_log_simple(ctrl, NVME_LOG_LID_MGMT_ADDR_LIST, len, log);
2653 }
2654
2655 /**
2656 * nvme_mi_admin_get_log_phy_rx_eom() - Retrieve Physical Interface Receiver Eye Opening Measurement Log
2657 * @ctrl: Controller to query
2658 * @lsp: Log specific, controls action and measurement quality
2659 * @controller: Target controller ID
2660 * @len: The allocated size, minimum
2661 * struct nvme_phy_rx_eom_log
2662 * @log: User address to store the log page
2663 *
2664 * Return: The nvme command status if a response was received (see
2665 * &enum nvme_status_field) or -1 with errno set otherwise
2666 */
2667 static inline int nvme_mi_admin_get_log_phy_rx_eom(nvme_mi_ctrl_t ctrl,
2668 __u8 lsp, __u16 controller,
2669 __u32 len,
2670 struct nvme_phy_rx_eom_log *log)
2671 {
2672 struct nvme_get_log_args args = {
2673 .lpo = 0,
2674 .result = NULL,
2675 .log = log,
2676 .args_size = sizeof(args),
2677 .lid = NVME_LOG_LID_PHY_RX_EOM,
2678 .len = len,
2679 .nsid = NVME_NSID_NONE,
2680 .csi = NVME_CSI_NVM,
2681 .lsi = controller,
2682 .lsp = lsp,
2683 .uuidx = NVME_UUID_NONE,
2684 .rae = false,
2685 .ot = false,
2686 };
2687 return nvme_mi_admin_get_log(ctrl, &args);
2688 }
2689
2690 /**
2691 * nvme_mi_admin_get_log_reachability_groups() - Retrieve Reachability Groups Log
2692 * @ctrl: Controller to query
2693 * @rgo: Return groups only
2694 * @rae: Retain asynchronous events
2695 * @len: The allocated length of the log page
2696 * @log: User address to store the log page
2697 *
2698 * Return: The nvme command status if a response was received (see
2699 * &enum nvme_status_field) or -1 with errno set otherwise
2700 */
2701 static inline int nvme_mi_admin_get_log_reachability_groups(nvme_mi_ctrl_t ctrl, bool rgo, bool rae,
2702 __u32 len, struct nvme_reachability_groups_log *log)
2703 {
2704 struct nvme_get_log_args args = {
2705 .lpo = 0,
2706 .result = NULL,
2707 .log = log,
2708 .args_size = sizeof(args),
2709 .timeout = NVME_DEFAULT_IOCTL_TIMEOUT,
2710 .lid = NVME_LOG_LID_REACHABILITY_GROUPS,
2711 .len = len,
2712 .nsid = NVME_NSID_ALL,
2713 .csi = NVME_CSI_NVM,
2714 .lsi = NVME_LOG_LSI_NONE,
2715 .lsp = rgo,
2716 .uuidx = NVME_LOG_LSP_NONE,
2717 .rae = rae,
2718 .ot = false,
2719 };
2720
2721 return nvme_mi_admin_get_log_page(ctrl, NVME_LOG_PAGE_PDU_SIZE, &args);
2722 }
2723
2724 /**
2725 * nvme_mi_admin_get_log_reachability_associations() - Retrieve Reachability Associations Log
2726 * @ctrl: Controller to query
2727 * @rao: Return associations only
2728 * @rae: Retain asynchronous events
2729 * @len: The allocated length of the log page
2730 * @log: User address to store the log page
2731 *
2732 * Return: The nvme command status if a response was received (see
2733 * &enum nvme_status_field) or -1 with errno set otherwise
2734 */
2735 static inline int nvme_mi_admin_get_log_reachability_associations(nvme_mi_ctrl_t ctrl, bool rao,
2736 bool rae, __u32 len,
2737 struct nvme_reachability_associations_log *log)
2738 {
2739 struct nvme_get_log_args args = {
2740 .lpo = 0,
2741 .result = NULL,
2742 .log = log,
2743 .args_size = sizeof(args),
2744 .timeout = NVME_DEFAULT_IOCTL_TIMEOUT,
2745 .lid = NVME_LOG_LID_REACHABILITY_ASSOCIATIONS,
2746 .len = len,
2747 .nsid = NVME_NSID_ALL,
2748 .csi = NVME_CSI_NVM,
2749 .lsi = NVME_LOG_LSI_NONE,
2750 .lsp = rao,
2751 .uuidx = NVME_LOG_LSP_NONE,
2752 .rae = rae,
2753 .ot = false,
2754 };
2755
2756 return nvme_mi_admin_get_log_page(ctrl, NVME_LOG_PAGE_PDU_SIZE, &args);
2757 }
2758
2759 /**
2760 * nvme_mi_admin_get_log_changed_alloc_ns_list() - Retrieve Changed Allocated Namespace List Log
2761 * @ctrl: Controller to query
2762 * @rae: Retain asynchronous events
2763 * @len: The allocated length of the log page
2764 * @log: User address to store the log page
2765 *
2766 * Return: The nvme command status if a response was received (see
2767 * &enum nvme_status_field) or -1 with errno set otherwise
2768 */
2769 static inline int nvme_mi_admin_get_log_changed_alloc_ns_list(nvme_mi_ctrl_t ctrl, bool rae,
2770 __u32 len, struct nvme_ns_list *log)
2771 {
2772 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_CHANGED_ALLOC_NS_LIST,
2773 NVME_NSID_ALL, len, log);
2774 }
2775
2776 /**
2777 * nvme_mi_admin_get_log_discovery() - Retrieve Discovery log page
2778 * @ctrl: Controller to query
2779 * @rae: Retain asynchronous events
2780 * @offset: Offset of this log to retrieve
2781 * @len: The allocated size for this portion of the log
2782 * @log: User address to store the discovery log
2783 *
2784 * Supported only by fabrics discovery controllers, returning discovery
2785 * records.
2786 *
2787 * Return: The nvme command status if a response was received (see
2788 * &enum nvme_status_field) or -1 with errno set otherwise.
2789 */
2790 static inline int nvme_mi_admin_get_log_discovery(nvme_mi_ctrl_t ctrl, bool rae,
2791 __u32 offset, __u32 len,
2792 void *log)
2793 {
2794 struct nvme_get_log_args args = {
2795 .lpo = offset,
2796 .result = NULL,
2797 .log = log,
2798 .args_size = sizeof(args),
2799 .lid = NVME_LOG_LID_DISCOVER,
2800 .len = len,
2801 .nsid = NVME_NSID_NONE,
2802 .csi = NVME_CSI_NVM,
2803 .lsi = NVME_LOG_LSI_NONE,
2804 .lsp = NVME_LOG_LSP_NONE,
2805 .uuidx = NVME_UUID_NONE,
2806 .rae = rae,
2807 .ot = false,
2808 };
2809 return nvme_mi_admin_get_log(ctrl, &args);
2810 }
2811
2812 /**
2813 * nvme_mi_admin_get_log_host_discover() - Retrieve Host Discovery Log
2814 * @ctrl: Controller to query
2815 * @allhoste: All host entries
2816 * @rae: Retain asynchronous events
2817 * @len: The allocated length of the log page
2818 * @log: User address to store the log page
2819 *
2820 * Return: The nvme command status if a response was received (see
2821 * &enum nvme_status_field) or -1 with errno set otherwise
2822 */
2823 static inline int nvme_mi_admin_get_log_host_discover(nvme_mi_ctrl_t ctrl, bool allhoste, bool rae,
2824 __u32 len, struct nvme_host_discover_log *log)
2825 {
2826 struct nvme_get_log_args args = {
2827 .lpo = 0,
2828 .result = NULL,
2829 .log = log,
2830 .args_size = sizeof(args),
2831 .timeout = NVME_DEFAULT_IOCTL_TIMEOUT,
2832 .lid = NVME_LOG_LID_HOST_DISCOVER,
2833 .len = len,
2834 .nsid = NVME_NSID_ALL,
2835 .csi = NVME_CSI_NVM,
2836 .lsi = NVME_LOG_LSI_NONE,
2837 .lsp = allhoste,
2838 .uuidx = NVME_LOG_LSP_NONE,
2839 .rae = rae,
2840 .ot = false,
2841 };
2842
2843 return nvme_mi_admin_get_log_page(ctrl, NVME_LOG_PAGE_PDU_SIZE, &args);
2844 }
2845
2846 /**
2847 * nvme_mi_admin_get_log_ave_discover() - Retrieve AVE Discovery Log
2848 * @ctrl: Controller to query
2849 * @rae: Retain asynchronous events
2850 * @len: The allocated length of the log page
2851 * @log: User address to store the log page
2852 *
2853 * Return: The nvme command status if a response was received (see
2854 * &enum nvme_status_field) or -1 with errno set otherwise
2855 */
2856 static inline int nvme_mi_admin_get_log_ave_discover(nvme_mi_ctrl_t ctrl, bool rae, __u32 len,
2857 struct nvme_ave_discover_log *log)
2858 {
2859 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_AVE_DISCOVER, NVME_NSID_ALL, len,
2860 log);
2861 }
2862
2863 /**
2864 * nvme_mi_admin_get_log_pull_model_ddc_req() - Retrieve Pull Model DDC Request Log
2865 * @ctrl: Controller to query
2866 * @rae: Retain asynchronous events
2867 * @len: The allocated length of the log page
2868 * @log: User address to store the log page
2869 *
2870 * Return: The nvme command status if a response was received (see
2871 * &enum nvme_status_field) or -1 with errno set otherwise
2872 */
2873 static inline int nvme_mi_admin_get_log_pull_model_ddc_req(nvme_mi_ctrl_t ctrl, bool rae, __u32 len,
2874 struct nvme_pull_model_ddc_req_log *log)
2875 {
2876 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_PULL_MODEL_DDC_REQ, NVME_NSID_ALL,
2877 len, log);
2878 }
2879
2880 /**
2881 * nvme_mi_admin_get_log_media_unit_stat() - Retrieve Media Unit Status
2882 * @ctrl: Controller to query
2883 * @domid: Domain Identifier selection, if supported
2884 * @mus: User address to store the Media Unit statistics log
2885 *
2886 * Return: The nvme command status if a response was received (see
2887 * &enum nvme_status_field) or -1 with errno set otherwise.
2888 */
2889 static inline int nvme_mi_admin_get_log_media_unit_stat(nvme_mi_ctrl_t ctrl,
2890 __u16 domid,
2891 struct nvme_media_unit_stat_log *mus)
2892 {
2893 struct nvme_get_log_args args = {
2894 .lpo = 0,
2895 .result = NULL,
2896 .log = mus,
2897 .args_size = sizeof(args),
2898 .lid = NVME_LOG_LID_MEDIA_UNIT_STATUS,
2899 .len = sizeof(*mus),
2900 .nsid = NVME_NSID_NONE,
2901 .csi = NVME_CSI_NVM,
2902 .lsi = domid,
2903 .lsp = NVME_LOG_LSP_NONE,
2904 .uuidx = NVME_UUID_NONE,
2905 .rae = false,
2906 .ot = false,
2907 };
2908 return nvme_mi_admin_get_log(ctrl, &args);
2909 }
2910
2911 /**
2912 * nvme_mi_admin_get_log_support_cap_config_list() - Retrieve Supported
2913 * Capacity Configuration List
2914 * @ctrl: Controller to query
2915 * @domid: Domain Identifier selection, if supported
2916 * @cap: User address to store supported capabilities config list
2917 *
2918 * Return: The nvme command status if a response was received (see
2919 * &enum nvme_status_field) or -1 with errno set otherwise.
2920 */
2921 static inline int nvme_mi_admin_get_log_support_cap_config_list(nvme_mi_ctrl_t ctrl,
2922 __u16 domid,
2923 struct nvme_supported_cap_config_list_log *cap)
2924 {
2925 struct nvme_get_log_args args = {
2926 .lpo = 0,
2927 .result = NULL,
2928 .log = cap,
2929 .args_size = sizeof(args),
2930 .lid = NVME_LOG_LID_SUPPORTED_CAP_CONFIG_LIST,
2931 .len = sizeof(*cap),
2932 .nsid = NVME_NSID_NONE,
2933 .csi = NVME_CSI_NVM,
2934 .lsi = domid,
2935 .lsp = NVME_LOG_LSP_NONE,
2936 .uuidx = NVME_UUID_NONE,
2937 .rae = false,
2938 .ot = false,
2939 };
2940 return nvme_mi_admin_get_log(ctrl, &args);
2941 }
2942
2943 /**
2944 * nvme_mi_admin_get_log_reservation() - Retrieve Reservation Notification
2945 * @ctrl: Controller to query
2946 * @rae: Retain asynchronous events
2947 * @log: User address to store the reservation log
2948 *
2949 * Return: The nvme command status if a response was received (see
2950 * &enum nvme_status_field) or -1 with errno set otherwise.
2951 */
2952 static inline int nvme_mi_admin_get_log_reservation(nvme_mi_ctrl_t ctrl,
2953 bool rae,
2954 struct nvme_resv_notification_log *log)
2955 {
2956 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_RESERVATION,
2957 NVME_NSID_ALL, sizeof(*log), log);
2958 }
2959
2960 /**
2961 * nvme_mi_admin_get_log_sanitize() - Retrieve Sanitize Status
2962 * @ctrl: Controller to query
2963 * @rae: Retain asynchronous events
2964 * @log: User address to store the sanitize log
2965 *
2966 * The Sanitize Status log page reports sanitize operation time estimates and
2967 * information about the most recent sanitize operation.
2968 *
2969 * Return: The nvme command status if a response was received (see
2970 * &enum nvme_status_field) or -1 with errno set otherwise.
2971 */
2972 static inline int nvme_mi_admin_get_log_sanitize(nvme_mi_ctrl_t ctrl, bool rae,
2973 struct nvme_sanitize_log_page *log)
2974 {
2975 return nvme_mi_admin_get_nsid_log(ctrl, rae, NVME_LOG_LID_SANITIZE,
2976 NVME_NSID_ALL, sizeof(*log), log);
2977 }
2978
2979 /**
2980 * nvme_mi_admin_get_log_zns_changed_zones() - Retrieve list of zones that have
2981 * changed
2982 * @ctrl: Controller to query
2983 * @nsid: Namespace ID
2984 * @rae: Retain asynchronous events
2985 * @log: User address to store the changed zone log
2986 *
2987 * The list of zones that have changed state due to an exceptional event.
2988 *
2989 * Return: The nvme command status if a response was received (see
2990 * &enum nvme_status_field) or -1 with errno set otherwise.
2991 */
2992 static inline int nvme_mi_admin_get_log_zns_changed_zones(nvme_mi_ctrl_t ctrl,
2993 __u32 nsid, bool rae,
2994 struct nvme_zns_changed_zone_log *log)
2995 {
2996 struct nvme_get_log_args args = {
2997 .lpo = 0,
2998 .result = NULL,
2999 .log = log,
3000 .args_size = sizeof(args),
3001 .lid = NVME_LOG_LID_ZNS_CHANGED_ZONES,
3002 .len = sizeof(*log),
3003 .nsid = nsid,
3004 .csi = NVME_CSI_ZNS,
3005 .lsi = NVME_LOG_LSI_NONE,
3006 .lsp = NVME_LOG_LSP_NONE,
3007 .uuidx = NVME_UUID_NONE,
3008 .rae = rae,
3009 .ot = false,
3010 };
3011 return nvme_mi_admin_get_log(ctrl, &args);
3012 }
3013
3014 /**
3015 * nvme_mi_admin_get_log_persistent_event() - Retrieve Persistent Event Log
3016 * @ctrl: Controller to query
3017 * @action: Action the controller should take during processing this command
3018 * @size: Size of @pevent_log
3019 * @pevent_log: User address to store the persistent event log
3020 *
3021 * Return: The nvme command status if a response was received (see
3022 * &enum nvme_status_field) or -1 with errno set otherwise.
3023 */
3024 static inline int nvme_mi_admin_get_log_persistent_event(nvme_mi_ctrl_t ctrl,
3025 enum nvme_pevent_log_action action,
3026 __u32 size, void *pevent_log)
3027 {
3028 struct nvme_get_log_args args = {
3029 .lpo = 0,
3030 .result = NULL,
3031 .log = pevent_log,
3032 .args_size = sizeof(args),
3033 .lid = NVME_LOG_LID_PERSISTENT_EVENT,
3034 .len = size,
3035 .nsid = NVME_NSID_ALL,
3036 .csi = NVME_CSI_NVM,
3037 .lsi = NVME_LOG_LSI_NONE,
3038 .lsp = (__u8)action,
3039 .uuidx = NVME_UUID_NONE,
3040 .rae = false,
3041 .ot = false,
3042 };
3043 return nvme_mi_admin_get_log(ctrl, &args);
3044 }
3045
3046 /**
3047 * nvme_mi_admin_get_log_lockdown() - Retrieve lockdown Log
3048 * @ctrl: Controller to query
3049 * @cnscp: Contents and Scope of Command and Feature Identifier Lists
3050 * @lockdown_log: Buffer to store the lockdown log
3051 *
3052 * Return: The nvme command status if a response was received (see
3053 * &enum nvme_status_field) or -1 with errno set otherwise.
3054 */
3055 static inline int nvme_mi_admin_get_log_lockdown(nvme_mi_ctrl_t ctrl,
3056 __u8 cnscp, struct nvme_lockdown_log *lockdown_log)
3057 {
3058 struct nvme_get_log_args args = {
3059 .lpo = 0,
3060 .result = NULL,
3061 .log = lockdown_log,
3062 .args_size = sizeof(args),
3063 .lid = NVME_LOG_LID_CMD_AND_FEAT_LOCKDOWN,
3064 .len = sizeof(*lockdown_log),
3065 .nsid = NVME_NSID_ALL,
3066 .csi = NVME_CSI_NVM,
3067 .lsi = NVME_LOG_LSI_NONE,
3068 .lsp = cnscp,
3069 .uuidx = NVME_UUID_NONE,
3070 .rae = false,
3071 .ot = false,
3072 };
3073 return nvme_mi_admin_get_log(ctrl, &args);
3074 }
3075
3076 /**
3077 * nvme_mi_admin_security_send() - Perform a Security Send command on a
3078 * controller.
3079 * @ctrl: Controller to send command to
3080 * @args: Security Send command arguments
3081 *
3082 * Performs a Security Send Admin command as specified by @args. Response data
3083 * is stored in @args->data, which should be a buffer of @args->data_len bytes.
3084 * Resulting data length is stored in @args->data_len on successful
3085 * command completion.
3086 *
3087 * Security Send data length should not be greater than 4096 bytes to
3088 * comply with specification limits.
3089 *
3090 * Return: The nvme command status if a response was received (see
3091 * &enum nvme_status_field) or -1 with errno set otherwise.
3092 *
3093 * See: &struct nvme_get_log_args
3094 */
3095 int nvme_mi_admin_security_send(nvme_mi_ctrl_t ctrl,
3096 struct nvme_security_send_args *args);
3097
3098 /**
3099 * nvme_mi_admin_security_recv() - Perform a Security Receive command on a
3100 * controller.
3101 * @ctrl: Controller to send command to
3102 * @args: Security Receive command arguments
3103 *
3104 * Performs a Security Receive Admin command as specified by @args. Response
3105 * data is stored in @args->data, which should be a buffer of @args->data_len
3106 * bytes. Resulting data length is stored in @args->data_len on successful
3107 * command completion.
3108 *
3109 * Security Receive data length should not be greater than 4096 bytes to
3110 * comply with specification limits.
3111 *
3112 * Return: The nvme command status if a response was received (see
3113 * &enum nvme_status_field) or -1 with errno set otherwise.
3114 *
3115 * See: &struct nvme_get_log_args
3116 */
3117 int nvme_mi_admin_security_recv(nvme_mi_ctrl_t ctrl,
3118 struct nvme_security_receive_args *args);
3119
3120 /**
3121 * nvme_mi_admin_get_features - Perform a Get Feature command on a controller
3122 * @ctrl: Controller to send command to
3123 * @args: Get Features command arguments
3124 *
3125 * Performs a Get Features Admin command as specified by @args. Returned
3126 * feature data will be stored in @args->result and @args->data, depending
3127 * on the specification of the feature itself; most features do not return
3128 * additional data. See section 5.27.1 of the NVMe spec (v2.0b) for
3129 * feature-specific information.
3130 *
3131 * On success, @args->data_len will be updated with the actual data length
3132 * received.
3133 *
3134 * Return: The nvme command status if a response was received (see
3135 * &enum nvme_status_field) or -1 with errno set otherwise.
3136 */
3137 int nvme_mi_admin_get_features(nvme_mi_ctrl_t ctrl,
3138 struct nvme_get_features_args *args);
3139
3140 /**
3141 * nvme_mi_admin_get_features_arbitration() - Get arbitration feature
3142 * @ctrl: Controller to send command to
3143 * @sel: Select which type of attribute to return, see &enum nvme_get_features_sel
3144 * @result: The feature data is returned in this argument
3145 *
3146 * Return: The nvme command status if a response was received (see
3147 * &enum nvme_status_field) or -1 with errno set otherwise.
3148 */
3149 int nvme_mi_admin_get_features_arbitration(nvme_mi_ctrl_t ctrl, enum nvme_get_features_sel sel,
3150 __u32 *result);
3151
3152 /**
3153 * nvme_mi_admin_get_features_power_mgmt() - Get power management feature
3154 * @ctrl: Controller to send command to
3155 * @sel: Select which type of attribute to return, see &enum nvme_get_features_sel
3156 * @result: The feature data is returned in this argument
3157 *
3158 * Return: The nvme command status if a response was received (see
3159 * &enum nvme_status_field) or -1 with errno set otherwise.
3160 */
3161 int nvme_mi_admin_get_features_power_mgmt(nvme_mi_ctrl_t ctrl, enum nvme_get_features_sel sel,
3162 __u32 *result);
3163
3164 /**
3165 * nvme_mi_admin_get_features_data() - Helper function for &nvme_mi_admin_get_features()
3166 * @ctrl: Controller to send command to
3167 * @fid: Feature identifier
3168 * @nsid: Namespace ID, if applicable for @fid
3169 * @data_len: Length of feature data, if applicable for @fid, in bytes
3170 * @data: User address of feature data, if applicable
3171 * @result: The command completion result from CQE dword0
3172 *
3173 * Helper for optionally features that optionally return data, using the
3174 * SEL_CURRENT selector value.
3175 *
3176 * Return: The nvme command status if a response was received (see
3177 * &enum nvme_status_field) or -1 with errno set otherwise.
3178 */
3179 static inline int nvme_mi_admin_get_features_data(nvme_mi_ctrl_t ctrl,
3180 enum nvme_features_id fid,
3181 __u32 nsid, __u32 data_len,
3182 void *data, __u32 *result)
3183 {
3184 struct nvme_get_features_args args = {
3185 .result = result,
3186 .data = data,
3187 .args_size = sizeof(args),
3188 .nsid = nsid,
3189 .sel = NVME_GET_FEATURES_SEL_CURRENT,
3190 .cdw11 = 0,
3191 .data_len = data_len,
3192 .fid = (__u8)fid,
3193 .uuidx = NVME_UUID_NONE,
3194 };
3195
3196 return nvme_mi_admin_get_features(ctrl, &args);
3197 }
3198
3199 /**
3200 * nvme_mi_admin_get_features_simple - Get a simple feature value with no data
3201 * @ctrl: Controller to send command to
3202 * @fid: Feature identifier
3203 * @nsid: Namespace id, if required by @fid
3204 * @result: output feature data
3205 */
3206 static inline int nvme_mi_admin_get_features_simple(nvme_mi_ctrl_t ctrl,
3207 enum nvme_features_id fid,
3208 __u32 nsid,
3209 __u32 *result)
3210 {
3211 return nvme_mi_admin_get_features_data(ctrl, fid, nsid,
3212 0, NULL, result);
3213 }
3214
3215 /**
3216 * nvme_mi_admin_set_features - Perform a Set Features command on a controller
3217 * @ctrl: Controller to send command to
3218 * @args: Set Features command arguments
3219 *
3220 * Performs a Set Features Admin command as specified by @args. Result
3221 * data will be stored in @args->result.
3222 * on the specification of the feature itself; most features do not return
3223 * additional data. See section 5.27.1 of the NVMe spec (v2.0b) for
3224 * feature-specific information.
3225 *
3226 * On success, @args->data_len will be updated with the actual data length
3227 * received.
3228 *
3229 * Return: The nvme command status if a response was received (see
3230 * &enum nvme_status_field) or -1 with errno set otherwise.
3231 */
3232 int nvme_mi_admin_set_features(nvme_mi_ctrl_t ctrl,
3233 struct nvme_set_features_args *args);
3234
3235 /**
3236 * nvme_mi_admin_set_features_power_mgmt() - Set power management feature
3237 * @ctrl: Controller to send command to
3238 * @ps: Power State
3239 * @wh: Workload Hint
3240 * @save: Save value across power states
3241 * @result: The feature data is returned in this argument
3242 *
3243 * Return: The nvme command status if a response was received (see
3244 * &enum nvme_status_field) or -1 with errno set otherwise.
3245 */
3246 int nvme_mi_admin_set_features_power_mgmt(nvme_mi_ctrl_t ctrl, __u8 ps, __u8 wh, bool save,
3247 __u32 *result);
3248
3249 /**
3250 * nvme_mi_admin_ns_mgmt - Issue a Namespace Management command
3251 * @ctrl: Controller to send command to
3252 * @args: Namespace management command arguments
3253 *
3254 * Issues a Namespace Management command to @ctrl, with arguments specified
3255 * from @args.
3256 *
3257 * Return: The nvme command status if a response was received (see
3258 * &enum nvme_status_field) or -1 with errno set otherwise.
3259 */
3260 int nvme_mi_admin_ns_mgmt(nvme_mi_ctrl_t ctrl,
3261 struct nvme_ns_mgmt_args *args);
3262
3263 /**
3264 * nvme_mi_admin_ns_mgmt_create - Helper for Namespace Management Create command
3265 * @ctrl: Controller to send command to
3266 * @ns: New namespace parameters
3267 * @csi: Command Set Identifier for new NS
3268 * @nsid: Set to new namespace ID on create
3269 * @data: Host Software Specified Fields that defines ns creation parameters
3270 *
3271 * Issues a Namespace Management (Create) command to @ctrl, to create a
3272 * new namespace specified by @ns, using command set @csi. On success,
3273 * the new namespace ID will be written to @nsid.
3274 *
3275 * Return: The nvme command status if a response was received (see
3276 * &enum nvme_status_field) or -1 with errno set otherwise.
3277 */
3278 static inline int nvme_mi_admin_ns_mgmt_create(nvme_mi_ctrl_t ctrl,
3279 struct nvme_id_ns *ns, __u8 csi, __u32 *nsid,
3280 struct nvme_ns_mgmt_host_sw_specified *data)
3281 {
3282 struct nvme_ns_mgmt_args args = {
3283 .result = nsid,
3284 .ns = ns,
3285 .args_size = sizeof(args),
3286 .nsid = NVME_NSID_NONE,
3287 .sel = NVME_NS_MGMT_SEL_CREATE,
3288 .csi = csi,
3289 .data = data,
3290 };
3291
3292 return nvme_mi_admin_ns_mgmt(ctrl, &args);
3293 }
3294
3295 /**
3296 * nvme_mi_admin_ns_mgmt_delete - Helper for Namespace Management Delete command
3297 * @ctrl: Controller to send command to
3298 * @nsid: Namespace ID to delete
3299 *
3300 * Issues a Namespace Management (Delete) command to @ctrl, to delete the
3301 * namespace with id @nsid.
3302 *
3303 * Return: The nvme command status if a response was received (see
3304 * &enum nvme_status_field) or -1 with errno set otherwise.
3305 */
3306 static inline int nvme_mi_admin_ns_mgmt_delete(nvme_mi_ctrl_t ctrl, __u32 nsid)
3307 {
3308 struct nvme_ns_mgmt_args args = {
3309 .args_size = sizeof(args),
3310 .nsid = nsid,
3311 .sel = NVME_NS_MGMT_SEL_DELETE,
3312 };
3313
3314 return nvme_mi_admin_ns_mgmt(ctrl, &args);
3315 }
3316
3317 /**
3318 * nvme_mi_admin_ns_attach() - Attach or detach namespace to controller(s)
3319 * @ctrl: Controller to send command to
3320 * @args: Namespace Attach command arguments
3321 *
3322 * Return: The nvme command status if a response was received (see
3323 * &enum nvme_status_field) or -1 with errno set otherwise.
3324 */
3325 int nvme_mi_admin_ns_attach(nvme_mi_ctrl_t ctrl,
3326 struct nvme_ns_attach_args *args);
3327
3328 /**
3329 * nvme_mi_admin_ns_attach_ctrls() - Attach namespace to controllers
3330 * @ctrl: Controller to send command to
3331 * @nsid: Namespace ID to attach
3332 * @ctrlist: Controller list to modify attachment state of nsid
3333 *
3334 * Return: The nvme command status if a response was received (see
3335 * &enum nvme_status_field) or -1 with errno set otherwise.
3336 */
3337 static inline int nvme_mi_admin_ns_attach_ctrls(nvme_mi_ctrl_t ctrl, __u32 nsid,
3338 struct nvme_ctrl_list *ctrlist)
3339 {
3340 struct nvme_ns_attach_args args = {
3341 .result = NULL,
3342 .ctrlist = ctrlist,
3343 .args_size = sizeof(args),
3344 .nsid = nsid,
3345 .sel = NVME_NS_ATTACH_SEL_CTRL_ATTACH,
3346 };
3347
3348 return nvme_mi_admin_ns_attach(ctrl, &args);
3349 }
3350
3351 /**
3352 * nvme_mi_admin_ns_detach_ctrls() - Detach namespace from controllers
3353 * @ctrl: Controller to send command to
3354 * @nsid: Namespace ID to detach
3355 * @ctrlist: Controller list to modify attachment state of nsid
3356 *
3357 * Return: The nvme command status if a response was received (see
3358 * &enum nvme_status_field) or -1 with errno set otherwise.
3359 */
3360 static inline int nvme_mi_admin_ns_detach_ctrls(nvme_mi_ctrl_t ctrl, __u32 nsid,
3361 struct nvme_ctrl_list *ctrlist)
3362 {
3363 struct nvme_ns_attach_args args = {
3364 .result = NULL,
3365 .ctrlist = ctrlist,
3366 .args_size = sizeof(args),
3367 .nsid = nsid,
3368 .sel = NVME_NS_ATTACH_SEL_CTRL_DEATTACH,
3369 };
3370
3371 return nvme_mi_admin_ns_attach(ctrl, &args);
3372 }
3373
3374 /**
3375 * nvme_mi_admin_fw_download() - Download part or all of a firmware image to
3376 * the controller
3377 * @ctrl: Controller to send firmware data to
3378 * @args: &struct nvme_fw_download_args argument structure
3379 *
3380 * The Firmware Image Download command downloads all or a portion of an image
3381 * for a future update to the controller. The Firmware Image Download command
3382 * downloads a new image (in whole or in part) to the controller.
3383 *
3384 * The image may be constructed of multiple pieces that are individually
3385 * downloaded with separate Firmware Image Download commands. Each Firmware
3386 * Image Download command includes a Dword Offset and Number of Dwords that
3387 * specify a dword range.
3388 *
3389 * The new firmware image is not activated as part of the Firmware Image
3390 * Download command. Use the nvme_mi_admin_fw_commit() to activate a newly
3391 * downloaded image.
3392 *
3393 * Return: 0 on success, non-zero on failure
3394 */
3395 int nvme_mi_admin_fw_download(nvme_mi_ctrl_t ctrl,
3396 struct nvme_fw_download_args *args);
3397
3398 /**
3399 * nvme_mi_admin_fw_commit() - Commit firmware using the specified action
3400 * @ctrl: Controller to send firmware data to
3401 * @args: &struct nvme_fw_download_args argument structure
3402 *
3403 * The Firmware Commit command modifies the firmware image or Boot Partitions.
3404 *
3405 * Return: 0 on success, non-zero on failure
3406 */
3407 int nvme_mi_admin_fw_commit(nvme_mi_ctrl_t ctrl,
3408 struct nvme_fw_commit_args *args);
3409
3410 /**
3411 * nvme_mi_admin_format_nvm() - Format NVMe namespace
3412 * @ctrl: Controller to send command to
3413 * @args: Format NVM command arguments
3414 *
3415 * Perform a low-level format to set the LBA data & metadata size. May destroy
3416 * data & metadata on the specified namespaces
3417 *
3418 * Return: The nvme command status if a response was received (see
3419 * &enum nvme_status_field) or -1 with errno set otherwise.
3420 */
3421 int nvme_mi_admin_format_nvm(nvme_mi_ctrl_t ctrl,
3422 struct nvme_format_nvm_args *args);
3423
3424 /**
3425 * nvme_mi_admin_sanitize_nvm() - Start a subsystem Sanitize operation
3426 * @ctrl: Controller to send command to
3427 * @args: Sanitize command arguments
3428 *
3429 * A sanitize operation alters all user data in the NVM subsystem such that
3430 * recovery of any previous user data from any cache, the non-volatile media,
3431 * or any Controller Memory Buffer is not possible.
3432 *
3433 * The Sanitize command starts a sanitize operation or to recover from a
3434 * previously failed sanitize operation. The sanitize operation types that may
3435 * be supported are Block Erase, Crypto Erase, and Overwrite. All sanitize
3436 * operations are processed in the background, i.e., completion of the sanitize
3437 * command does not indicate completion of the sanitize operation.
3438 *
3439 * Return: The nvme command status if a response was received (see
3440 * &enum nvme_status_field) or -1 with errno set otherwise.
3441 */
3442 int nvme_mi_admin_sanitize_nvm(nvme_mi_ctrl_t ctrl,
3443 struct nvme_sanitize_nvm_args *args);
3444
3445 /**
3446 * enum nvme_mi_aem_handler_next_action - Next action for the AEM state machine handler
3447 * @NVME_MI_AEM_HNA_ACK: Send an ack for the AEM
3448 * @NVME_MI_AEM_HNA_NONE: No further action
3449 *
3450 * Used as return value for the AE callback generated when calling nvme_mi_aem_process
3451 */
3452 enum nvme_mi_aem_handler_next_action {
3453 NVME_MI_AEM_HNA_ACK,
3454 NVME_MI_AEM_HNA_NONE,
3455 };
3456
3457 /**
3458 * struct nvme_mi_event - AE event information structure
3459 * @aeoi: Event identifier
3460 * @aessi: Event occurrence scope info
3461 * @aeocidi: Event occurrence scope ID info
3462 * @spec_info: Specific info buffer
3463 * @spec_info_len: Length of specific info buffer
3464 * @vend_spec_info: Vendor specific info buffer
3465 * @vend_spec_info_len: Length of vendor specific info buffer
3466 *
3467 * Application callbacks for nvme_mi_aem_process will be able to call
3468 * nvme_mi_aem_get_next_event which will return a pointer to such an identifier
3469 * for the next event the application should parse
3470 */
3471 struct nvme_mi_event {
3472 uint8_t aeoi;
3473 uint8_t aessi;
3474 uint32_t aeocidi;
3475 void *spec_info;
3476 size_t spec_info_len;
3477 void *vend_spec_info;
3478 size_t vend_spec_info_len;
3479 };
3480
3481 /**
3482 * nvme_mi_aem_get_next_event() - Get details for the next event to parse
3483 * @ep: The endpoint with the event
3484 *
3485 * When inside a aem_handler, call this and a returned struct pointer
3486 * will provide details of event information. Will return NULL when end of parsing is occurred.
3487 * spec_info and vend_spec_info must be copied to persist as they will not be valid
3488 * after the handler_next_action has returned.
3489 *
3490 * Return: Pointer no next nvme_mi_event or NULL if this is the last one
3491 */
3492 struct nvme_mi_event *nvme_mi_aem_get_next_event(nvme_mi_ep_t ep);
3493
3494 struct nvme_mi_aem_enabled_map {
3495 bool enabled[256];
3496 };
3497
3498 /**
3499 * struct nvme_mi_aem_config - Provided for nvme_mi_aem_enable
3500 * @aem_handler: Callback function for application processing of events
3501 * @enabled_map: Map indicating which AE should be enabled on the endpoint
3502 * @envfa: Enable SR-IOV virtual functions AE
3503 * @empfa: Enable SR-IOV physical functions AE
3504 * @encfa: Enable PCIe functions AE
3505 * @aemd: AEM Delay (time in seconds from when event happens to AEM being batched and sent)
3506 * @aerd: AEM Retry Delay (time in 100s of ms between AEM retries from the endpoint)
3507 *
3508 * Application callbacks for nvme_mi_aem_process will be able to call
3509 * nvme_mi_aem_get_next_event which will return a pointer to such an identifier
3510 * for the next event the application should parse
3511 */
3512 struct nvme_mi_aem_config {
3513 /*
3514 * This is called from inside nvme_mi_process when a payload has been validated and
3515 * can be parsed. The application may call nvme_mi_aem_get_next_event from inside
3516 * the callback to parse event data.
3517 */
3518 enum nvme_mi_aem_handler_next_action (*aem_handler)(
3519 nvme_mi_ep_t ep,
3520 size_t num_events,
3521 void *userdata);
3522
3523 struct nvme_mi_aem_enabled_map enabled_map;
3524
3525 bool envfa;
3526 bool empfa;
3527 bool encfa;
3528 __u8 aemd;
3529 __u8 aerd;
3530 };
3531
3532 /**
3533 * nvme_mi_aem_get_fd() - Returns the pollable fd for AEM data available
3534 * @ep: The endpoint being monitored for asynchronous data
3535 *
3536 * This populated structure can be polled from the application to understand if
3537 * a call to nvme_mi_aem_process() is required (when a poll returns > 0).
3538 *
3539 * Return: The fd value or -1 if error
3540 */
3541 int nvme_mi_aem_get_fd(nvme_mi_ep_t ep);
3542
3543 /**
3544 * nvme_mi_aem_enable() - Enable AE on the provided endpoint
3545 * @ep: Endpoint to enable AEs
3546 * @config: AE configuraiton including which events are enabled and the callback function
3547 * @userdata: Application provided context pointer for callback function
3548 *
3549 * This function is called to enable AE on the endpoint. Endpoint will provide initial state
3550 * (if any) of enabled AEs and application can parse those via the aem_handler fn pointer in
3551 * callbacks. Thes can be obtained in the callback by calling nvme_mi_aem_get_next_event().
3552 *
3553 * Application should poll the fd that can be obtained from nvme_mi_aem_get_fd and then call
3554 * nvme_mi_aem_process() when poll() indicates data available.
3555 *
3556 * A call to nvme_mi_aem_process() will grab AEM data and call the aem_handler fn pointer.
3557 * At this point the application can call nvme_mi_aem_get_next_event() to get information for
3558 * each triggered event.
3559 *
3560 * Return: 0 is a success, nonzero is an error and errno may be read for further details
3561 */
3562 int nvme_mi_aem_enable(nvme_mi_ep_t ep,
3563 struct nvme_mi_aem_config *config,
3564 void *userdata);
3565
3566
3567 /**
3568 * nvme_mi_aem_get_enabled() - Return information on which AEs are enabled
3569 * @ep: Endpoint to check enabled status
3570 * @enabled: nvme_mi_aem_enabled_map indexed by AE event ID of enabled state
3571 *
3572 * Return: 0 is a success, nonzero is an error and errno may be read for further details
3573 */
3574 int nvme_mi_aem_get_enabled(nvme_mi_ep_t ep,
3575 struct nvme_mi_aem_enabled_map *enabled);
3576
3577 /**
3578 * nvme_mi_aem_disable() - Disable AE on the provided endpoint
3579 * @ep: Endpoint to disable AEs
3580 *
3581 * Return: 0 is a success, nonzero is an error and errno may be read for further details
3582 */
3583 int nvme_mi_aem_disable(nvme_mi_ep_t ep);
3584
3585 /**
3586 * nvme_mi_aem_process() - Process AEM on the provided endpoint
3587 * @ep: Endpoint to process
3588 * @userdata: Application provided context pointer for callback function
3589 *
3590 * Call this if poll() indicates data is available on the fd provided by nvme_mi_aem_get_fd()
3591 *
3592 * This will call the fn pointer, aem_handler, provided with nvme_mi_aem_config and the
3593 * application can call nvme_mi_aem_get_next_event() from within this callback to get
3594 * aem event data. The callback function should return NVME_MI_AEM_HNA_ACK for normal operation.
3595 *
3596 * Return: 0 is a success, nonzero is an error and errno may be read for further details
3597 */
3598 int nvme_mi_aem_process(nvme_mi_ep_t ep, void *userdata);
3599
3600 #endif /* _LIBNVME_MI_MI_H */