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