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 2026 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 blkdev attach and detach 409 * operations failed to complete due to an error in the underlying 410 * kernel subsystems. For detach this might happen because of a disk 411 * being open, busy in a zpool, or something else. For attach, it may 412 * suggest an 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 /* 439 * Indicates that the controller does not support namespace management 440 * operations including controller attach/detach and namespace 441 * create/delete. 442 */ 443 NVME_ERR_NS_MGMT_UNSUP_BY_DEV, 444 /* 445 * Indicates that the controller does not support thin provisioning. 446 */ 447 NVME_ERR_THIN_PROV_UNSUP_BY_DEV, 448 /* 449 * These indicate that the corresponding requests cannot be executed due 450 * to missing fields. 451 */ 452 NVME_ERR_NS_ATTACH_REQ_MISSING_FIELDS, 453 NVME_ERR_NS_CREATE_REQ_MISSING_FIELDS, 454 NVME_ERR_NS_DELETE_REQ_MISSING_FIELDS, 455 /* 456 * This specifically is used by the namespace creation functions to 457 * indicate that a requested CSI is not supported. Currently this could 458 * be because the CSI is invalid, the device doesn't support it, the 459 * kernel doesn't support it, etc. 460 * 461 * The namespace attach variant is the same logic, just applied to the 462 * selector. Both of these are phrased differently as the set of fields 463 * that may or may not be valid for a given request of these types can 464 * vary based on the type. 465 */ 466 NVME_ERR_NS_CREATE_BAD_CSI, 467 NVME_ERR_NS_ATTACH_BAD_SEL, 468 /* 469 * Indicates that the NSID result value is not valid because we have not 470 * yet executed a namespace create request. 471 */ 472 NVME_ERR_NS_CREATE_NO_RESULTS, 473 /* 474 * Indicates that the create namespace field is outside of the valid 475 * range for the field. 476 */ 477 NVME_ERR_NS_CREATE_NCAP_RANGE, 478 NVME_ERR_NS_CREATE_NSZE_RANGE, 479 NVME_ERR_NS_CREATE_NMIC_RANGE, 480 NVME_ERR_NS_CREATE_FLBAS_RANGE, 481 /* 482 * Indicates that the operation cannot proceed because the namespace is 483 * already attached or not attached to a controller respectively. 484 */ 485 NVME_ERR_NS_CTRL_ATTACHED, 486 NVME_ERR_NS_CTRL_NOT_ATTACHED, 487 /* 488 * Indicates that the namespace is unallocated and therefore the 489 * operation cannot proceed. 490 */ 491 NVME_ERR_NS_UNALLOC, 492 /* 493 * Indicates that a library function was referring to a PCIe lane number 494 * that is not valid for the device. 495 */ 496 NVME_ERR_PCIE_LANE_RANGE, 497 /* 498 * Indicates that a PCIe eye diagram buffer size was too small. 499 */ 500 NVME_ERR_PCIE_EYE_BUF_RANGE 501 } nvme_err_t; 502 503 /* 504 * Errors used for the various information errors. This is shared between both 505 * controller and namespace information structures. 506 */ 507 typedef enum { 508 NVME_INFO_ERR_OK, 509 /* 510 * Indicates that the item is not supported because this is the wrong 511 * controller transport. For example, asking about a PCI ID for 512 * something that is not PCI-based. 513 */ 514 NVME_INFO_ERR_TRANSPORT, 515 /* 516 * Indicates that the item is not supported because the device version 517 * is too old to get this. 518 */ 519 NVME_INFO_ERR_VERSION, 520 /* 521 * Indicates that we could not get certain information because the 522 * device does not support a given capability. 523 */ 524 NVME_INFO_ERR_MISSING_CAP, 525 /* 526 * Indicates that the specified format value is unknown. 527 */ 528 NVME_INFO_ERR_BAD_LBA_FMT, 529 /* 530 * These errors only occur during attempts to persist information and 531 * indicate challenges allocating memory or otherwise challenges with 532 * libnvpair. 533 */ 534 NVME_INFO_ERR_PERSIST_NVL, 535 /* 536 * The first indicates that the index is invalid or if it is technically 537 * within the valid LBA format range, but there is no data size. The 538 * second indicates that we can't actually fully represent the data 539 * here. This happens because say the LBA size can't be represented by a 540 * uint64_t. 541 */ 542 NVME_INFO_ERR_BAD_FMT, 543 NVME_INFO_ERR_BAD_FMT_DATA, 544 /* 545 * Indicates that the information cannot be returned because the 546 * namespace's state does not allow us to answer this question. This may 547 * be because it's inactive as below or because blkdev is not attached. 548 */ 549 NVME_INFO_ERR_NS_INACTIVE, 550 NVME_INFO_ERR_NS_NO_BLKDEV 551 } nvme_info_err_t; 552 553 typedef struct nvme nvme_t; 554 typedef struct nvme_ctrl nvme_ctrl_t; 555 typedef struct nvme_ctrl_iter nvme_ctrl_iter_t; 556 typedef struct nvme_ctrl_disc nvme_ctrl_disc_t; 557 typedef struct nvme_ctrl_info nvme_ctrl_info_t; 558 typedef struct nvme_ns nvme_ns_t; 559 typedef struct nvme_ns_iter nvme_ns_iter_t; 560 typedef struct nvme_ns_disc nvme_ns_disc_t; 561 typedef struct nvme_ns_info nvme_ns_info_t; 562 typedef struct nvme_nvm_lba_fmt nvme_nvm_lba_fmt_t; 563 typedef struct nvme_log_iter nvme_log_iter_t; 564 typedef struct nvme_log_disc nvme_log_disc_t; 565 typedef struct nvme_log_req nvme_log_req_t; 566 typedef struct nvme_id_req nvme_id_req_t; 567 typedef struct nvme_vuc_iter nvme_vuc_iter_t; 568 typedef struct nvme_vuc_disc nvme_vuc_disc_t; 569 typedef struct nvme_vuc_req nvme_vuc_req_t; 570 typedef struct nvme_fw_commit_req nvme_fw_commit_req_t; 571 typedef struct nvme_format_req nvme_format_req_t; 572 typedef struct nvme_feat_disc nvme_feat_disc_t; 573 typedef struct nvme_feat_iter nvme_feat_iter_t; 574 typedef struct nvme_get_feat_req nvme_get_feat_req_t; 575 typedef struct nvme_ns_attach_req nvme_ns_attach_req_t; 576 typedef struct nvme_ns_create_req nvme_ns_create_req_t; 577 typedef struct nvme_ns_delete_req nvme_ns_delete_req_t; 578 579 /* 580 * Vendor-specific forwards. 581 */ 582 typedef struct nvme_wdc_e6_req nvme_wdc_e6_req_t; 583 584 extern nvme_t *nvme_init(void); 585 extern void nvme_fini(nvme_t *); 586 587 /* 588 * Error information. Operations that take an nvme_t, always set error 589 * information on the nvme_t. Operations that operate on a controller or are 590 * related to a request object or iterator that starts from the controller 591 * set error information on the nvme_ctrl_t. 592 */ 593 extern nvme_err_t nvme_err(nvme_t *); 594 extern int32_t nvme_syserr(nvme_t *); 595 extern const char *nvme_errmsg(nvme_t *); 596 extern size_t nvme_errlen(nvme_t *); 597 extern const char *nvme_errtostr(nvme_t *, nvme_err_t); 598 599 extern nvme_err_t nvme_ctrl_err(nvme_ctrl_t *); 600 extern int32_t nvme_ctrl_syserr(nvme_ctrl_t *); 601 extern const char *nvme_ctrl_errmsg(nvme_ctrl_t *); 602 extern size_t nvme_ctrl_errlen(nvme_ctrl_t *); 603 extern void nvme_ctrl_deverr(nvme_ctrl_t *, uint32_t *, uint32_t *); 604 extern const char *nvme_ctrl_errtostr(nvme_ctrl_t *, nvme_err_t); 605 606 /* 607 * Translations for NVMe spec error constants. These end up taking the 608 * nvme_ctrl_t so that way they can potentially translate vendor-specific errors 609 * if they are defined. A NULL controller is allowed, which will skip all such 610 * processing altogether. Both functions will always a return a string so there 611 * is no need to check for NULL (though it may just be a variant of "unknown 612 * ..."). 613 * 614 * If NULL is passed for the controller in nvme_sctostr(), we will assume that 615 * the controller's type is a traditional PCI I/O controller and not a fabric 616 * based controller, which further changes the way that command-specific status 617 * codes are interpreted. Due to the lack of support in the system for 618 * different controller types, this function will always assume a PCI I/O 619 * controller currently. 620 */ 621 extern const char *nvme_scttostr(nvme_ctrl_t *, uint32_t); 622 extern const char *nvme_sctostr(nvme_ctrl_t *, nvme_csi_t, uint32_t, uint32_t); 623 624 typedef enum nvme_iter { 625 NVME_ITER_VALID, 626 NVME_ITER_DONE, 627 NVME_ITER_ERROR 628 } nvme_iter_t; 629 630 /* 631 * NVMe Controller discovery. 632 */ 633 extern di_node_t nvme_ctrl_disc_devi(const nvme_ctrl_disc_t *); 634 extern di_minor_t nvme_ctrl_disc_minor(const nvme_ctrl_disc_t *); 635 636 extern bool nvme_ctrl_discover_init(nvme_t *, nvme_ctrl_iter_t **); 637 extern nvme_iter_t nvme_ctrl_discover_step(nvme_ctrl_iter_t *, 638 const nvme_ctrl_disc_t **); 639 extern void nvme_ctrl_discover_fini(nvme_ctrl_iter_t *); 640 641 typedef bool (*nvme_ctrl_disc_f)(nvme_t *, const nvme_ctrl_disc_t *, void *); 642 extern bool nvme_ctrl_discover(nvme_t *, nvme_ctrl_disc_f, void *); 643 644 extern bool nvme_ctrl_init(nvme_t *, di_node_t, nvme_ctrl_t **); 645 extern bool nvme_ctrl_init_by_instance(nvme_t *, int32_t, nvme_ctrl_t **); 646 extern bool nvme_ctrl_devi(nvme_ctrl_t *, di_node_t *); 647 extern void nvme_ctrl_fini(nvme_ctrl_t *); 648 649 /* 650 * Get information about a controller. This information about a controller is 651 * separate from the lifetime of the controller itself. This is done to 652 * facilitate the ability of saving and using this information on another 653 * system and make the management a bit easier. Errors appear on this object and 654 * not the nmve_t. 655 */ 656 extern bool nvme_ctrl_info_snap(nvme_ctrl_t *, nvme_ctrl_info_t **); 657 extern bool nvme_ctrl_info_restore(nvme_t *, nvlist_t *, nvme_ctrl_info_t **); 658 extern bool nvme_ctrl_info_persist(nvme_ctrl_info_t *, nvlist_t **); 659 extern void nvme_ctrl_info_free(nvme_ctrl_info_t *); 660 661 extern nvme_info_err_t nvme_ctrl_info_err(nvme_ctrl_info_t *); 662 extern int32_t nvme_ctrl_info_syserr(nvme_ctrl_info_t *); 663 extern const char *nvme_ctrl_info_errmsg(nvme_ctrl_info_t *); 664 extern size_t nvme_ctrl_info_errlen(nvme_ctrl_info_t *); 665 extern const char *nvme_ctrl_info_errtostr(nvme_ctrl_info_t *, nvme_info_err_t); 666 667 /* 668 * Information about an NVMe controller. This information is a combination of 669 * the identify data structure which can be retrieved directly by folks who 670 * would prefer to use it. Common fields that are used in something like nvmeadm 671 * or other utilities who would rather not need to know about the specifics of 672 * the data structure or have to think about the version can use that instead. 673 * 674 * NVMe 2.x has kept the identify controller data structure backwards 675 * compatible. If a future version were to invalidate that, then this could 676 * possibly return NULL. 677 */ 678 extern uint16_t nvme_ctrl_info_vendor(nvme_ctrl_info_t *); 679 extern const nvme_identify_ctrl_t *nvme_ctrl_info_identify(nvme_ctrl_info_t *); 680 extern const nvme_version_t *nvme_ctrl_info_version(nvme_ctrl_info_t *); 681 extern const char *nvme_ctrl_info_model(nvme_ctrl_info_t *); 682 extern const char *nvme_ctrl_info_serial(nvme_ctrl_info_t *); 683 extern uint32_t nvme_ctrl_info_fwgran(nvme_ctrl_info_t *); 684 extern const char *nvme_ctrl_info_fwrev(nvme_ctrl_info_t *); 685 extern uint32_t nvme_ctrl_info_nns(nvme_ctrl_info_t *); 686 687 typedef enum { 688 NVME_CTRL_TRANSPORT_PCI, 689 NVME_CTRL_TRANSPORT_TCP, 690 NVME_CTRL_TRANSPORT_RDMA, 691 } nvme_ctrl_transport_t; 692 693 typedef enum { 694 NVME_CTRL_TYPE_UNKNOWN, 695 NVME_CTRL_TYPE_IO, 696 NVME_CTRL_TYPE_ADMIN, 697 NVME_CTRL_TYPE_DISCOVERY, 698 } nvme_ctrl_type_t; 699 700 /* 701 * Controller types were explicitly added in the NVMe 1.4 specification. Prior 702 * to that all controllers were required to support issuing I/O, hence we return 703 * them as NVME_CTRL_TYPE_IO, even though this isn't quite by the spec. In 1.4 704 * this was added to the identify controller information. The 'UNKNOWN' type is 705 * for cases where we don't recognize the value based upon the standard. 706 */ 707 extern nvme_ctrl_type_t nvme_ctrl_info_type(nvme_ctrl_info_t *); 708 extern nvme_ctrl_transport_t nvme_ctrl_info_transport(nvme_ctrl_info_t *); 709 710 /* 711 * The following pieces of information are specific to PCI NVMe controllers and 712 * are not from the common identify controller data structure. As such they are 713 * fallible. The first group come from configuration space while the others are 714 * information that comes from the actual controller capability registers. 715 */ 716 extern bool nvme_ctrl_info_pci_vid(nvme_ctrl_info_t *, uint16_t *); 717 extern bool nvme_ctrl_info_pci_did(nvme_ctrl_info_t *, uint16_t *); 718 extern bool nvme_ctrl_info_pci_rev(nvme_ctrl_info_t *, uint8_t *); 719 extern bool nvme_ctrl_info_pci_subvid(nvme_ctrl_info_t *, uint16_t *); 720 extern bool nvme_ctrl_info_pci_subsys(nvme_ctrl_info_t *, uint16_t *); 721 722 extern bool nvme_ctrl_info_pci_mps_min(nvme_ctrl_info_t *, uint32_t *); 723 extern bool nvme_ctrl_info_pci_mps_max(nvme_ctrl_info_t *, uint32_t *); 724 725 extern bool nvme_ctrl_info_pci_nintrs(nvme_ctrl_info_t *, uint32_t *); 726 727 /* 728 * These three items are only present if the device supports Namespace 729 * Management. 730 */ 731 extern bool nvme_ctrl_info_cap(nvme_ctrl_info_t *, nvme_uint128_t *); 732 extern bool nvme_ctrl_info_unalloc_cap(nvme_ctrl_info_t *, nvme_uint128_t *); 733 extern bool nvme_ctrl_info_common_ns(nvme_ctrl_info_t *, 734 const nvme_identify_nsid_t **); 735 736 /* 737 * The following information is specific to the NVM command set for controllers. 738 */ 739 extern uint32_t nvme_ctrl_info_nformats(nvme_ctrl_info_t *); 740 extern bool nvme_ctrl_info_format(nvme_ctrl_info_t *, uint32_t, 741 const nvme_nvm_lba_fmt_t **); 742 extern uint32_t nvme_nvm_lba_fmt_id(const nvme_nvm_lba_fmt_t *); 743 extern uint32_t nvme_nvm_lba_fmt_meta_size(const nvme_nvm_lba_fmt_t *); 744 extern uint64_t nvme_nvm_lba_fmt_data_size(const nvme_nvm_lba_fmt_t *); 745 extern uint32_t nvme_nvm_lba_fmt_rel_perf(const nvme_nvm_lba_fmt_t *); 746 747 /* 748 * Identify Operations 749 * 750 * The basic controller and namespace identify operations are a part of the 751 * controller and namespace snapshot facilities. These functions are designed to 752 * help enumerate and iterate lists of active and inactive namespaces, 753 * controllers, and related. The initial interface is a basic form that allows 754 * folks to create a request based on one that the library knows about as the 755 * kernel doesn't allow unknown requests. 756 * 757 * Eventually, when the kernel allows for arbitrary identify commands to be 758 * issued we can add an nvme_id_req_init() and the ability to set the CSI and 759 * CNS. 760 */ 761 extern bool nvme_id_req_init_by_cns(nvme_ctrl_t *, nvme_csi_t, uint32_t, 762 nvme_id_req_t **); 763 extern void nvme_id_req_fini(nvme_id_req_t *); 764 765 extern bool nvme_id_req_set_nsid(nvme_id_req_t *, uint32_t); 766 extern bool nvme_id_req_set_ctrlid(nvme_id_req_t *, uint32_t); 767 extern bool nvme_id_req_set_output(nvme_id_req_t *, void *, size_t); 768 extern bool nvme_id_req_clear_output(nvme_id_req_t *); 769 extern bool nvme_id_req_exec(nvme_id_req_t *); 770 771 /* 772 * NVMe Namespace Discovery 773 * 774 * Namespaces come in various states. While the controller has a list of 775 * namespace IDs. The following enumeration describes namespace information with 776 * increasing specificity. 777 */ 778 typedef enum { 779 /* 780 * This returns all namespaces that are present on the device. This 781 * includes ones that may be ignored by the kernel or more. 782 */ 783 NVME_NS_DISC_F_ALL = 0, 784 /* 785 * Only return namespaces that the controller considers to be allocated. 786 */ 787 NVME_NS_DISC_F_ALLOCATED, 788 /* 789 * Only return namespaces that are active. If the controller does not 790 * support namespace management then all namespaces are considered 791 * active. 792 */ 793 NVME_NS_DISC_F_ACTIVE, 794 /* 795 * The kernel has a notion of a namespace is ignored or not. In general, 796 * this is a subset of active namespaces that can actually be supported. 797 * They may or may not have a blkdev instance attached. 798 */ 799 NVME_NS_DISC_F_NOT_IGNORED, 800 /* 801 * Only return namespaces that have blkdev actively attached. In other 802 * words these are disks that the OS can use. 803 */ 804 NVME_NS_DISC_F_BLKDEV 805 } nvme_ns_disc_level_t; 806 807 typedef enum nvme_ns_disc_flags { 808 NVME_NS_DISC_F_EUI64_VALID = 1 << 0, 809 NVME_NS_DISC_F_NGUID_VALID = 1 << 1 810 } nvme_ns_disc_flags_t; 811 812 extern uint32_t nvme_ns_disc_nsid(const nvme_ns_disc_t *); 813 extern nvme_ns_disc_level_t nvme_ns_disc_level(const nvme_ns_disc_t *); 814 extern nvme_ns_disc_flags_t nvme_ns_disc_flags(const nvme_ns_disc_t *); 815 extern const uint8_t *nvme_ns_disc_eui64(const nvme_ns_disc_t *); 816 extern const uint8_t *nvme_ns_disc_nguid(const nvme_ns_disc_t *); 817 818 extern bool nvme_ns_discover_init(nvme_ctrl_t *, nvme_ns_disc_level_t, 819 nvme_ns_iter_t **); 820 extern nvme_iter_t nvme_ns_discover_step(nvme_ns_iter_t *, 821 const nvme_ns_disc_t **); 822 extern void nvme_ns_discover_fini(nvme_ns_iter_t *); 823 824 typedef bool (*nvme_ns_disc_f)(nvme_ctrl_t *, const nvme_ns_disc_t *, void *); 825 extern bool nvme_ns_discover(nvme_ctrl_t *, nvme_ns_disc_level_t, 826 nvme_ns_disc_f, void *); 827 828 extern bool nvme_ns_init(nvme_ctrl_t *, uint32_t, nvme_ns_t **); 829 extern bool nvme_ns_init_by_name(nvme_ctrl_t *, const char *, nvme_ns_t **); 830 extern void nvme_ns_fini(nvme_ns_t *); 831 832 /* 833 * This is a convenience routine for opening up an NVMe controller and/or 834 * namespace. Many utilities refer to things as <controller>/<namespace>. As 835 * such, this will parse that apart. If no namespace is specified, it will be 836 * left as NULL. If the specified controller or namespace cannot be found, then 837 * the function will fail. 838 * 839 * Currently the only supported controller name is nvmeX, though we should 840 * support GUIDs at some point. The namespace id, EUI64, and NGUID are all 841 * supported for the namespace. 842 */ 843 extern bool nvme_ctrl_ns_init(nvme_t *, const char *, nvme_ctrl_t **, 844 nvme_ns_t **); 845 846 /* 847 * NVMe Namespace Information. 848 * 849 * Namespace information is broken into a few groups. There is basic information 850 * about the LBA formats and capacities (which are provided in block sizes). 851 * There is information about the IDs. Note the NGUID/EUI64 are fallible 852 * because they are optional. 853 */ 854 extern bool nvme_ns_info_snap(nvme_ns_t *, nvme_ns_info_t **); 855 extern bool nvme_ctrl_ns_info_snap(nvme_ctrl_t *, uint32_t, nvme_ns_info_t **); 856 extern void nvme_ns_info_free(nvme_ns_info_t *); 857 858 extern nvme_info_err_t nvme_ns_info_err(nvme_ns_info_t *); 859 extern int32_t nvme_ns_info_syserr(nvme_ns_info_t *); 860 extern const char *nvme_ns_info_errmsg(nvme_ns_info_t *); 861 extern size_t nvme_ns_info_errlen(nvme_ns_info_t *); 862 extern const char *nvme_ns_info_errtostr(nvme_ns_info_t *, nvme_info_err_t); 863 864 extern uint32_t nvme_ns_info_nsid(nvme_ns_info_t *); 865 extern nvme_ns_disc_level_t nvme_ns_info_level(nvme_ns_info_t *); 866 extern const nvme_identify_nsid_t *nvme_ns_info_identify(nvme_ns_info_t *); 867 868 extern bool nvme_ns_info_nguid(nvme_ns_info_t *, uint8_t [16]); 869 extern bool nvme_ns_info_eui64(nvme_ns_info_t *, uint8_t [8]); 870 871 extern bool nvme_ns_info_size(nvme_ns_info_t *, uint64_t *); 872 extern bool nvme_ns_info_cap(nvme_ns_info_t *, uint64_t *); 873 extern bool nvme_ns_info_use(nvme_ns_info_t *, uint64_t *); 874 875 extern bool nvme_ns_info_curformat(nvme_ns_info_t *, 876 const nvme_nvm_lba_fmt_t **); 877 extern bool nvme_ns_info_nformats(nvme_ns_info_t *, uint32_t *); 878 extern bool nvme_ns_info_format(nvme_ns_info_t *, uint32_t, 879 const nvme_nvm_lba_fmt_t **); 880 881 extern bool nvme_ns_info_bd_addr(nvme_ns_info_t *, const char **); 882 883 /* 884 * Controller and Namespace Locking 885 * 886 * A given controller can be active by several different parallel consumers. 887 */ 888 extern bool nvme_ctrl_lock(nvme_ctrl_t *, nvme_lock_level_t, nvme_lock_flags_t); 889 extern void nvme_ctrl_unlock(nvme_ctrl_t *); 890 extern bool nvme_ns_lock(nvme_ns_t *, nvme_lock_level_t, nvme_lock_flags_t); 891 extern void nvme_ns_unlock(nvme_ns_t *); 892 893 /* 894 * Namespace Attach and Detach 895 * 896 * These operations are used to attach and detach a blkdev device from a given 897 * namespace. 898 */ 899 extern bool nvme_ns_bd_attach(nvme_ns_t *); 900 extern bool nvme_ns_bd_detach(nvme_ns_t *); 901 902 /* 903 * NVMe Log Page Discovery 904 * 905 * NVMe Log Pages provide some complications around discovery. There are 906 * standard log pages, which are either mandatory or optional. There are also 907 * vendor-specific log pages that we may know about. While NVMe 2.0 introduced a 908 * way to list all of the supported log pages a device implements, that is not 909 * true for most devices. Pre 2.x devices sometimes have a vendor-specific way 910 * to list all the available logs. The NVMe 2.0 based mechanism also does not 911 * provide a means of getting additional information such as required fields, so 912 * we'll end up always needing the additional information this interface 913 * provides. 914 * 915 * The log page discovery functions here allow a caller to just ask for all the 916 * known IDs that exist for something. The discovery callback will fire once for 917 * each log page that may be implemented. Log pages we know that aren't 918 * implemented are never called back for. 919 */ 920 extern const char *nvme_log_disc_name(const nvme_log_disc_t *); 921 extern const char *nvme_log_disc_desc(const nvme_log_disc_t *); 922 extern const char *const *nvme_log_disc_aliases(const nvme_log_disc_t *); 923 extern size_t nvme_log_disc_naliases(const nvme_log_disc_t *); 924 extern nvme_csi_t nvme_log_disc_csi(const nvme_log_disc_t *); 925 extern uint32_t nvme_log_disc_lid(const nvme_log_disc_t *); 926 extern nvme_log_disc_kind_t nvme_log_disc_kind(const nvme_log_disc_t *); 927 extern nvme_log_disc_source_t nvme_log_disc_sources(const nvme_log_disc_t *); 928 extern nvme_log_disc_fields_t nvme_log_disc_fields(const nvme_log_disc_t *); 929 extern nvme_log_disc_scope_t nvme_log_disc_scopes(const nvme_log_disc_t *); 930 extern bool nvme_log_disc_impl(const nvme_log_disc_t *); 931 932 typedef enum { 933 /* 934 * This indicates that the size of a log page is unknown. Instead, we 935 * will return a size that is reasonable enough to hopefully cover most 936 * things. 937 */ 938 NVME_LOG_SIZE_K_UNKNOWN = 0, 939 /* 940 * This indicates that there is a known fixed size for the log page and 941 * we have indicated what that is. 942 */ 943 NVME_LOG_SIZE_K_FIXED, 944 /* 945 * This indicates that the total log size is variable; however, it can 946 * be determined by reading the specified following number of bytes. 947 * Once that number of bytes has been read, that can be passed to the 948 * nvme_log_disc_cal_size() function, which will attempt to determine 949 * the actual number of bytes based on the returned data. 950 */ 951 NVME_LOG_SIZE_K_VAR 952 } nvme_log_size_kind_t; 953 extern nvme_log_size_kind_t nvme_log_disc_size(const nvme_log_disc_t *, 954 uint64_t *); 955 extern bool nvme_log_disc_calc_size(const nvme_log_disc_t *, uint64_t *, 956 const void *, size_t); 957 958 /* 959 * Duplicate and free log discovery information. The free function should only 960 * be used when it is explicitly duplicated or obtained through something like 961 * nvme_log_req_init_by_name(). It must not be used on the constant data 962 * provided as part of the nvme_log_discover family of functions. 963 */ 964 extern bool nvme_log_disc_dup(nvme_ctrl_t *, const nvme_log_disc_t *, 965 nvme_log_disc_t **); 966 extern void nvme_log_disc_free(nvme_log_disc_t *); 967 968 extern bool nvme_log_discover_init(nvme_ctrl_t *, nvme_log_disc_scope_t, 969 uint32_t, nvme_log_iter_t **); 970 extern nvme_iter_t nvme_log_discover_step(nvme_log_iter_t *, 971 const nvme_log_disc_t **); 972 extern void nvme_log_discover_fini(nvme_log_iter_t *); 973 974 typedef bool (*nvme_log_disc_f)(nvme_ctrl_t *, const nvme_log_disc_t *, 975 void *); 976 extern bool nvme_log_discover(nvme_ctrl_t *, nvme_log_disc_scope_t, 977 uint32_t, nvme_log_disc_f, void *); 978 979 /* 980 * One does not simply request a log page. There are a lot of parameters that 981 * are used to get a log page and these have been evolving over time. For 982 * example, the size has changed between 1.2 and 1.3, NVMe 1.0 never had UUIDs, 983 * LSP, LSIs, there are optional features around supporting offsets, etc. 984 * 985 * To deal with the fact that this keeps changing and an attempt to create a 986 * stable ABI, we instead have an opaque structure that allows various fields to 987 * be set and changed. To speed this up, this can be bootstrapped from the 988 * discovery information directly or indirectly by the log page short name. 989 * 990 * Once all of the appropriate fields are set on a log page request then it can 991 * be executed. A given request may be executed multiple times. 992 * 993 * When creating a raw log request, it will be up to the caller to fill in and 994 * set up the log ID (lid) and the output information. It is assumed that by 995 * default a log request should specify the NVM CSI. When using 996 * nvme_log_req_init_by_disc(), the log ID and command set will be filled in 997 * automatically. The discovery flags will indicate what other fields are still 998 * required. 999 */ 1000 extern bool nvme_log_req_init(nvme_ctrl_t *, nvme_log_req_t **); 1001 extern bool nvme_log_req_init_by_disc(nvme_ctrl_t *, const nvme_log_disc_t *, 1002 nvme_log_req_t **); 1003 extern bool nvme_log_req_init_by_name(nvme_ctrl_t *, const char *, 1004 uint32_t, nvme_log_disc_t **, nvme_log_req_t **); 1005 extern void nvme_log_req_fini(nvme_log_req_t *); 1006 1007 extern bool nvme_log_req_set_lid(nvme_log_req_t *, uint32_t); 1008 extern bool nvme_log_req_set_lsp(nvme_log_req_t *, uint32_t); 1009 extern bool nvme_log_req_set_lsi(nvme_log_req_t *, uint32_t); 1010 extern bool nvme_log_req_set_uuid(nvme_log_req_t *, uint32_t); 1011 extern bool nvme_log_req_set_nsid(nvme_log_req_t *, uint32_t); 1012 extern bool nvme_log_req_set_output(nvme_log_req_t *, void *, size_t); 1013 extern bool nvme_log_req_clear_output(nvme_log_req_t *); 1014 extern bool nvme_log_req_set_offset(nvme_log_req_t *, uint64_t); 1015 extern bool nvme_log_req_set_rae(nvme_log_req_t *, bool); 1016 extern bool nvme_log_req_set_csi(nvme_log_req_t *, nvme_csi_t); 1017 extern bool nvme_log_req_exec(nvme_log_req_t *); 1018 1019 /* 1020 * Feature Discovery and Management 1021 * 1022 * Features are parts of the NVMe specification that can both be retrieved and 1023 * set. Features are often either a uint32_t or a larger data payload. In 1024 * addition, there are additional modifiers that are required to select 1025 * information about features. For example, when getting or setting a 1026 * temperature threshold feature, a temperature sensor ID is required. Much like 1027 * with log pages this has changed and added new arguments to getting and 1028 * setting a feature at the command level and the individual features have grown 1029 * support for more configuration as well. 1030 * 1031 * We currently provide information in discovery to determine what is required 1032 * to get a feature as well as the ability to fast path that. Currently we 1033 * provide the raw feature getting API that works at the low level. There is no 1034 * higher level API for specific features. This works okay for an nvmeadm(8) 1035 * style implementation, but we should consider adding more here based on 1036 * feedback from consumers. 1037 * 1038 * Currently the kernel does not support setting features, which is why there is 1039 * not a set feature API exposed through here. When it is, there will be an 1040 * analogues set feature API to the get feature API that allows for one to 1041 * build this up generically. 1042 */ 1043 extern const char *nvme_feat_disc_short(const nvme_feat_disc_t *); 1044 extern const char *nvme_feat_disc_spec(const nvme_feat_disc_t *); 1045 extern uint32_t nvme_feat_disc_fid(const nvme_feat_disc_t *); 1046 extern nvme_feat_scope_t nvme_feat_disc_scope(const nvme_feat_disc_t *); 1047 extern nvme_feat_kind_t nvme_feat_disc_kind(const nvme_feat_disc_t *); 1048 extern nvme_feat_csi_t nvme_feat_disc_csi(const nvme_feat_disc_t *); 1049 extern nvme_feat_flags_t nvme_feat_disc_flags(const nvme_feat_disc_t *); 1050 extern nvme_get_feat_fields_t nvme_feat_disc_fields_get( 1051 const nvme_feat_disc_t *); 1052 extern nvme_set_feat_fields_t nvme_feat_disc_fields_set( 1053 const nvme_feat_disc_t *); 1054 extern nvme_feat_output_t nvme_feat_disc_output_get(const nvme_feat_disc_t *); 1055 extern nvme_feat_output_t nvme_feat_disc_output_set(const nvme_feat_disc_t *); 1056 extern uint64_t nvme_feat_disc_data_size(const nvme_feat_disc_t *); 1057 extern nvme_feat_impl_t nvme_feat_disc_impl(const nvme_feat_disc_t *); 1058 1059 extern bool nvme_feat_discover_init(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t, 1060 nvme_feat_iter_t **); 1061 extern nvme_iter_t nvme_feat_discover_step(nvme_feat_iter_t *, 1062 const nvme_feat_disc_t **); 1063 extern void nvme_feat_discover_fini(nvme_feat_iter_t *); 1064 1065 extern bool nvme_feat_disc_dup(nvme_ctrl_t *, const nvme_feat_disc_t *, 1066 nvme_feat_disc_t **); 1067 extern void nvme_feat_disc_free(nvme_feat_disc_t *); 1068 1069 typedef bool (*nvme_feat_disc_f)(nvme_ctrl_t *, const nvme_feat_disc_t *, 1070 void *); 1071 extern bool nvme_feat_discover(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t, 1072 nvme_feat_disc_f, void *); 1073 1074 /* 1075 * Get Feature Request 1076 * 1077 * The get feature request allows one to build up a get feature command. It is 1078 * recommended to initiate a request based on discovery information or a 1079 * feature's name. That will allow the system to perform better validation, know 1080 * what fields are required or not, and pre-set parameters like the feature id 1081 * (fid). By default, a get features request will always ask for the current 1082 * value. Unless you want a saved or default value (and the controller is new 1083 * enough), then there is no need to set the selector. The only required field 1084 * when not using discovery information is the fid. 1085 */ 1086 extern bool nvme_get_feat_req_init(nvme_ctrl_t *, nvme_get_feat_req_t **); 1087 extern bool nvme_get_feat_req_init_by_disc(nvme_ctrl_t *, 1088 const nvme_feat_disc_t *, nvme_get_feat_req_t **); 1089 extern bool nvme_get_feat_req_init_by_name(nvme_ctrl_t *, const char *, 1090 uint32_t, nvme_feat_disc_t **, nvme_get_feat_req_t **); 1091 extern void nvme_get_feat_req_fini(nvme_get_feat_req_t *); 1092 1093 extern bool nvme_get_feat_req_set_fid(nvme_get_feat_req_t *, uint32_t); 1094 extern bool nvme_get_feat_req_set_sel(nvme_get_feat_req_t *, uint32_t); 1095 extern bool nvme_get_feat_req_set_nsid(nvme_get_feat_req_t *, uint32_t); 1096 extern bool nvme_get_feat_req_set_cdw11(nvme_get_feat_req_t *, uint32_t); 1097 extern bool nvme_get_feat_req_set_output(nvme_get_feat_req_t *, void *, size_t); 1098 extern bool nvme_get_feat_req_clear_output(nvme_get_feat_req_t *); 1099 extern bool nvme_get_feat_req_exec(nvme_get_feat_req_t *); 1100 extern bool nvme_get_feat_req_get_cdw0(nvme_get_feat_req_t *, uint32_t *); 1101 1102 /* 1103 * NVMe Vendor Unique Command Discovery and Execution 1104 * 1105 * There is a standard form of vendor unique commands which are indicated in the 1106 * identify controller datasheet. The first set of pieces here allows one to 1107 * discover which vendor-specific commands are supported by a device that are 1108 * known to the library. These generally have their own implementation 1109 * function; however, that isn't really linked to from the discovery function. 1110 * Tied into this is also asking if a given controller supports a given command 1111 * and getting information about it. 1112 * 1113 * The second set of functions here is all around allocating a vendor unique 1114 * command then executing it. Currently only admin commands are supported 1115 * through this interface. 1116 */ 1117 extern bool nvme_vuc_discover_init(nvme_ctrl_t *, uint32_t, 1118 nvme_vuc_iter_t **); 1119 extern nvme_iter_t nvme_vuc_discover_step(nvme_vuc_iter_t *, 1120 const nvme_vuc_disc_t **); 1121 extern void nvme_vuc_discover_fini(nvme_vuc_iter_t *); 1122 1123 typedef bool (*nvme_vuc_disc_f)(nvme_ctrl_t *, const nvme_vuc_disc_t *, void *); 1124 extern bool nvme_vuc_discover(nvme_ctrl_t *, uint32_t, nvme_vuc_disc_f, void *); 1125 1126 extern bool nvme_vuc_discover_by_name(nvme_ctrl_t *, const char *, uint32_t, 1127 nvme_vuc_disc_t **); 1128 extern bool nvme_vuc_disc_dup(nvme_ctrl_t *, const nvme_vuc_disc_t *, 1129 nvme_vuc_disc_t **); 1130 extern void nvme_vuc_disc_free(nvme_vuc_disc_t *); 1131 1132 extern const char *nvme_vuc_disc_name(const nvme_vuc_disc_t *); 1133 extern const char *nvme_vuc_disc_desc(const nvme_vuc_disc_t *); 1134 extern uint32_t nvme_vuc_disc_opcode(const nvme_vuc_disc_t *); 1135 1136 typedef enum { 1137 /* 1138 * Indicates that when this command is run, one should assume that all 1139 * data is potentially erased. 1140 */ 1141 NVME_VUC_DISC_IMPACT_DATA = 1 << 0, 1142 /* 1143 * Indicates that when this command is run, one should assume that the 1144 * list of namespaces and their attributes will change. 1145 */ 1146 NVME_VUC_DISC_IMPACT_NS = 1 << 1 1147 } nvme_vuc_disc_impact_t; 1148 extern nvme_vuc_disc_impact_t nvme_vuc_disc_impact(const nvme_vuc_disc_t *); 1149 1150 typedef enum { 1151 NVME_VUC_DISC_IO_NONE = 0, 1152 /* 1153 * Indicates that this command needs additional data provided as input 1154 * to the command. 1155 */ 1156 NVME_VUC_DISC_IO_INPUT = 1 << 0, 1157 /* 1158 * Indicates that this command writes output back to the host from the 1159 * controller and a data buffer is required. 1160 */ 1161 NVME_VUC_DISC_IO_OUTPUT = 1 << 1 1162 } nvme_vuc_disc_io_t; 1163 extern nvme_vuc_disc_io_t nvme_vuc_disc_dt(const nvme_vuc_disc_t *); 1164 1165 typedef enum { 1166 /* 1167 * Indicates that the library has no opinion on whether a lock should be 1168 * taken or not. 1169 */ 1170 NVME_VUC_DISC_LOCK_NONE = 0, 1171 /* 1172 * Indicates that a controller or namespace level read lock is 1173 * recommended for this operation. 1174 */ 1175 NVME_VUC_DISC_LOCK_READ, 1176 /* 1177 * Indicates that a controller or namespace level write lock is 1178 * recommended for this operation. 1179 */ 1180 NVME_VUC_DISC_LOCK_WRITE 1181 } nvme_vuc_disc_lock_t; 1182 extern nvme_vuc_disc_lock_t nvme_vuc_disc_lock(const nvme_vuc_disc_t *); 1183 1184 extern bool nvme_vuc_req_init(nvme_ctrl_t *, nvme_vuc_req_t **); 1185 extern void nvme_vuc_req_fini(nvme_vuc_req_t *); 1186 1187 extern bool nvme_vuc_req_set_opcode(nvme_vuc_req_t *, uint32_t); 1188 extern bool nvme_vuc_req_set_nsid(nvme_vuc_req_t *, uint32_t); 1189 extern bool nvme_vuc_req_set_timeout(nvme_vuc_req_t *, uint32_t); 1190 extern bool nvme_vuc_req_set_cdw12(nvme_vuc_req_t *, uint32_t); 1191 extern bool nvme_vuc_req_set_cdw13(nvme_vuc_req_t *, uint32_t); 1192 extern bool nvme_vuc_req_set_cdw14(nvme_vuc_req_t *, uint32_t); 1193 extern bool nvme_vuc_req_set_cdw15(nvme_vuc_req_t *, uint32_t); 1194 extern bool nvme_vuc_req_set_impact(nvme_vuc_req_t *, nvme_vuc_disc_impact_t); 1195 extern bool nvme_vuc_req_set_input(nvme_vuc_req_t *, const void *, size_t); 1196 extern bool nvme_vuc_req_set_output(nvme_vuc_req_t *, void *, size_t); 1197 extern bool nvme_vuc_req_clear_output(nvme_vuc_req_t *); 1198 1199 /* 1200 * Execute a request. After a request is executed, the status information 1201 * becomes available. A call to exec will invalidate any prior results. If the 1202 * request does not make it to the controller for some reason or some other 1203 * error occurs, then getting the results will fail. If the controller fails the 1204 * command, that will set the NVME_ERR_CONTROLLER error and the corresponding 1205 * SCT/SC values can be retrieved from the controller's error information for 1206 * inspection. 1207 */ 1208 extern bool nvme_vuc_req_exec(nvme_vuc_req_t *); 1209 extern bool nvme_vuc_req_get_cdw0(nvme_vuc_req_t *, uint32_t *); 1210 1211 /* 1212 * Firmware Download and Commit (Activation) 1213 * 1214 * NVMe devices have a buffer that is used to receive a firmware download. This 1215 * can then be committed into a firmware slot or a boot slot through the commit 1216 * action. The commit action may also change which firmware slot is activated on 1217 * the next boot at the same time as installing an image or a commit can be used 1218 * to just change the active image. The optional bootloader features will have a 1219 * similar shape as to the firmware commit routines, but ultimately be different 1220 * ones to make it more obvious what is being done. 1221 * 1222 * The firmware download command has to date not really changed through the NVMe 1223 * 1.x and 2.0 standards, which is why it is not broken into a request and 1224 * execution format like others at this time. 1225 * 1226 * Firmware must be loaded with a particular granularity and if blocks do not 1227 * conform to that, nvme_fw_load() will return an error. 1228 */ 1229 extern bool nvme_fw_load(nvme_ctrl_t *, const void *, size_t, uint64_t); 1230 1231 extern bool nvme_fw_commit_req_init(nvme_ctrl_t *, nvme_fw_commit_req_t **); 1232 extern void nvme_fw_commit_req_fini(nvme_fw_commit_req_t *); 1233 extern bool nvme_fw_commit_req_set_slot(nvme_fw_commit_req_t *, uint32_t); 1234 extern bool nvme_fw_commit_req_set_action(nvme_fw_commit_req_t *, uint32_t); 1235 extern bool nvme_fw_commit_req_exec(nvme_fw_commit_req_t *); 1236 1237 /* 1238 * Format NVM 1239 * 1240 * This is used to erase and reformat either all namespaces or a specific one. 1241 * We currently do not support setting metadata or protection information for 1242 * namespaces in the kernel which is why this is not present in the library. 1243 */ 1244 extern bool nvme_format_req_init(nvme_ctrl_t *, nvme_format_req_t **); 1245 extern void nvme_format_req_fini(nvme_format_req_t *); 1246 extern bool nvme_format_req_set_lbaf(nvme_format_req_t *, uint32_t); 1247 extern bool nvme_format_req_set_ses(nvme_format_req_t *, uint32_t); 1248 extern bool nvme_format_req_set_nsid(nvme_format_req_t *, uint32_t); 1249 extern bool nvme_format_req_exec(nvme_format_req_t *); 1250 1251 /* 1252 * NVMe Namespace Attach 1253 * 1254 * This is used to attach or detach a collection of controllers to a namespace. 1255 * Currently the only way to specify a controller is to use the self flag on 1256 * here. In the future, we will likely have support for listing the explicit 1257 * controllers to specify here. 1258 */ 1259 extern bool nvme_ns_attach_req_init_by_sel(nvme_ctrl_t *, uint32_t, 1260 nvme_ns_attach_req_t **); 1261 extern void nvme_ns_attach_req_fini(nvme_ns_attach_req_t *); 1262 extern bool nvme_ns_attach_req_set_nsid(nvme_ns_attach_req_t *, uint32_t); 1263 extern bool nvme_ns_attach_req_set_ctrlid_self(nvme_ns_attach_req_t *); 1264 extern bool nvme_ns_attach_req_exec(nvme_ns_attach_req_t *); 1265 1266 /* 1267 * NVMe Namesapce Create and Delete 1268 */ 1269 extern bool nvme_ns_create_req_init_by_csi(nvme_ctrl_t *, nvme_csi_t, 1270 nvme_ns_create_req_t **); 1271 extern void nvme_ns_create_req_fini(nvme_ns_create_req_t *); 1272 extern bool nvme_ns_create_req_set_flbas(nvme_ns_create_req_t *, uint32_t); 1273 extern bool nvme_ns_create_req_set_nsze(nvme_ns_create_req_t *, uint64_t); 1274 extern bool nvme_ns_create_req_set_ncap(nvme_ns_create_req_t *, uint64_t); 1275 extern bool nvme_ns_create_req_set_nmic(nvme_ns_create_req_t *, uint32_t); 1276 extern bool nvme_ns_create_req_exec(nvme_ns_create_req_t *); 1277 extern bool nvme_ns_create_req_get_nsid(nvme_ns_create_req_t *, uint32_t *); 1278 1279 extern bool nvme_ns_delete_req_init(nvme_ctrl_t *, nvme_ns_delete_req_t **); 1280 extern void nvme_ns_delete_req_fini(nvme_ns_delete_req_t *); 1281 extern bool nvme_ns_delete_req_set_nsid(nvme_ns_delete_req_t *, uint32_t); 1282 extern bool nvme_ns_delete_req_exec(nvme_ns_delete_req_t *); 1283 1284 /* 1285 * Vendor-specific interfaces. 1286 */ 1287 1288 /* 1289 * WDC resizing functions. These are interfaces supported in the SN840, SN650, 1290 * SN655, etc. These end up allowing one to adjust the overprovisioning ratio, 1291 * though this ends up reformatting the device and all namespaces in the 1292 * process. The values passed and returned are in GB (not GiB). 1293 */ 1294 extern bool nvme_wdc_resize_set(nvme_ctrl_t *, uint32_t); 1295 extern bool nvme_wdc_resize_get(nvme_ctrl_t *, uint32_t *); 1296 1297 /* 1298 * WDC e6 diagnostic log. The e6 log is a WDC-specific diagnostic log which 1299 * contains information about the device itself. 1300 */ 1301 extern bool nvme_wdc_e6_req_init(nvme_ctrl_t *, nvme_wdc_e6_req_t **); 1302 extern void nvme_wdc_e6_req_fini(nvme_wdc_e6_req_t *); 1303 extern bool nvme_wdc_e6_req_set_offset(nvme_wdc_e6_req_t *, uint64_t); 1304 extern bool nvme_wdc_e6_req_set_output(nvme_wdc_e6_req_t *, void *, 1305 size_t); 1306 extern bool nvme_wdc_e6_req_clear_output(nvme_wdc_e6_req_t *); 1307 extern bool nvme_wdc_e6_req_exec(nvme_wdc_e6_req_t *); 1308 1309 /* 1310 * WDC assert injection and removal. 1311 */ 1312 extern bool nvme_wdc_assert_clear(nvme_ctrl_t *); 1313 extern bool nvme_wdc_assert_inject(nvme_ctrl_t *); 1314 1315 /* 1316 * Sandisk commands to get PCI eye diagrams and the hardware revision. 1317 */ 1318 extern bool nvme_sndk_pci_eye(nvme_ctrl_t *, uint8_t, void *, size_t); 1319 extern bool nvme_sndk_hw_rev(nvme_ctrl_t *, uint8_t *, uint8_t *); 1320 1321 #ifdef __cplusplus 1322 } 1323 #endif 1324 1325 #endif /* _LIBNVME_H */ 1326