Debian Codegraph @

doc/rst/mi.rst

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