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