xref: /illumos-gate/usr/src/lib/libnvme/common/libnvme.h (revision 1c02c6c85edfeb48df1fe18511a8779bf9d6c6ed)
1 /*
2  * This file and its contents are supplied under the terms of the
3  * Common Development and Distribution License ("CDDL"), version 1.0.
4  * You may only use this file in accordance with the terms of version
5  * 1.0 of the CDDL.
6  *
7  * A full copy of the text of the CDDL should have accompanied this
8  * source.  A copy of the CDDL is also available via the Internet at
9  * http://www.illumos.org/license/CDDL.
10  */
11 
12 /*
13  * Copyright 2024 Oxide Computer Company
14  */
15 
16 #ifndef _LIBNVME_H
17 #define	_LIBNVME_H
18 
19 /*
20  * This contains an evolving set of interfaces for more programmatically
21  * interfacing with NVMe devices. For more information on why the library looks
22  * this way, please see lib/libnvme/common/libnvme.c.
23  */
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 #include <stdint.h>
30 #include <stdbool.h>
31 #include <libdevinfo.h>
32 #include <sys/nvme/discovery.h>
33 
34 /*
35  * Right now everything relies on seeing various pieces that are in sys/nvme.h,
36  * unfortunately. This includes things like the identify, log page, and
37  * structure data structures, various constants, and other things that have
38  * accumulated. This must all be rejiggered prior to making this a committed
39  * interface as we're leaking through many things that software needs.
40  * Directionally splitting this out into headers that relate to the spec as
41  * <sys/nvme/identify.h>, etc. would be useful and would address several of the
42  * places that we're passing in raw uint32_t's for items that come from the spec
43  * and could be a little more specific to help out consumers.
44  */
45 #include <sys/nvme.h>
46 
47 /*
48  * General error classes that may be returned when operating on non-information
49  * snapshots.
50  */
51 typedef enum {
52 	NVME_ERR_OK	 = 0,
53 	/*
54 	 * Indicates that a command failed due to a controller-specific error.
55 	 * The controller's SCT/SC are valid in the corresponding objects error
56 	 * data.
57 	 */
58 	NVME_ERR_CONTROLLER,
59 	/*
60 	 * Indicates that there was a memory allocation error. The system error
61 	 * contains the specific errno.
62 	 */
63 	NVME_ERR_NO_MEM,
64 	/*
65 	 * Indicates that an operation could not complete because the kernel did
66 	 * not have DMA resources available for us.
67 	 */
68 	NVME_ERR_NO_DMA_MEM,
69 	/*
70 	 * Indicates that an error occurred while trying to use the devinfo
71 	 * library.
72 	 */
73 	NVME_ERR_LIBDEVINFO,
74 	/*
75 	 * Indicates that an internal error condition occurred.
76 	 */
77 	NVME_ERR_INTERNAL,
78 	/*
79 	 * Indicates that the function was given an invalid pointer argument.
80 	 */
81 	NVME_ERR_BAD_PTR,
82 	/*
83 	 * Indicates that an unknown flag argument was given to us.
84 	 */
85 	NVME_ERR_BAD_FLAG,
86 	/*
87 	 * Indicates that the devinfo node we were given doesn't correspond to
88 	 * an NVMe controller.
89 	 */
90 	NVME_ERR_BAD_DEVI,
91 	/*
92 	 * Indicates that while we found a devinfo property successfully,
93 	 * something about it does not match our expectations. This could be the
94 	 * type, number of values, range, etc.
95 	 */
96 	NVME_ERR_BAD_DEVI_PROP,
97 	/*
98 	 * Indicates that we were given an illegal instance (i.e. a negative
99 	 * instance).
100 	 */
101 	NVME_ERR_ILLEGAL_INSTANCE,
102 	/*
103 	 * Indicates that a means of identifying a controller (name, instance,
104 	 * etc.) does not match any known NVMe device.
105 	 */
106 	NVME_ERR_BAD_CONTROLLER,
107 	/*
108 	 * Indicates that a request could not proceed due to missing privileges.
109 	 */
110 	NVME_ERR_PRIVS,
111 	/*
112 	 * Indicates a failure to open a device file.
113 	 */
114 	NVME_ERR_OPEN_DEV,
115 	/*
116 	 * Indicates that the given restore data is not valid.
117 	 */
118 	NVME_ERR_BAD_RESTORE,
119 	/*
120 	 * Indicates that a namespace (name, ID, etc.) passed in is not valid on
121 	 * the controller. This may be because it's outside the valid range or
122 	 * there was an attempt to use the broadcast namespace when it's not
123 	 * supported.
124 	 */
125 	NVME_ERR_NS_RANGE,
126 	/*
127 	 * Indicates that a namespace ID is not usable in this context. For
128 	 * example, attempting to specify a namespace to an identify or log page
129 	 * that does not support them.
130 	 */
131 	NVME_ERR_NS_UNUSE,
132 	/*
133 	 * Indicates that the value for a get log page field is invalid. This
134 	 * may happened due to alignment, just being too large, or something
135 	 * else.
136 	 */
137 	NVME_ERR_LOG_CSI_RANGE,
138 	NVME_ERR_LOG_LID_RANGE,
139 	NVME_ERR_LOG_LSP_RANGE,
140 	NVME_ERR_LOG_LSI_RANGE,
141 	NVME_ERR_LOG_RAE_RANGE,
142 	NVME_ERR_LOG_SIZE_RANGE,
143 	NVME_ERR_LOG_OFFSET_RANGE,
144 	/*
145 	 * Indicates that the log field value given is not supported because the
146 	 * controller is not of a sufficient version or does not indicate that
147 	 * it is supported in the LPA field.
148 	 */
149 	NVME_ERR_LOG_CSI_UNSUP,
150 	NVME_ERR_LOG_LSP_UNSUP,
151 	NVME_ERR_LOG_LSI_UNSUP,
152 	NVME_ERR_LOG_RAE_UNSUP,
153 	NVME_ERR_LOG_OFFSET_UNSUP,
154 	/*
155 	 * Indicates that the log field value is unusable. The specifics of our
156 	 * request indicate that this cannot be set.
157 	 */
158 	NVME_ERR_LOG_LSP_UNUSE,
159 	NVME_ERR_LOG_LSI_UNUSE,
160 	NVME_ERR_LOG_RAE_UNUSE,
161 	/*
162 	 * Indicates that the log page's scope requires operating on something
163 	 * that isn't what was requested. This would happen if manually
164 	 * constructing a log page that operates on the controller, but passed a
165 	 * namespace (e.g. the firmware log page).
166 	 */
167 	NVME_ERR_LOG_SCOPE_MISMATCH,
168 	/*
169 	 * Indicates that a log request can't be executed because required
170 	 * fields have not been set.
171 	 */
172 	NVME_ERR_LOG_REQ_MISSING_FIELDS,
173 	/*
174 	 * Indicates that the named log is unknown to the library.
175 	 */
176 	NVME_ERR_LOG_NAME_UNKNOWN,
177 	/*
178 	 * Indicates that the named log is not supported by the device.
179 	 */
180 	NVME_ERR_LOG_UNSUP_BY_DEV,
181 	/*
182 	 * Indicates that the IDENTIFY command requested is unknown.
183 	 */
184 	NVME_ERR_IDENTIFY_UNKNOWN,
185 	/*
186 	 * Indicates that the requested identify command is not supported by the
187 	 * device.
188 	 */
189 	NVME_ERR_IDENTIFY_UNSUP_BY_DEV,
190 	/*
191 	 * Indicates that the identify command parameter is outside of the valid
192 	 * range for the field.
193 	 */
194 	NVME_ERR_IDENTIFY_CTRLID_RANGE,
195 	NVME_ERR_IDENTIFY_OUTPUT_RANGE,
196 	/*
197 	 * Indicates that the parameter given is not supported because the
198 	 * controller is not of a sufficient version or does not indicate that
199 	 * it is supported.
200 	 */
201 	NVME_ERR_IDENTIFY_CTRLID_UNSUP,
202 	/*
203 	 * Indicates that the parameter given is not supported in the context of
204 	 * a given identify command. Namespaces are handled with the
205 	 * cross-command error code.
206 	 */
207 	NVME_ERR_IDENTIFY_CTRLID_UNUSE,
208 	/*
209 	 * Indicates that an identify request can't be executed because required
210 	 * fields have not been set.
211 	 */
212 	NVME_ERR_IDENTIFY_REQ_MISSING_FIELDS,
213 	/*
214 	 * Indicates that the controller doesn't support the NVMe standard
215 	 * vendor unique command.
216 	 */
217 	NVME_ERR_VUC_UNSUP_BY_DEV,
218 	/*
219 	 * Indicates that the vendor unique command parameter is outside of the
220 	 * valid range for the field.
221 	 */
222 	NVME_ERR_VUC_TIMEOUT_RANGE,
223 	NVME_ERR_VUC_OPCODE_RANGE,
224 	NVME_ERR_VUC_IMPACT_RANGE,
225 	NVME_ERR_VUC_NDT_RANGE,
226 	/*
227 	 * Indicates that a vendor unique command already has an input or output
228 	 * buffer set and is being asked to set a separate one.
229 	 */
230 	NVME_ERR_VUC_CANNOT_RW,
231 	/*
232 	 * Indicates that the vendor unique request does not have valid
233 	 * execution context. This may be because the command was never executed
234 	 * or the exec failed in a way such that the controller never exercised
235 	 * the command.
236 	 */
237 	NVME_ERR_VUC_NO_RESULTS,
238 	/*
239 	 * Indicates that the named vendor unique command is not known to the
240 	 * library.
241 	 */
242 	NVME_ERR_VUC_UNKNOWN,
243 	/*
244 	 * Indicates that a vendor unique command can't be executed because
245 	 * required fields have not been set.
246 	 */
247 	NVME_ERR_VUC_REQ_MISSING_FIELDS,
248 	/*
249 	 * Indicates that the vendor-specific library operation could not
250 	 * proceed because it is not supported by the given device.
251 	 */
252 	NVME_ERR_VU_FUNC_UNSUP_BY_DEV,
253 	/*
254 	 * WDC e6 dump specific invalid values
255 	 */
256 	NVME_ERR_WDC_E6_OFFSET_RANGE,
257 	/*
258 	 * Indicates that the controller does not support firmware related
259 	 * operations.
260 	 */
261 	NVME_ERR_FW_UNSUP_BY_DEV,
262 	/*
263 	 * Indicates that the constraints of the device and what the kernel can
264 	 * do make the firmware upgrade non-tenable.
265 	 */
266 	NVME_ERR_KERN_FW_IMPOS,
267 	/*
268 	 * Indicates that a firmware download parameter is invalid.
269 	 */
270 	NVME_ERR_FW_LOAD_LEN_RANGE,
271 	NVME_ERR_FW_LOAD_OFFSET_RANGE,
272 	/*
273 	 * Indicates that the firmware commit command parameter is outside of
274 	 * the valid range for the field.
275 	 */
276 	NVME_ERR_FW_COMMIT_SLOT_RANGE,
277 	NVME_ERR_FW_COMMIT_ACTION_RANGE,
278 	/*
279 	 * Indicates that a firmware commit command can't be executed because
280 	 * required fields have not been set.
281 	 */
282 	NVME_ERR_FW_COMMIT_REQ_MISSING_FIELDS,
283 	/*
284 	 * Indicates that the firmware commit could not occur because the
285 	 * requested slot is read-only.
286 	 */
287 	NVME_ERR_FW_SLOT_RO,
288 	/*
289 	 * Indicates that the controller does not support NVM format operations.
290 	 */
291 	NVME_ERR_FORMAT_UNSUP_BY_DEV,
292 	/*
293 	 * Indicates that the controller does not support cryptographic secure
294 	 * erase.
295 	 */
296 	NVME_ERR_CRYPTO_SE_UNSUP_BY_DEV,
297 	/*
298 	 * Indicates that the NVM format command cannot be executed because it
299 	 * would target a specific namespace; however, the device does not allow
300 	 * a secure erase or a format to target an individual namespace.
301 	 */
302 	NVME_ERR_NS_FORMAT_UNSUP_BY_DEV,
303 	/*
304 	 * Indicates that the kernel does not support formatting with the
305 	 * specified LBA format, generally due to something like the use of
306 	 * metadata in the namespace.
307 	 */
308 	NVME_ERR_KERN_FORMAT_UNSUP,
309 	/*
310 	 * Indicates that the NVM format command parameter is outside of
311 	 * the valid range for the field.
312 	 */
313 	NVME_ERR_FORMAT_LBAF_RANGE,
314 	NVME_ERR_FORMAT_SES_RANGE,
315 	/*
316 	 * Indicates that the parameter and/or its value is not supported for a
317 	 * NVM format command.
318 	 */
319 	NVME_ERR_FORMAT_PARAM_UNSUP,
320 	/*
321 	 * Indicates that a NVM format command can't be executed because
322 	 * required fields have not been set.
323 	 */
324 	NVME_ERR_FORMAT_REQ_MISSING_FIELDS,
325 	/*
326 	 * Indicates that the WDC e6 log dump request could not be executed due
327 	 * to fields not being set.
328 	 */
329 	NVME_ERR_WDC_E6_REQ_MISSING_FIELDS,
330 	/*
331 	 * Indicates that the named feature is unknown to the library.
332 	 */
333 	NVME_ERR_FEAT_NAME_UNKNOWN,
334 	/*
335 	 * Indicates that the named feature is not supported by the device.
336 	 */
337 	NVME_ERR_FEAT_UNSUP_BY_DEV,
338 	/*
339 	 * Indicates that the feature parameter is outside of the valid range
340 	 * for the field.
341 	 */
342 	NVME_ERR_FEAT_FID_RANGE,
343 	NVME_ERR_FEAT_SEL_RANGE,
344 	NVME_ERR_FEAT_CDW11_RANGE,
345 	NVME_ERR_FEAT_DATA_RANGE,
346 	/*
347 	 * Indicates that the feature parameter given is not supported because
348 	 * the controller is not of a sufficient version.
349 	 */
350 	NVME_ERR_FEAT_SEL_UNSUP,
351 	/*
352 	 * Indicates that the get feature parameter given is not supported for
353 	 * the given feature. For example, passing in a cdw11 argument that is
354 	 * not needed.
355 	 */
356 	NVME_ERR_FEAT_CDW11_UNUSE,
357 	NVME_ERR_FEAT_DATA_UNUSE,
358 	/*
359 	 * Indicates that a feature request does not have valid output data.
360 	 * This may be because the command was never executed or it did not
361 	 * execute successfully.
362 	 */
363 	NVME_ERR_FEAT_NO_RESULTS,
364 	/*
365 	 * Indicates that a get features request can't be executed because
366 	 * required fields have not been set.
367 	 */
368 	NVME_ERR_GET_FEAT_REQ_MISSING_FIELDS,
369 	/*
370 	 * These indicate that the operation could not be executed because they
371 	 * require holding either a controller or namespace write lock and one
372 	 * is not held by the corresponding controller handle.
373 	 */
374 	NVME_ERR_NEED_CTRL_WRLOCK,
375 	NVME_ERR_NEED_NS_WRLOCK,
376 	/*
377 	 * These indicate that the operation could not be executed because the
378 	 * controller or namespace respectively currently have an exclusive
379 	 * write lock (or an equivalent future form) that blocks execution from
380 	 * others.
381 	 */
382 	NVME_ERR_CTRL_LOCKED,
383 	NVME_ERR_NS_LOCKED,
384 	/*
385 	 * Indicates that a fatal locking operation occurred that will terminate
386 	 * the process. This includes cases such as recursive enters on the same
387 	 * lock, attempting to unlock a lock that isn't owned, etc.
388 	 */
389 	NVME_ERR_LOCK_PROG,
390 	/*
391 	 * Indicates that a lock order violation was attempted. This includes
392 	 * things like taking the controller lock while holding the namespace
393 	 * lock, attempting to take a second namespace lock, holding a
394 	 * controller write lock and trying to get a namespace lock, etc.
395 	 */
396 	NVME_ERR_LOCK_ORDER,
397 	/*
398 	 * Indicates that a signal was encountered while attempting to take a
399 	 * lock.
400 	 */
401 	NVME_ERR_LOCK_WAIT_INTR,
402 	/*
403 	 * Indicates that attempting to take the lock failed because the thread
404 	 * would be required to block, but it asked not to.
405 	 */
406 	NVME_ERR_LOCK_WOULD_BLOCK,
407 	/*
408 	 * These indicate that the respective attach and detach operations
409 	 * failed to complete due to an error in the underlying kernel
410 	 * subsystems. For detach this might happen because of a disk being
411 	 * open, busy in a zpool, or something else. For attach, it may suggest
412 	 * and NDI or other issue.
413 	 */
414 	NVME_ERR_DETACH_KERN,
415 	NVME_ERR_ATTACH_KERN,
416 	/*
417 	 * Indicates that the kernel driver does not support some property of
418 	 * the requested namespace.
419 	 */
420 	NVME_ERR_ATTACH_UNSUP_KERN,
421 	/*
422 	 * Indicates that the operation cannot proceed because a namespace is
423 	 * attached to blkdev and it must be detached to proceed.
424 	 */
425 	NVME_ERR_NS_BLKDEV_ATTACH,
426 	/*
427 	 * Indicates that non-DMA kernel memory was not available for this
428 	 * request.
429 	 */
430 	NVME_ERR_NO_KERN_MEM,
431 	/*
432 	 * These two codes represent internal device conditions that indicate
433 	 * the device is unusable or that it was physically removed (usually due
434 	 * to hotplug).
435 	 */
436 	NVME_ERR_CTRL_DEAD,
437 	NVME_ERR_CTRL_GONE
438 } nvme_err_t;
439 
440 /*
441  * Errors used for the various information errors. This is shared between both
442  * controller and namespace information structures.
443  */
444 typedef enum {
445 	NVME_INFO_ERR_OK,
446 	/*
447 	 * Indicates that the item is not supported because this is the wrong
448 	 * controller transport. For example, asking about a PCI ID for
449 	 * something that is not PCI-based.
450 	 */
451 	NVME_INFO_ERR_TRANSPORT,
452 	/*
453 	 * Indicates that the item is not supported because the device version
454 	 * is too old to get this.
455 	 */
456 	NVME_INFO_ERR_VERSION,
457 	/*
458 	 * Indicates that we could not get certain information because the
459 	 * device does not support a given capability.
460 	 */
461 	NVME_INFO_ERR_MISSING_CAP,
462 	/*
463 	 * Indicates that the specified format value is unknown.
464 	 */
465 	NVME_INFO_ERR_BAD_LBA_FMT,
466 	/*
467 	 * These errors only occur during attempts to persist information and
468 	 * indicate challenges allocating memory or otherwise challenges with
469 	 * libnvpair.
470 	 */
471 	NVME_INFO_ERR_PERSIST_NVL,
472 	/*
473 	 * The first indicates that the index is invalid or if it is technically
474 	 * within the valid LBA format range, but there is no data size. The
475 	 * second indicates that we can't actually fully represent the data
476 	 * here. This happens because say the LBA size can't be represented by a
477 	 * uint64_t.
478 	 */
479 	NVME_INFO_ERR_BAD_FMT,
480 	NVME_INFO_ERR_BAD_FMT_DATA,
481 	/*
482 	 * Indicates that the information cannot be returned because the
483 	 * namespace's state does not allow us to answer this question. This may
484 	 * be because it's inactive as below or because blkdev is not attached.
485 	 */
486 	NVME_INFO_ERR_NS_INACTIVE,
487 	NVME_INFO_ERR_NS_NO_BLKDEV
488 } nvme_info_err_t;
489 
490 typedef struct nvme nvme_t;
491 typedef struct nvme_ctrl nvme_ctrl_t;
492 typedef struct nvme_ctrl_iter nvme_ctrl_iter_t;
493 typedef struct nvme_ctrl_disc nvme_ctrl_disc_t;
494 typedef struct nvme_ctrl_info nvme_ctrl_info_t;
495 typedef struct nvme_ns nvme_ns_t;
496 typedef struct nvme_ns_iter nvme_ns_iter_t;
497 typedef struct nvme_ns_disc nvme_ns_disc_t;
498 typedef struct nvme_ns_info nvme_ns_info_t;
499 typedef struct nvme_nvm_lba_fmt nvme_nvm_lba_fmt_t;
500 typedef struct nvme_log_iter nvme_log_iter_t;
501 typedef struct nvme_log_disc nvme_log_disc_t;
502 typedef struct nvme_log_req nvme_log_req_t;
503 typedef struct nvme_id_req nvme_id_req_t;
504 typedef struct nvme_vuc_iter nvme_vuc_iter_t;
505 typedef struct nvme_vuc_disc nvme_vuc_disc_t;
506 typedef struct nvme_vuc_req nvme_vuc_req_t;
507 typedef struct nvme_fw_commit_req nvme_fw_commit_req_t;
508 typedef struct nvme_format_req nvme_format_req_t;
509 typedef struct nvme_feat_disc nvme_feat_disc_t;
510 typedef struct nvme_feat_iter nvme_feat_iter_t;
511 typedef struct nvme_get_feat_req nvme_get_feat_req_t;
512 
513 /*
514  * Vendor-specific forwards.
515  */
516 typedef struct nvme_wdc_e6_req nvme_wdc_e6_req_t;
517 
518 extern nvme_t *nvme_init(void);
519 extern void nvme_fini(nvme_t *);
520 
521 /*
522  * Error information. Operations that take an nvme_t, always set error
523  * information on the nvme_t. Operations that operate on a controller or are
524  * related to a request object or iterator that starts from the controller
525  * set error information on the nvme_ctrl_t.
526  */
527 extern nvme_err_t nvme_err(nvme_t *);
528 extern int32_t nvme_syserr(nvme_t *);
529 extern const char *nvme_errmsg(nvme_t *);
530 extern size_t nvme_errlen(nvme_t *);
531 extern const char *nvme_errtostr(nvme_t *, nvme_err_t);
532 
533 extern nvme_err_t nvme_ctrl_err(nvme_ctrl_t *);
534 extern int32_t nvme_ctrl_syserr(nvme_ctrl_t *);
535 extern const char *nvme_ctrl_errmsg(nvme_ctrl_t *);
536 extern size_t nvme_ctrl_errlen(nvme_ctrl_t *);
537 extern void nvme_ctrl_deverr(nvme_ctrl_t *, uint32_t *, uint32_t *);
538 extern const char *nvme_ctrl_errtostr(nvme_ctrl_t *, nvme_err_t);
539 
540 /*
541  * Translations for NVMe spec error constants. These end up taking the
542  * nvme_ctrl_t so that way they can potentially translate vendor-specific errors
543  * if they are defined. A NULL controller is allowed, which will skip all such
544  * processing altogether. Both functions will always a return a string so there
545  * is no need to check for NULL (though it may just be a variant of "unknown
546  * ...").
547  *
548  * If NULL is passed for the controller in nvme_sctostr(), we will assume that
549  * the controller's type is a traditional PCI I/O controller and not a fabric
550  * based controller, which further changes the way that command-specific status
551  * codes are interpreted. Due to the lack of support in the system for
552  * different controller types, this function will always assume a PCI I/O
553  * controller currently.
554  */
555 extern const char *nvme_scttostr(nvme_ctrl_t *, uint32_t);
556 extern const char *nvme_sctostr(nvme_ctrl_t *, nvme_csi_t, uint32_t, uint32_t);
557 
558 typedef enum nvme_iter {
559 	NVME_ITER_VALID,
560 	NVME_ITER_DONE,
561 	NVME_ITER_ERROR
562 } nvme_iter_t;
563 
564 /*
565  * NVMe Controller discovery.
566  */
567 extern di_node_t nvme_ctrl_disc_devi(const nvme_ctrl_disc_t *);
568 extern di_minor_t nvme_ctrl_disc_minor(const nvme_ctrl_disc_t *);
569 
570 extern bool nvme_ctrl_discover_init(nvme_t *, nvme_ctrl_iter_t **);
571 extern nvme_iter_t nvme_ctrl_discover_step(nvme_ctrl_iter_t *,
572     const nvme_ctrl_disc_t **);
573 extern void nvme_ctrl_discover_fini(nvme_ctrl_iter_t *);
574 
575 typedef bool (*nvme_ctrl_disc_f)(nvme_t *, const nvme_ctrl_disc_t *, void *);
576 extern bool nvme_ctrl_discover(nvme_t *, nvme_ctrl_disc_f, void *);
577 
578 extern bool nvme_ctrl_init(nvme_t *, di_node_t, nvme_ctrl_t **);
579 extern bool nvme_ctrl_init_by_instance(nvme_t *, int32_t, nvme_ctrl_t **);
580 extern bool nvme_ctrl_devi(nvme_ctrl_t *, di_node_t *);
581 extern void nvme_ctrl_fini(nvme_ctrl_t *);
582 
583 /*
584  * Get information about a controller. This information about a controller is
585  * separate from the lifetime of the controller itself. This is done to
586  * facilitate the ability of saving and using this information on another
587  * system and make the management a bit easier. Errors appear on this object and
588  * not the nmve_t.
589  */
590 extern bool nvme_ctrl_info_snap(nvme_ctrl_t *, nvme_ctrl_info_t **);
591 extern bool nvme_ctrl_info_restore(nvme_t *, nvlist_t *, nvme_ctrl_info_t **);
592 extern bool nvme_ctrl_info_persist(nvme_ctrl_info_t *, nvlist_t **);
593 extern void nvme_ctrl_info_free(nvme_ctrl_info_t *);
594 
595 extern nvme_info_err_t nvme_ctrl_info_err(nvme_ctrl_info_t *);
596 extern int32_t nvme_ctrl_info_syserr(nvme_ctrl_info_t *);
597 extern const char *nvme_ctrl_info_errmsg(nvme_ctrl_info_t *);
598 extern size_t nvme_ctrl_info_errlen(nvme_ctrl_info_t *);
599 extern const char *nvme_ctrl_info_errtostr(nvme_ctrl_info_t *, nvme_info_err_t);
600 
601 /*
602  * Information about an NVMe controller. This information is a combination of
603  * the identify data structure which can be retrieved directly by folks who
604  * would prefer to use it. Common fields that are used in something like nvmeadm
605  * or other utilities who would rather not need to know about the specifics of
606  * the data structure or have to think about the version can use that instead.
607  *
608  * NVMe 2.x has kept the identify controller data structure backwards
609  * compatible. If a future version were to invalidate that, then this could
610  * possibly return NULL.
611  */
612 extern uint16_t nvme_ctrl_info_vendor(nvme_ctrl_info_t *);
613 extern const nvme_identify_ctrl_t *nvme_ctrl_info_identify(nvme_ctrl_info_t *);
614 extern const nvme_version_t *nvme_ctrl_info_version(nvme_ctrl_info_t *);
615 extern const char *nvme_ctrl_info_model(nvme_ctrl_info_t *);
616 extern const char *nvme_ctrl_info_serial(nvme_ctrl_info_t *);
617 extern uint32_t nvme_ctrl_info_fwgran(nvme_ctrl_info_t *);
618 extern const char *nvme_ctrl_info_fwrev(nvme_ctrl_info_t *);
619 extern uint32_t nvme_ctrl_info_nns(nvme_ctrl_info_t *);
620 
621 typedef enum {
622 	NVME_CTRL_TRANSPORT_PCI,
623 	NVME_CTRL_TRANSPORT_TCP,
624 	NVME_CTRL_TRANSPORT_RDMA,
625 } nvme_ctrl_transport_t;
626 
627 typedef enum {
628 	NVME_CTRL_TYPE_UNKNOWN,
629 	NVME_CTRL_TYPE_IO,
630 	NVME_CTRL_TYPE_ADMIN,
631 	NVME_CTRL_TYPE_DISCOVERY,
632 } nvme_ctrl_type_t;
633 
634 /*
635  * Controller types were explicitly added in the NVMe 1.4 specification. Prior
636  * to that all controllers were required to support issuing I/O, hence we return
637  * them as NVME_CTRL_TYPE_IO, even though this isn't quite by the spec. In 1.4
638  * this was added to the identify controller information. The 'UNKNOWN' type is
639  * for cases where we don't recognize the value based upon the standard.
640  */
641 extern nvme_ctrl_type_t nvme_ctrl_info_type(nvme_ctrl_info_t *);
642 extern nvme_ctrl_transport_t nvme_ctrl_info_transport(nvme_ctrl_info_t *);
643 
644 /*
645  * The following pieces of information are specific to PCI NVMe controllers and
646  * are not from the common identify controller data structure. As such they are
647  * fallible. The first group come from configuration space while the others are
648  * information that comes from the actual controller capability registers.
649  */
650 extern bool nvme_ctrl_info_pci_vid(nvme_ctrl_info_t *, uint16_t *);
651 extern bool nvme_ctrl_info_pci_did(nvme_ctrl_info_t *, uint16_t *);
652 extern bool nvme_ctrl_info_pci_rev(nvme_ctrl_info_t *, uint8_t *);
653 extern bool nvme_ctrl_info_pci_subvid(nvme_ctrl_info_t *, uint16_t *);
654 extern bool nvme_ctrl_info_pci_subsys(nvme_ctrl_info_t *, uint16_t *);
655 
656 extern bool nvme_ctrl_info_pci_mps_min(nvme_ctrl_info_t *, uint32_t *);
657 extern bool nvme_ctrl_info_pci_mps_max(nvme_ctrl_info_t *, uint32_t *);
658 
659 extern bool nvme_ctrl_info_pci_nintrs(nvme_ctrl_info_t *, uint32_t *);
660 
661 /*
662  * These three items are only present if the device supports Namespace
663  * Management.
664  */
665 extern bool nvme_ctrl_info_cap(nvme_ctrl_info_t *, nvme_uint128_t *);
666 extern bool nvme_ctrl_info_unalloc_cap(nvme_ctrl_info_t *, nvme_uint128_t *);
667 extern bool nvme_ctrl_info_common_ns(nvme_ctrl_info_t *,
668     const nvme_identify_nsid_t **);
669 
670 /*
671  * The following information is specific to the NVM command set for controllers.
672  */
673 extern uint32_t nvme_ctrl_info_nformats(nvme_ctrl_info_t *);
674 extern bool nvme_ctrl_info_format(nvme_ctrl_info_t *, uint32_t,
675     const nvme_nvm_lba_fmt_t **);
676 extern uint32_t nvme_nvm_lba_fmt_id(const nvme_nvm_lba_fmt_t *);
677 extern uint32_t nvme_nvm_lba_fmt_meta_size(const nvme_nvm_lba_fmt_t *);
678 extern uint64_t nvme_nvm_lba_fmt_data_size(const nvme_nvm_lba_fmt_t *);
679 extern uint32_t nvme_nvm_lba_fmt_rel_perf(const nvme_nvm_lba_fmt_t *);
680 
681 /*
682  * Identify Operations
683  *
684  * The basic controller and namespace identify operations are a part of the
685  * controller and namespace snapshot facilities. These functions are designed to
686  * help enumerate and iterate lists of active and inactive namespaces,
687  * controllers, and related. The initial interface is a basic form that allows
688  * folks to create a request based on one that the library knows about as the
689  * kernel doesn't allow unknown requests.
690  *
691  * Eventually, when the kernel allows for arbitrary identify commands to be
692  * issued we can add an nvme_id_req_init() and the ability to set the CSI and
693  * CNS.
694  */
695 extern bool nvme_id_req_init_by_cns(nvme_ctrl_t *, nvme_csi_t, uint32_t,
696     nvme_id_req_t **);
697 extern void nvme_id_req_fini(nvme_id_req_t *);
698 
699 extern bool nvme_id_req_set_nsid(nvme_id_req_t *, uint32_t);
700 extern bool nvme_id_req_set_ctrlid(nvme_id_req_t *, uint32_t);
701 extern bool nvme_id_req_set_output(nvme_id_req_t *, void *, size_t);
702 extern bool nvme_id_req_clear_output(nvme_id_req_t *);
703 extern bool nvme_id_req_exec(nvme_id_req_t *);
704 
705 /*
706  * NVMe Namespace Discovery
707  *
708  * Namespaces come in various states. While the controller has a list of
709  * namespace IDs. The following enumeration describes namespace information with
710  * increasing specificity.
711  */
712 typedef enum {
713 	/*
714 	 * This returns all namespaces that are present on the device. This
715 	 * includes ones that may be ignored by the kernel or more.
716 	 */
717 	NVME_NS_DISC_F_ALL = 0,
718 	/*
719 	 * Only return namespaces that the controller considers to be allocated.
720 	 */
721 	NVME_NS_DISC_F_ALLOCATED,
722 	/*
723 	 * Only return namespaces that are active. If the controller does not
724 	 * support namespace management then all namespaces are considered
725 	 * active.
726 	 */
727 	NVME_NS_DISC_F_ACTIVE,
728 	/*
729 	 * The kernel has a notion of a namespace is ignored or not. In general,
730 	 * this is a subset of active namespaces that can actually be supported.
731 	 * They may or may not have a blkdev instance attached.
732 	 */
733 	NVME_NS_DISC_F_NOT_IGNORED,
734 	/*
735 	 * Only return namespaces that have blkdev actively attached. In other
736 	 * words these are disks that the OS can use.
737 	 */
738 	NVME_NS_DISC_F_BLKDEV
739 } nvme_ns_disc_level_t;
740 
741 typedef enum nvme_ns_disc_flags {
742 	NVME_NS_DISC_F_EUI64_VALID	= 1 << 0,
743 	NVME_NS_DISC_F_NGUID_VALID	= 1 << 1
744 } nvme_ns_disc_flags_t;
745 
746 extern uint32_t nvme_ns_disc_nsid(const nvme_ns_disc_t *);
747 extern nvme_ns_disc_level_t nvme_ns_disc_level(const nvme_ns_disc_t *);
748 extern nvme_ns_disc_flags_t nvme_ns_disc_flags(const nvme_ns_disc_t *);
749 extern const uint8_t *nvme_ns_disc_eui64(const nvme_ns_disc_t *);
750 extern const uint8_t *nvme_ns_disc_nguid(const nvme_ns_disc_t *);
751 
752 extern bool nvme_ns_discover_init(nvme_ctrl_t *, nvme_ns_disc_level_t,
753     nvme_ns_iter_t **);
754 extern nvme_iter_t nvme_ns_discover_step(nvme_ns_iter_t *,
755     const nvme_ns_disc_t **);
756 extern void nvme_ns_discover_fini(nvme_ns_iter_t *);
757 
758 typedef bool (*nvme_ns_disc_f)(nvme_ctrl_t *, const nvme_ns_disc_t *, void *);
759 extern bool nvme_ns_discover(nvme_ctrl_t *, nvme_ns_disc_level_t,
760     nvme_ns_disc_f, void *);
761 
762 extern bool nvme_ns_init(nvme_ctrl_t *, uint32_t, nvme_ns_t **);
763 extern bool nvme_ns_init_by_name(nvme_ctrl_t *, const char *, nvme_ns_t **);
764 extern void nvme_ns_fini(nvme_ns_t *);
765 
766 /*
767  * This is a convenience routine for opening up an NVMe controller and/or
768  * namespace. Many utilities refer to things as <controller>/<namespace>. As
769  * such, this will parse that apart. If no namespace is specified, it will be
770  * left as NULL. If the specified controller or namespace cannot be found, then
771  * the function will fail.
772  *
773  * Currently the only supported controller name is nvmeX, though we should
774  * support GUIDs at some point. The namespace id, EUI64, and NGUID are all
775  * supported for the namespace.
776  */
777 extern bool nvme_ctrl_ns_init(nvme_t *, const char *, nvme_ctrl_t **,
778     nvme_ns_t **);
779 
780 /*
781  * NVMe Namespace Information.
782  *
783  * Namespace information is broken into a few groups. There is basic information
784  * about the LBA formats and capacities (which are provided in block sizes).
785  * There is information about the IDs. Note the NGUID/EUI64 are fallible
786  * because they are optional.
787  */
788 extern bool nvme_ns_info_snap(nvme_ns_t *, nvme_ns_info_t **);
789 extern bool nvme_ctrl_ns_info_snap(nvme_ctrl_t *, uint32_t, nvme_ns_info_t **);
790 extern void nvme_ns_info_free(nvme_ns_info_t *);
791 
792 extern nvme_info_err_t nvme_ns_info_err(nvme_ns_info_t *);
793 extern int32_t nvme_ns_info_syserr(nvme_ns_info_t *);
794 extern const char *nvme_ns_info_errmsg(nvme_ns_info_t *);
795 extern size_t nvme_ns_info_errlen(nvme_ns_info_t *);
796 extern const char *nvme_ns_info_errtostr(nvme_ns_info_t *, nvme_info_err_t);
797 
798 extern uint32_t nvme_ns_info_nsid(nvme_ns_info_t *);
799 extern nvme_ns_disc_level_t nvme_ns_info_level(nvme_ns_info_t *);
800 extern const nvme_identify_nsid_t *nvme_ns_info_identify(nvme_ns_info_t *);
801 
802 extern bool nvme_ns_info_nguid(nvme_ns_info_t *, uint8_t [16]);
803 extern bool nvme_ns_info_eui64(nvme_ns_info_t *, uint8_t [8]);
804 
805 extern bool nvme_ns_info_size(nvme_ns_info_t *, uint64_t *);
806 extern bool nvme_ns_info_cap(nvme_ns_info_t *, uint64_t *);
807 extern bool nvme_ns_info_use(nvme_ns_info_t *, uint64_t *);
808 
809 extern bool nvme_ns_info_curformat(nvme_ns_info_t *,
810     const nvme_nvm_lba_fmt_t **);
811 extern bool nvme_ns_info_nformats(nvme_ns_info_t *, uint32_t *);
812 extern bool nvme_ns_info_format(nvme_ns_info_t *, uint32_t,
813     const nvme_nvm_lba_fmt_t **);
814 
815 extern bool nvme_ns_info_bd_addr(nvme_ns_info_t *, const char **);
816 
817 /*
818  * Controller and Namespace Locking
819  *
820  * A given controller can be active by several different parallel consumers.
821  */
822 extern bool nvme_ctrl_lock(nvme_ctrl_t *, nvme_lock_level_t, nvme_lock_flags_t);
823 extern void nvme_ctrl_unlock(nvme_ctrl_t *);
824 extern bool nvme_ns_lock(nvme_ns_t *, nvme_lock_level_t, nvme_lock_flags_t);
825 extern void nvme_ns_unlock(nvme_ns_t *);
826 
827 /*
828  * Namespace Attach and Detach
829  *
830  * These operations are used to attach and detach a blkdev device from a given
831  * namespace.
832  */
833 extern bool nvme_ns_bd_attach(nvme_ns_t *);
834 extern bool nvme_ns_bd_detach(nvme_ns_t *);
835 
836 /*
837  * NVMe Log Page Discovery
838  *
839  * NVMe Log Pages provide some complications around discovery. There are
840  * standard log pages, which are either mandatory or optional. There are also
841  * vendor-specific log pages that we may know about. While NVMe 2.0 introduced a
842  * way to list all of the supported log pages a device implements, that is not
843  * true for most devices. Pre 2.x devices sometimes have a vendor-specific way
844  * to list all the available logs. The NVMe 2.0 based mechanism also does not
845  * provide a means of getting additional information such as required fields, so
846  * we'll end up always needing the additional information this interface
847  * provides.
848  *
849  * The log page discovery functions here allow a caller to just ask for all the
850  * known IDs that exist for something. The discovery callback will fire once for
851  * each log page that may be implemented. Log pages we know that aren't
852  * implemented are never called back for.
853  */
854 extern const char *nvme_log_disc_name(const nvme_log_disc_t *);
855 extern const char *nvme_log_disc_desc(const nvme_log_disc_t *);
856 extern nvme_csi_t nvme_log_disc_csi(const nvme_log_disc_t *);
857 extern uint32_t nvme_log_disc_lid(const nvme_log_disc_t *);
858 extern nvme_log_disc_kind_t nvme_log_disc_kind(const nvme_log_disc_t *);
859 extern nvme_log_disc_source_t nvme_log_disc_sources(const nvme_log_disc_t *);
860 extern nvme_log_disc_fields_t nvme_log_disc_fields(const nvme_log_disc_t *);
861 extern nvme_log_disc_scope_t nvme_log_disc_scopes(const nvme_log_disc_t *);
862 extern bool nvme_log_disc_impl(const nvme_log_disc_t *);
863 
864 typedef enum {
865 	/*
866 	 * This indicates that the size of a log page is unknown. Instead, we
867 	 * will return a size that is reasonable enough to hopefully cover most
868 	 * things.
869 	 */
870 	NVME_LOG_SIZE_K_UNKNOWN	= 0,
871 	/*
872 	 * This indicates that there is a known fixed size for the log page and
873 	 * we have indicated what that is.
874 	 */
875 	NVME_LOG_SIZE_K_FIXED,
876 	/*
877 	 * This indicates that the total log size is variable; however, it can
878 	 * be determined by reading the specified following number of bytes.
879 	 * Once that number of bytes has been read, that can be passed to the
880 	 * nvme_log_disc_cal_size() function, which will attempt to determine
881 	 * the actual number of bytes based on the returned data.
882 	 */
883 	NVME_LOG_SIZE_K_VAR
884 } nvme_log_size_kind_t;
885 extern nvme_log_size_kind_t nvme_log_disc_size(const nvme_log_disc_t *,
886     uint64_t *);
887 extern bool nvme_log_disc_calc_size(const nvme_log_disc_t *, uint64_t *,
888     const void *, size_t);
889 
890 /*
891  * Duplicate and free log discovery information. The free function should only
892  * be used when it is explicitly duplicated or obtained through something like
893  * nvme_log_req_init_by_name(). It must not be used on the constant data
894  * provided as part of the nvme_log_discover family of functions.
895  */
896 extern bool nvme_log_disc_dup(nvme_ctrl_t *, const nvme_log_disc_t *,
897     nvme_log_disc_t **);
898 extern void nvme_log_disc_free(nvme_log_disc_t *);
899 
900 extern bool nvme_log_discover_init(nvme_ctrl_t *, nvme_log_disc_scope_t,
901     uint32_t, nvme_log_iter_t **);
902 extern nvme_iter_t nvme_log_discover_step(nvme_log_iter_t *,
903     const nvme_log_disc_t **);
904 extern void nvme_log_discover_fini(nvme_log_iter_t *);
905 
906 typedef bool (*nvme_log_disc_f)(nvme_ctrl_t *, const nvme_log_disc_t *,
907     void *);
908 extern bool nvme_log_discover(nvme_ctrl_t *, nvme_log_disc_scope_t,
909     uint32_t, nvme_log_disc_f, void *);
910 
911 /*
912  * One does not simply request a log page. There are a lot of parameters that
913  * are used to get a log page and these have been evolving over time. For
914  * example, the size has changed between 1.2 and 1.3, NVMe 1.0 never had UUIDs,
915  * LSP, LSIs, there are optional features around supporting offsets, etc.
916  *
917  * To deal with the fact that this keeps changing and an attempt to create a
918  * stable ABI, we instead have an opaque structure that allows various fields to
919  * be set and changed. To speed this up, this can be bootstrapped from the
920  * discovery information directly or indirectly by the log page short name.
921  *
922  * Once all of the appropriate fields are set on a log page request then it can
923  * be executed. A given request may be executed multiple times.
924  *
925  * When creating a raw log request, it will be up to the caller to fill in and
926  * set up the log ID (lid) and the output information. It is assumed that by
927  * default a log request should specify the NVM CSI. When using
928  * nvme_log_req_init_by_disc(), the log ID and command set will be filled in
929  * automatically. The discovery flags will indicate what other fields are still
930  * required.
931  */
932 extern bool nvme_log_req_init(nvme_ctrl_t *, nvme_log_req_t **);
933 extern bool nvme_log_req_init_by_disc(nvme_ctrl_t *, const nvme_log_disc_t *,
934     nvme_log_req_t **);
935 extern bool nvme_log_req_init_by_name(nvme_ctrl_t *, const char *,
936     uint32_t, nvme_log_disc_t **, nvme_log_req_t **);
937 extern void nvme_log_req_fini(nvme_log_req_t *);
938 
939 extern bool nvme_log_req_set_lid(nvme_log_req_t *, uint32_t);
940 extern bool nvme_log_req_set_lsp(nvme_log_req_t *, uint32_t);
941 extern bool nvme_log_req_set_lsi(nvme_log_req_t *, uint32_t);
942 extern bool nvme_log_req_set_uuid(nvme_log_req_t *, uint32_t);
943 extern bool nvme_log_req_set_nsid(nvme_log_req_t *, uint32_t);
944 extern bool nvme_log_req_set_output(nvme_log_req_t *, void *, size_t);
945 extern bool nvme_log_req_clear_output(nvme_log_req_t *);
946 extern bool nvme_log_req_set_offset(nvme_log_req_t *, uint64_t);
947 extern bool nvme_log_req_set_rae(nvme_log_req_t *, bool);
948 extern bool nvme_log_req_set_csi(nvme_log_req_t *, nvme_csi_t);
949 extern bool nvme_log_req_exec(nvme_log_req_t *);
950 
951 /*
952  * Feature Discovery and Management
953  *
954  * Features are parts of the NVMe specification that can both be retrieved and
955  * set. Features are often either a uint32_t or a larger data payload. In
956  * addition, there are additional modifiers that are required to select
957  * information about features. For example, when getting or setting a
958  * temperature threshold feature, a temperature sensor ID is required. Much like
959  * with log pages this has changed and added new arguments to getting and
960  * setting a feature at the command level and the individual features have grown
961  * support for more configuration as well.
962  *
963  * We currently provide information in discovery to determine what is required
964  * to get a feature as well as the ability to fast path that. Currently we
965  * provide the raw feature getting API that works at the low level. There is no
966  * higher level API for specific features. This works okay for an nvmeadm(8)
967  * style implementation, but we should consider adding more here based on
968  * feedback from consumers.
969  *
970  * Currently the kernel does not support setting features, which is why there is
971  * not a set feature API exposed through here. When it is, there will be an
972  * analogues set feature API to the get feature API that allows for one to
973  * build this up generically.
974  */
975 extern const char *nvme_feat_disc_short(const nvme_feat_disc_t *);
976 extern const char *nvme_feat_disc_spec(const nvme_feat_disc_t *);
977 extern uint32_t nvme_feat_disc_fid(const nvme_feat_disc_t *);
978 extern nvme_feat_scope_t nvme_feat_disc_scope(const nvme_feat_disc_t *);
979 extern nvme_feat_kind_t nvme_feat_disc_kind(const nvme_feat_disc_t *);
980 extern nvme_feat_csi_t nvme_feat_disc_csi(const nvme_feat_disc_t *);
981 extern nvme_feat_flags_t nvme_feat_disc_flags(const nvme_feat_disc_t *);
982 extern nvme_get_feat_fields_t nvme_feat_disc_fields_get(
983     const nvme_feat_disc_t *);
984 extern nvme_set_feat_fields_t nvme_feat_disc_fields_set(
985     const nvme_feat_disc_t *);
986 extern nvme_feat_output_t nvme_feat_disc_output_get(const nvme_feat_disc_t *);
987 extern nvme_feat_output_t nvme_feat_disc_output_set(const nvme_feat_disc_t *);
988 extern uint64_t nvme_feat_disc_data_size(const nvme_feat_disc_t *);
989 extern nvme_feat_impl_t nvme_feat_disc_impl(const nvme_feat_disc_t *);
990 
991 extern bool nvme_feat_discover_init(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t,
992     nvme_feat_iter_t **);
993 extern nvme_iter_t nvme_feat_discover_step(nvme_feat_iter_t *,
994     const nvme_feat_disc_t **);
995 extern void nvme_feat_discover_fini(nvme_feat_iter_t *);
996 
997 extern bool nvme_feat_disc_dup(nvme_ctrl_t *, const nvme_feat_disc_t *,
998     nvme_feat_disc_t **);
999 extern void nvme_feat_disc_free(nvme_feat_disc_t *);
1000 
1001 typedef bool (*nvme_feat_disc_f)(nvme_ctrl_t *, const nvme_feat_disc_t *,
1002     void *);
1003 extern bool nvme_feat_discover(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t,
1004     nvme_feat_disc_f, void *);
1005 
1006 /*
1007  * Get Feature Request
1008  *
1009  * The get feature request allows one to build up a get feature command. It is
1010  * recommended to initiate a request based on discovery information or a
1011  * feature's name. That will allow the system to perform better validation, know
1012  * what fields are required or not, and pre-set parameters like the feature id
1013  * (fid). By default, a get features request will always ask for the current
1014  * value. Unless you want a saved or default value (and the controller is new
1015  * enough), then there is no need to set the selector. The only required field
1016  * when not using discovery information is the fid.
1017  */
1018 extern bool nvme_get_feat_req_init(nvme_ctrl_t *, nvme_get_feat_req_t **);
1019 extern bool nvme_get_feat_req_init_by_disc(nvme_ctrl_t *,
1020     const nvme_feat_disc_t *, nvme_get_feat_req_t **);
1021 extern bool nvme_get_feat_req_init_by_name(nvme_ctrl_t *, const char *,
1022     uint32_t, nvme_feat_disc_t **, nvme_get_feat_req_t **);
1023 extern void nvme_get_feat_req_fini(nvme_get_feat_req_t *);
1024 
1025 extern bool nvme_get_feat_req_set_fid(nvme_get_feat_req_t *, uint32_t);
1026 extern bool nvme_get_feat_req_set_sel(nvme_get_feat_req_t *, uint32_t);
1027 extern bool nvme_get_feat_req_set_nsid(nvme_get_feat_req_t *, uint32_t);
1028 extern bool nvme_get_feat_req_set_cdw11(nvme_get_feat_req_t *, uint32_t);
1029 extern bool nvme_get_feat_req_set_output(nvme_get_feat_req_t *, void *, size_t);
1030 extern bool nvme_get_feat_req_clear_output(nvme_get_feat_req_t *);
1031 extern bool nvme_get_feat_req_exec(nvme_get_feat_req_t *);
1032 extern bool nvme_get_feat_req_get_cdw0(nvme_get_feat_req_t *, uint32_t *);
1033 
1034 /*
1035  * NVMe Vendor Unique Command Discovery and Execution
1036  *
1037  * There is a standard form of vendor unique commands which are indicated in the
1038  * identify controller datasheet. The first set of pieces here allows one to
1039  * discover which vendor-specific commands are supported by a device that are
1040  * known to the library. These generally have their own implementation
1041  * function; however, that isn't really linked to from the discovery function.
1042  * Tied into this is also asking if a given controller supports a given command
1043  * and getting information about it.
1044  *
1045  * The second set of functions here is all around allocating a vendor unique
1046  * command then executing it. Currently only admin commands are supported
1047  * through this interface.
1048  */
1049 extern bool nvme_vuc_discover_init(nvme_ctrl_t *, uint32_t,
1050     nvme_vuc_iter_t **);
1051 extern nvme_iter_t nvme_vuc_discover_step(nvme_vuc_iter_t *,
1052     const nvme_vuc_disc_t **);
1053 extern void nvme_vuc_discover_fini(nvme_vuc_iter_t *);
1054 
1055 typedef bool (*nvme_vuc_disc_f)(nvme_ctrl_t *, const nvme_vuc_disc_t *, void *);
1056 extern bool nvme_vuc_discover(nvme_ctrl_t *, uint32_t, nvme_vuc_disc_f, void *);
1057 
1058 extern bool nvme_vuc_discover_by_name(nvme_ctrl_t *, const char *, uint32_t,
1059     nvme_vuc_disc_t **);
1060 extern bool nvme_vuc_disc_dup(nvme_ctrl_t *, const nvme_vuc_disc_t *,
1061     nvme_vuc_disc_t **);
1062 extern void nvme_vuc_disc_free(nvme_vuc_disc_t *);
1063 
1064 extern const char *nvme_vuc_disc_name(const nvme_vuc_disc_t *);
1065 extern const char *nvme_vuc_disc_desc(const nvme_vuc_disc_t *);
1066 extern uint32_t nvme_vuc_disc_opcode(const nvme_vuc_disc_t *);
1067 
1068 typedef enum {
1069 	/*
1070 	 * Indicates that when this command is run, one should assume that all
1071 	 * data is potentially erased.
1072 	 */
1073 	NVME_VUC_DISC_IMPACT_DATA	= 1 << 0,
1074 	/*
1075 	 * Indicates that when this command is run, one should assume that the
1076 	 * list of namespaces and their attributes will change.
1077 	 */
1078 	NVME_VUC_DISC_IMPACT_NS		= 1 << 1
1079 } nvme_vuc_disc_impact_t;
1080 extern nvme_vuc_disc_impact_t nvme_vuc_disc_impact(const nvme_vuc_disc_t *);
1081 
1082 typedef enum {
1083 	NVME_VUC_DISC_IO_NONE	= 0,
1084 	/*
1085 	 * Indicates that this command needs additional data provided as input
1086 	 * to the command.
1087 	 */
1088 	NVME_VUC_DISC_IO_INPUT	= 1 << 0,
1089 	/*
1090 	 * Indicates that this command writes output back to the host from the
1091 	 * controller and a data buffer is required.
1092 	 */
1093 	NVME_VUC_DISC_IO_OUTPUT	= 1 << 1
1094 } nvme_vuc_disc_io_t;
1095 extern nvme_vuc_disc_io_t nvme_vuc_disc_dt(const nvme_vuc_disc_t *);
1096 
1097 typedef enum {
1098 	/*
1099 	 * Indicates that the library has no opinion on whether a lock should be
1100 	 * taken or not.
1101 	 */
1102 	NVME_VUC_DISC_LOCK_NONE	= 0,
1103 	/*
1104 	 * Indicates that a controller or namespace level read lock is
1105 	 * recommended for this operation.
1106 	 */
1107 	NVME_VUC_DISC_LOCK_READ,
1108 	/*
1109 	 * Indicates that a controller or namespace level write lock is
1110 	 * recommended for this operation.
1111 	 */
1112 	NVME_VUC_DISC_LOCK_WRITE
1113 } nvme_vuc_disc_lock_t;
1114 extern nvme_vuc_disc_lock_t nvme_vuc_disc_lock(const nvme_vuc_disc_t *);
1115 
1116 extern bool nvme_vuc_req_init(nvme_ctrl_t *, nvme_vuc_req_t **);
1117 extern void nvme_vuc_req_fini(nvme_vuc_req_t *);
1118 
1119 extern bool nvme_vuc_req_set_opcode(nvme_vuc_req_t *, uint32_t);
1120 extern bool nvme_vuc_req_set_nsid(nvme_vuc_req_t *, uint32_t);
1121 extern bool nvme_vuc_req_set_timeout(nvme_vuc_req_t *, uint32_t);
1122 extern bool nvme_vuc_req_set_cdw12(nvme_vuc_req_t *, uint32_t);
1123 extern bool nvme_vuc_req_set_cdw13(nvme_vuc_req_t *, uint32_t);
1124 extern bool nvme_vuc_req_set_cdw14(nvme_vuc_req_t *, uint32_t);
1125 extern bool nvme_vuc_req_set_cdw15(nvme_vuc_req_t *, uint32_t);
1126 extern bool nvme_vuc_req_set_impact(nvme_vuc_req_t *, nvme_vuc_disc_impact_t);
1127 extern bool nvme_vuc_req_set_input(nvme_vuc_req_t *, const void *, size_t);
1128 extern bool nvme_vuc_req_set_output(nvme_vuc_req_t *, void *, size_t);
1129 extern bool nvme_vuc_req_clear_output(nvme_vuc_req_t *);
1130 
1131 /*
1132  * Execute a request. After a request is executed, the status information
1133  * becomes available. A call to exec will invalidate any prior results. If the
1134  * request does not make it to the controller for some reason or some other
1135  * error occurs, then getting the results will fail. If the controller fails the
1136  * command, that will set the NVME_ERR_CONTROLLER error and the corresponding
1137  * SCT/SC values can be retrieved from the controller's error information for
1138  * inspection.
1139  */
1140 extern bool nvme_vuc_req_exec(nvme_vuc_req_t *);
1141 extern bool nvme_vuc_req_get_cdw0(nvme_vuc_req_t *, uint32_t *);
1142 
1143 /*
1144  * Firmware Download and Commit (Activation)
1145  *
1146  * NVMe devices have a buffer that is used to receive a firmware download. This
1147  * can then be committed into a firmware slot or a boot slot through the commit
1148  * action. The commit action may also change which firmware slot is activated on
1149  * the next boot at the same time as installing an image or a commit can be used
1150  * to just change the active image. The optional bootloader features will have a
1151  * similar shape as to the firmware commit routines, but ultimately be different
1152  * ones to make it more obvious what is being done.
1153  *
1154  * The firmware download command has to date not really changed through the NVMe
1155  * 1.x and 2.0 standards, which is why it is not broken into a request and
1156  * execution format like others at this time.
1157  *
1158  * Firmware must be loaded with a particular granularity and if blocks do not
1159  * conform to that, nvme_fw_load() will return an error.
1160  */
1161 extern bool nvme_fw_load(nvme_ctrl_t *, const void *, size_t, uint64_t);
1162 
1163 extern bool nvme_fw_commit_req_init(nvme_ctrl_t *, nvme_fw_commit_req_t **);
1164 extern void nvme_fw_commit_req_fini(nvme_fw_commit_req_t *);
1165 extern bool nvme_fw_commit_req_set_slot(nvme_fw_commit_req_t *, uint32_t);
1166 extern bool nvme_fw_commit_req_set_action(nvme_fw_commit_req_t *, uint32_t);
1167 extern bool nvme_fw_commit_req_exec(nvme_fw_commit_req_t *);
1168 
1169 /*
1170  * Format NVM
1171  *
1172  * This is used to erase and reformat either all namespaces or a specific one.
1173  * We currently do not support setting metadata or protection information for
1174  * namespaces in the kernel which is why this is not present in the library.
1175  */
1176 extern bool nvme_format_req_init(nvme_ctrl_t *, nvme_format_req_t **);
1177 extern void nvme_format_req_fini(nvme_format_req_t *);
1178 extern bool nvme_format_req_set_lbaf(nvme_format_req_t *, uint32_t);
1179 extern bool nvme_format_req_set_ses(nvme_format_req_t *, uint32_t);
1180 extern bool nvme_format_req_set_nsid(nvme_format_req_t *, uint32_t);
1181 extern bool nvme_format_req_exec(nvme_format_req_t *);
1182 
1183 /*
1184  * Vendor-specific interfaces.
1185  */
1186 
1187 /*
1188  * WDC resizing functions. These are interfaces supported in the SN840, SN650,
1189  * SN655, etc. These end up allowing one to adjust the overprovisioning ratio,
1190  * though this ends up reformatting the device and all namespaces in the
1191  * process. The values passed and returned are in GB (not GiB).
1192  */
1193 extern bool nvme_wdc_resize_set(nvme_ctrl_t *, uint32_t);
1194 extern bool nvme_wdc_resize_get(nvme_ctrl_t *, uint32_t *);
1195 
1196 /*
1197  * WDC e6 diagnostic log. The e6 log is a WDC-specific diagnostic log which
1198  * contains information about the device itself.
1199  */
1200 extern bool nvme_wdc_e6_req_init(nvme_ctrl_t *, nvme_wdc_e6_req_t **);
1201 extern void nvme_wdc_e6_req_fini(nvme_wdc_e6_req_t *);
1202 extern bool nvme_wdc_e6_req_set_offset(nvme_wdc_e6_req_t *, uint64_t);
1203 extern bool nvme_wdc_e6_req_set_output(nvme_wdc_e6_req_t *, void *,
1204     size_t);
1205 extern bool nvme_wdc_e6_req_clear_output(nvme_wdc_e6_req_t *);
1206 extern bool nvme_wdc_e6_req_exec(nvme_wdc_e6_req_t *);
1207 
1208 /*
1209  * WDC assert injection and removal.
1210  */
1211 extern bool nvme_wdc_assert_clear(nvme_ctrl_t *);
1212 extern bool nvme_wdc_assert_inject(nvme_ctrl_t *);
1213 
1214 #ifdef __cplusplus
1215 }
1216 #endif
1217 
1218 #endif /* _LIBNVME_H */
1219