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