libnvme/common/libnvme.h

/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2026 Oxide Computer Company
 */

#ifndef _LIBNVME_H
#define	_LIBNVME_H

/*
 * This contains an evolving set of interfaces for more programmatically
 * interfacing with NVMe devices. For more information on why the library looks
 * this way, please see lib/libnvme/common/libnvme.c.
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stdbool.h>
#include <libdevinfo.h>
#include <sys/nvme/discovery.h>

/*
 * Right now everything relies on seeing various pieces that are in sys/nvme.h,
 * unfortunately. This includes things like the identify, log page, and
 * structure data structures, various constants, and other things that have
 * accumulated. This must all be rejiggered prior to making this a committed
 * interface as we're leaking through many things that software needs.
 * Directionally splitting this out into headers that relate to the spec as
 * <sys/nvme/identify.h>, etc. would be useful and would address several of the
 * places that we're passing in raw uint32_t's for items that come from the spec
 * and could be a little more specific to help out consumers.
 */
#include <sys/nvme.h>

/*
 * General error classes that may be returned when operating on non-information
 * snapshots.
 */
typedef enum {
	NVME_ERR_OK	 = 0,
	/*
	 * Indicates that a command failed due to a controller-specific error.
	 * The controller's SCT/SC are valid in the corresponding objects error
	 * data.
	 */
	NVME_ERR_CONTROLLER,
	/*
	 * Indicates that there was a memory allocation error. The system error
	 * contains the specific errno.
	 */
	NVME_ERR_NO_MEM,
	/*
	 * Indicates that an operation could not complete because the kernel did
	 * not have DMA resources available for us.
	 */
	NVME_ERR_NO_DMA_MEM,
	/*
	 * Indicates that an error occurred while trying to use the devinfo
	 * library.
	 */
	NVME_ERR_LIBDEVINFO,
	/*
	 * Indicates that an internal error condition occurred.
	 */
	NVME_ERR_INTERNAL,
	/*
	 * Indicates that the function was given an invalid pointer argument.
	 */
	NVME_ERR_BAD_PTR,
	/*
	 * Indicates that an unknown flag argument was given to us.
	 */
	NVME_ERR_BAD_FLAG,
	/*
	 * Indicates that the devinfo node we were given doesn't correspond to
	 * an NVMe controller.
	 */
	NVME_ERR_BAD_DEVI,
	/*
	 * Indicates that while we found a devinfo property successfully,
	 * something about it does not match our expectations. This could be the
	 * type, number of values, range, etc.
	 */
	NVME_ERR_BAD_DEVI_PROP,
	/*
	 * Indicates that we were given an illegal instance (i.e. a negative
	 * instance).
	 */
	NVME_ERR_ILLEGAL_INSTANCE,
	/*
	 * Indicates that a means of identifying a controller (name, instance,
	 * etc.) does not match any known NVMe device.
	 */
	NVME_ERR_BAD_CONTROLLER,
	/*
	 * Indicates that a request could not proceed due to missing privileges.
	 */
	NVME_ERR_PRIVS,
	/*
	 * Indicates a failure to open a device file.
	 */
	NVME_ERR_OPEN_DEV,
	/*
	 * Indicates that the given restore data is not valid.
	 */
	NVME_ERR_BAD_RESTORE,
	/*
	 * Indicates that a namespace (name, ID, etc.) passed in is not valid on
	 * the controller. This may be because it's outside the valid range or
	 * there was an attempt to use the broadcast namespace when it's not
	 * supported.
	 */
	NVME_ERR_NS_RANGE,
	/*
	 * Indicates that a namespace ID is not usable in this context. For
	 * example, attempting to specify a namespace to an identify or log page
	 * that does not support them.
	 */
	NVME_ERR_NS_UNUSE,
	/*
	 * Indicates that the value for a get log page field is invalid. This
	 * may happened due to alignment, just being too large, or something
	 * else.
	 */
	NVME_ERR_LOG_CSI_RANGE,
	NVME_ERR_LOG_LID_RANGE,
	NVME_ERR_LOG_LSP_RANGE,
	NVME_ERR_LOG_LSI_RANGE,
	NVME_ERR_LOG_RAE_RANGE,
	NVME_ERR_LOG_SIZE_RANGE,
	NVME_ERR_LOG_OFFSET_RANGE,
	/*
	 * Indicates that the log field value given is not supported because the
	 * controller is not of a sufficient version or does not indicate that
	 * it is supported in the LPA field.
	 */
	NVME_ERR_LOG_CSI_UNSUP,
	NVME_ERR_LOG_LSP_UNSUP,
	NVME_ERR_LOG_LSI_UNSUP,
	NVME_ERR_LOG_RAE_UNSUP,
	NVME_ERR_LOG_OFFSET_UNSUP,
	/*
	 * Indicates that the log field value is unusable. The specifics of our
	 * request indicate that this cannot be set.
	 */
	NVME_ERR_LOG_LSP_UNUSE,
	NVME_ERR_LOG_LSI_UNUSE,
	NVME_ERR_LOG_RAE_UNUSE,
	/*
	 * Indicates that the log page's scope requires operating on something
	 * that isn't what was requested. This would happen if manually
	 * constructing a log page that operates on the controller, but passed a
	 * namespace (e.g. the firmware log page).
	 */
	NVME_ERR_LOG_SCOPE_MISMATCH,
	/*
	 * Indicates that a log request can't be executed because required
	 * fields have not been set.
	 */
	NVME_ERR_LOG_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the named log is unknown to the library.
	 */
	NVME_ERR_LOG_NAME_UNKNOWN,
	/*
	 * Indicates that the named log is not supported by the device.
	 */
	NVME_ERR_LOG_UNSUP_BY_DEV,
	/*
	 * Indicates that the IDENTIFY command requested is unknown.
	 */
	NVME_ERR_IDENTIFY_UNKNOWN,
	/*
	 * Indicates that the requested identify command is not supported by the
	 * device.
	 */
	NVME_ERR_IDENTIFY_UNSUP_BY_DEV,
	/*
	 * Indicates that the identify command parameter is outside of the valid
	 * range for the field.
	 */
	NVME_ERR_IDENTIFY_CTRLID_RANGE,
	NVME_ERR_IDENTIFY_OUTPUT_RANGE,
	/*
	 * Indicates that the parameter given is not supported because the
	 * controller is not of a sufficient version or does not indicate that
	 * it is supported.
	 */
	NVME_ERR_IDENTIFY_CTRLID_UNSUP,
	/*
	 * Indicates that the parameter given is not supported in the context of
	 * a given identify command. Namespaces are handled with the
	 * cross-command error code.
	 */
	NVME_ERR_IDENTIFY_CTRLID_UNUSE,
	/*
	 * Indicates that an identify request can't be executed because required
	 * fields have not been set.
	 */
	NVME_ERR_IDENTIFY_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the controller doesn't support the NVMe standard
	 * vendor unique command.
	 */
	NVME_ERR_VUC_UNSUP_BY_DEV,
	/*
	 * Indicates that the vendor unique command parameter is outside of the
	 * valid range for the field.
	 */
	NVME_ERR_VUC_TIMEOUT_RANGE,
	NVME_ERR_VUC_OPCODE_RANGE,
	NVME_ERR_VUC_IMPACT_RANGE,
	NVME_ERR_VUC_NDT_RANGE,
	/*
	 * Indicates that a vendor unique command already has an input or output
	 * buffer set and is being asked to set a separate one.
	 */
	NVME_ERR_VUC_CANNOT_RW,
	/*
	 * Indicates that the vendor unique request does not have valid
	 * execution context. This may be because the command was never executed
	 * or the exec failed in a way such that the controller never exercised
	 * the command.
	 */
	NVME_ERR_VUC_NO_RESULTS,
	/*
	 * Indicates that the named vendor unique command is not known to the
	 * library.
	 */
	NVME_ERR_VUC_UNKNOWN,
	/*
	 * Indicates that a vendor unique command can't be executed because
	 * required fields have not been set.
	 */
	NVME_ERR_VUC_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the vendor-specific library operation could not
	 * proceed because it is not supported by the given device.
	 */
	NVME_ERR_VU_FUNC_UNSUP_BY_DEV,
	/*
	 * WDC e6 dump specific invalid values
	 */
	NVME_ERR_WDC_E6_OFFSET_RANGE,
	/*
	 * Indicates that the controller does not support firmware related
	 * operations.
	 */
	NVME_ERR_FW_UNSUP_BY_DEV,
	/*
	 * Indicates that the constraints of the device and what the kernel can
	 * do make the firmware upgrade non-tenable.
	 */
	NVME_ERR_KERN_FW_IMPOS,
	/*
	 * Indicates that a firmware download parameter is invalid.
	 */
	NVME_ERR_FW_LOAD_LEN_RANGE,
	NVME_ERR_FW_LOAD_OFFSET_RANGE,
	/*
	 * Indicates that the firmware commit command parameter is outside of
	 * the valid range for the field.
	 */
	NVME_ERR_FW_COMMIT_SLOT_RANGE,
	NVME_ERR_FW_COMMIT_ACTION_RANGE,
	/*
	 * Indicates that a firmware commit command can't be executed because
	 * required fields have not been set.
	 */
	NVME_ERR_FW_COMMIT_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the firmware commit could not occur because the
	 * requested slot is read-only.
	 */
	NVME_ERR_FW_SLOT_RO,
	/*
	 * Indicates that the controller does not support NVM format operations.
	 */
	NVME_ERR_FORMAT_UNSUP_BY_DEV,
	/*
	 * Indicates that the controller does not support cryptographic secure
	 * erase.
	 */
	NVME_ERR_CRYPTO_SE_UNSUP_BY_DEV,
	/*
	 * Indicates that the NVM format command cannot be executed because it
	 * would target a specific namespace; however, the device does not allow
	 * a secure erase or a format to target an individual namespace.
	 */
	NVME_ERR_NS_FORMAT_UNSUP_BY_DEV,
	/*
	 * Indicates that the kernel does not support formatting with the
	 * specified LBA format, generally due to something like the use of
	 * metadata in the namespace.
	 */
	NVME_ERR_KERN_FORMAT_UNSUP,
	/*
	 * Indicates that the NVM format command parameter is outside of
	 * the valid range for the field.
	 */
	NVME_ERR_FORMAT_LBAF_RANGE,
	NVME_ERR_FORMAT_SES_RANGE,
	/*
	 * Indicates that the parameter and/or its value is not supported for a
	 * NVM format command.
	 */
	NVME_ERR_FORMAT_PARAM_UNSUP,
	/*
	 * Indicates that a NVM format command can't be executed because
	 * required fields have not been set.
	 */
	NVME_ERR_FORMAT_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the WDC e6 log dump request could not be executed due
	 * to fields not being set.
	 */
	NVME_ERR_WDC_E6_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the named feature is unknown to the library.
	 */
	NVME_ERR_FEAT_NAME_UNKNOWN,
	/*
	 * Indicates that the named feature is not supported by the device.
	 */
	NVME_ERR_FEAT_UNSUP_BY_DEV,
	/*
	 * Indicates that the feature parameter is outside of the valid range
	 * for the field.
	 */
	NVME_ERR_FEAT_FID_RANGE,
	NVME_ERR_FEAT_SEL_RANGE,
	NVME_ERR_FEAT_CDW11_RANGE,
	NVME_ERR_FEAT_DATA_RANGE,
	/*
	 * Indicates that the feature parameter given is not supported because
	 * the controller is not of a sufficient version.
	 */
	NVME_ERR_FEAT_SEL_UNSUP,
	/*
	 * Indicates that the get feature parameter given is not supported for
	 * the given feature. For example, passing in a cdw11 argument that is
	 * not needed.
	 */
	NVME_ERR_FEAT_CDW11_UNUSE,
	NVME_ERR_FEAT_DATA_UNUSE,
	/*
	 * Indicates that a feature request does not have valid output data.
	 * This may be because the command was never executed or it did not
	 * execute successfully.
	 */
	NVME_ERR_FEAT_NO_RESULTS,
	/*
	 * Indicates that a get features request can't be executed because
	 * required fields have not been set.
	 */
	NVME_ERR_GET_FEAT_REQ_MISSING_FIELDS,
	/*
	 * These indicate that the operation could not be executed because they
	 * require holding either a controller or namespace write lock and one
	 * is not held by the corresponding controller handle.
	 */
	NVME_ERR_NEED_CTRL_WRLOCK,
	NVME_ERR_NEED_NS_WRLOCK,
	/*
	 * These indicate that the operation could not be executed because the
	 * controller or namespace respectively currently have an exclusive
	 * write lock (or an equivalent future form) that blocks execution from
	 * others.
	 */
	NVME_ERR_CTRL_LOCKED,
	NVME_ERR_NS_LOCKED,
	/*
	 * Indicates that a fatal locking operation occurred that will terminate
	 * the process. This includes cases such as recursive enters on the same
	 * lock, attempting to unlock a lock that isn't owned, etc.
	 */
	NVME_ERR_LOCK_PROG,
	/*
	 * Indicates that a lock order violation was attempted. This includes
	 * things like taking the controller lock while holding the namespace
	 * lock, attempting to take a second namespace lock, holding a
	 * controller write lock and trying to get a namespace lock, etc.
	 */
	NVME_ERR_LOCK_ORDER,
	/*
	 * Indicates that a signal was encountered while attempting to take a
	 * lock.
	 */
	NVME_ERR_LOCK_WAIT_INTR,
	/*
	 * Indicates that attempting to take the lock failed because the thread
	 * would be required to block, but it asked not to.
	 */
	NVME_ERR_LOCK_WOULD_BLOCK,
	/*
	 * These indicate that the respective blkdev attach and detach
	 * operations failed to complete due to an error in the underlying
	 * kernel subsystems. For detach this might happen because of a disk
	 * being open, busy in a zpool, or something else. For attach, it may
	 * suggest an NDI or other issue.
	 */
	NVME_ERR_DETACH_KERN,
	NVME_ERR_ATTACH_KERN,
	/*
	 * Indicates that the kernel driver does not support some property of
	 * the requested namespace.
	 */
	NVME_ERR_ATTACH_UNSUP_KERN,
	/*
	 * Indicates that the operation cannot proceed because a namespace is
	 * attached to blkdev and it must be detached to proceed.
	 */
	NVME_ERR_NS_BLKDEV_ATTACH,
	/*
	 * Indicates that non-DMA kernel memory was not available for this
	 * request.
	 */
	NVME_ERR_NO_KERN_MEM,
	/*
	 * These two codes represent internal device conditions that indicate
	 * the device is unusable or that it was physically removed (usually due
	 * to hotplug).
	 */
	NVME_ERR_CTRL_DEAD,
	NVME_ERR_CTRL_GONE,
	/*
	 * Indicates that the controller does not support namespace management
	 * operations including controller attach/detach and namespace
	 * create/delete.
	 */
	NVME_ERR_NS_MGMT_UNSUP_BY_DEV,
	/*
	 * Indicates that the controller does not support thin provisioning.
	 */
	NVME_ERR_THIN_PROV_UNSUP_BY_DEV,
	/*
	 * These indicate that the corresponding requests cannot be executed due
	 * to missing fields.
	 */
	NVME_ERR_NS_ATTACH_REQ_MISSING_FIELDS,
	NVME_ERR_NS_CREATE_REQ_MISSING_FIELDS,
	NVME_ERR_NS_DELETE_REQ_MISSING_FIELDS,
	/*
	 * This specifically is used by the namespace creation functions to
	 * indicate that a requested CSI is not supported. Currently this could
	 * be because the CSI is invalid, the device doesn't support it, the
	 * kernel doesn't support it, etc.
	 *
	 * The namespace attach variant is the same logic, just applied to the
	 * selector. Both of these are phrased differently as the set of fields
	 * that may or may not be valid for a given request of these types can
	 * vary based on the type.
	 */
	NVME_ERR_NS_CREATE_BAD_CSI,
	NVME_ERR_NS_ATTACH_BAD_SEL,
	/*
	 * Indicates that the NSID result value is not valid because we have not
	 * yet executed a namespace create request.
	 */
	NVME_ERR_NS_CREATE_NO_RESULTS,
	/*
	 * Indicates that the create namespace field is outside of the valid
	 * range for the field.
	 */
	NVME_ERR_NS_CREATE_NCAP_RANGE,
	NVME_ERR_NS_CREATE_NSZE_RANGE,
	NVME_ERR_NS_CREATE_NMIC_RANGE,
	NVME_ERR_NS_CREATE_FLBAS_RANGE,
	/*
	 * Indicates that the operation cannot proceed because the namespace is
	 * already attached or not attached to a controller respectively.
	 */
	NVME_ERR_NS_CTRL_ATTACHED,
	NVME_ERR_NS_CTRL_NOT_ATTACHED,
	/*
	 * Indicates that the namespace is unallocated and therefore the
	 * operation cannot proceed.
	 */
	NVME_ERR_NS_UNALLOC,
	/*
	 * Indicates that a library function was referring to a PCIe lane number
	 * that is not valid for the device.
	 */
	NVME_ERR_PCIE_LANE_RANGE,
	/*
	 * Indicates that a PCIe eye diagram buffer size was too small.
	 */
	NVME_ERR_PCIE_EYE_BUF_RANGE,
	/*
	 * The system does not allow this particular feature to be set by users.
	 */
	NVME_ERR_SET_FEAT_USER_UNSUP,
	/*
	 * Additional feature fields that are outside the range.
	 */
	NVME_ERR_FEAT_SAVE_RANGE,
	NVME_ERR_FEAT_CDW12_RANGE,
	NVME_ERR_FEAT_CDW13_RANGE,
	NVME_ERR_FEAT_CDW15_RANGE,
	NVME_ERR_FEAT_IMPACT_RANGE,
	/*
	 * Additional feature fields that are unusable on certain controllers.
	 */
	NVME_ERR_FEAT_SAVE_UNSUP,
	NVME_ERR_FEAT_CDW12_UNSUP,
	NVME_ERR_FEAT_CDW13_UNSUP,
	NVME_ERR_FEAT_CDW15_UNSUP,
	/*
	 * Additional feature fields that are not unusable in certain
	 * circumstances.
	 */
	NVME_ERR_FEAT_CDW12_UNUSE,
	NVME_ERR_FEAT_CDW13_UNUSE,
	NVME_ERR_FEAT_CDW15_UNUSE,
	/*
	 * Indicates that a set features request can't be executed because
	 * required fields have not been set.
	 */
	NVME_ERR_SET_FEAT_REQ_MISSING_FIELDS,
	/*
	 * Indicates that the vendor-specific library operation could not
	 * proceed because the underlying feature is not supported by the given
	 * device.
	 */
	NVME_ERR_VU_FEAT_UNSUP_BY_DEV,
	/*
	 * OCP Error Injection specific errors.
	 */
	NVME_ERR_OCP_ERRINJ_TYPE_RANGE,
	NVME_ERR_OCP_ERRINJ_NRTDE_RANGE,
	NVME_ERR_OCP_ERRINJ_LD_RANGE,
	NVME_ERR_OCP_ERRINJ_LD_UNSUP,
	NVME_ERR_OCP_ERRINJ_LD_UNUSE,
	NVME_ERR_OCP_ERRINJ_REQ_MISSING_FIELDS
} nvme_err_t;

/*
 * Errors used for the various information errors. This is shared between both
 * controller and namespace information structures.
 */
typedef enum {
	NVME_INFO_ERR_OK,
	/*
	 * Indicates that the item is not supported because this is the wrong
	 * controller transport. For example, asking about a PCI ID for
	 * something that is not PCI-based.
	 */
	NVME_INFO_ERR_TRANSPORT,
	/*
	 * Indicates that the item is not supported because the device version
	 * is too old to get this.
	 */
	NVME_INFO_ERR_VERSION,
	/*
	 * Indicates that we could not get certain information because the
	 * device does not support a given capability.
	 */
	NVME_INFO_ERR_MISSING_CAP,
	/*
	 * Indicates that the specified format value is unknown.
	 */
	NVME_INFO_ERR_BAD_LBA_FMT,
	/*
	 * These errors only occur during attempts to persist information and
	 * indicate challenges allocating memory or otherwise challenges with
	 * libnvpair.
	 */
	NVME_INFO_ERR_PERSIST_NVL,
	/*
	 * The first indicates that the index is invalid or if it is technically
	 * within the valid LBA format range, but there is no data size. The
	 * second indicates that we can't actually fully represent the data
	 * here. This happens because say the LBA size can't be represented by a
	 * uint64_t.
	 */
	NVME_INFO_ERR_BAD_FMT,
	NVME_INFO_ERR_BAD_FMT_DATA,
	/*
	 * Indicates that the information cannot be returned because the
	 * namespace's state does not allow us to answer this question. This may
	 * be because it's inactive as below or because blkdev is not attached.
	 */
	NVME_INFO_ERR_NS_INACTIVE,
	NVME_INFO_ERR_NS_NO_BLKDEV
} nvme_info_err_t;

typedef struct nvme nvme_t;
typedef struct nvme_ctrl nvme_ctrl_t;
typedef struct nvme_ctrl_iter nvme_ctrl_iter_t;
typedef struct nvme_ctrl_disc nvme_ctrl_disc_t;
typedef struct nvme_ctrl_info nvme_ctrl_info_t;
typedef struct nvme_ns nvme_ns_t;
typedef struct nvme_ns_iter nvme_ns_iter_t;
typedef struct nvme_ns_disc nvme_ns_disc_t;
typedef struct nvme_ns_info nvme_ns_info_t;
typedef struct nvme_nvm_lba_fmt nvme_nvm_lba_fmt_t;
typedef struct nvme_log_iter nvme_log_iter_t;
typedef struct nvme_log_disc nvme_log_disc_t;
typedef struct nvme_log_req nvme_log_req_t;
typedef struct nvme_id_req nvme_id_req_t;
typedef struct nvme_vuc_iter nvme_vuc_iter_t;
typedef struct nvme_vuc_disc nvme_vuc_disc_t;
typedef struct nvme_vuc_req nvme_vuc_req_t;
typedef struct nvme_fw_commit_req nvme_fw_commit_req_t;
typedef struct nvme_format_req nvme_format_req_t;
typedef struct nvme_feat_disc nvme_feat_disc_t;
typedef struct nvme_feat_iter nvme_feat_iter_t;
typedef struct nvme_get_feat_req nvme_get_feat_req_t;
typedef struct nvme_set_feat_req nvme_set_feat_req_t;
typedef struct nvme_ns_attach_req nvme_ns_attach_req_t;
typedef struct nvme_ns_create_req nvme_ns_create_req_t;
typedef struct nvme_ns_delete_req nvme_ns_delete_req_t;

/*
 * Vendor-specific forwards.
 */
typedef struct nvme_wdc_e6_req nvme_wdc_e6_req_t;
typedef struct nvme_ocp_errinj_req nvme_ocp_errinj_req_t;

extern nvme_t *nvme_init(void);
extern void nvme_fini(nvme_t *);

/*
 * Error information. Operations that take an nvme_t, always set error
 * information on the nvme_t. Operations that operate on a controller or are
 * related to a request object or iterator that starts from the controller
 * set error information on the nvme_ctrl_t.
 */
extern nvme_err_t nvme_err(nvme_t *);
extern int32_t nvme_syserr(nvme_t *);
extern const char *nvme_errmsg(nvme_t *);
extern size_t nvme_errlen(nvme_t *);
extern const char *nvme_errtostr(nvme_t *, nvme_err_t);

extern nvme_err_t nvme_ctrl_err(nvme_ctrl_t *);
extern int32_t nvme_ctrl_syserr(nvme_ctrl_t *);
extern const char *nvme_ctrl_errmsg(nvme_ctrl_t *);
extern size_t nvme_ctrl_errlen(nvme_ctrl_t *);
extern void nvme_ctrl_deverr(nvme_ctrl_t *, uint32_t *, uint32_t *);
extern const char *nvme_ctrl_errtostr(nvme_ctrl_t *, nvme_err_t);

/*
 * Translations for NVMe spec error constants. These end up taking the
 * nvme_ctrl_t so that way they can potentially translate vendor-specific errors
 * if they are defined. A NULL controller is allowed, which will skip all such
 * processing altogether. Both functions will always a return a string so there
 * is no need to check for NULL (though it may just be a variant of "unknown
 * ...").
 *
 * If NULL is passed for the controller in nvme_sctostr(), we will assume that
 * the controller's type is a traditional PCI I/O controller and not a fabric
 * based controller, which further changes the way that command-specific status
 * codes are interpreted. Due to the lack of support in the system for
 * different controller types, this function will always assume a PCI I/O
 * controller currently.
 */
extern const char *nvme_scttostr(nvme_ctrl_t *, uint32_t);
extern const char *nvme_sctostr(nvme_ctrl_t *, nvme_csi_t, uint32_t, uint32_t);

typedef enum nvme_iter {
	NVME_ITER_VALID,
	NVME_ITER_DONE,
	NVME_ITER_ERROR
} nvme_iter_t;

/*
 * NVMe Controller discovery.
 */
extern di_node_t nvme_ctrl_disc_devi(const nvme_ctrl_disc_t *);
extern di_minor_t nvme_ctrl_disc_minor(const nvme_ctrl_disc_t *);

extern bool nvme_ctrl_discover_init(nvme_t *, nvme_ctrl_iter_t **);
extern nvme_iter_t nvme_ctrl_discover_step(nvme_ctrl_iter_t *,
    const nvme_ctrl_disc_t **);
extern void nvme_ctrl_discover_fini(nvme_ctrl_iter_t *);

typedef bool (*nvme_ctrl_disc_f)(nvme_t *, const nvme_ctrl_disc_t *, void *);
extern bool nvme_ctrl_discover(nvme_t *, nvme_ctrl_disc_f, void *);

extern bool nvme_ctrl_init(nvme_t *, di_node_t, nvme_ctrl_t **);
extern bool nvme_ctrl_init_by_instance(nvme_t *, int32_t, nvme_ctrl_t **);
extern bool nvme_ctrl_devi(nvme_ctrl_t *, di_node_t *);
extern void nvme_ctrl_fini(nvme_ctrl_t *);

/*
 * Get information about a controller. This information about a controller is
 * separate from the lifetime of the controller itself. This is done to
 * facilitate the ability of saving and using this information on another
 * system and make the management a bit easier. Errors appear on this object and
 * not the nmve_t.
 */
extern bool nvme_ctrl_info_snap(nvme_ctrl_t *, nvme_ctrl_info_t **);
extern bool nvme_ctrl_info_restore(nvme_t *, nvlist_t *, nvme_ctrl_info_t **);
extern bool nvme_ctrl_info_persist(nvme_ctrl_info_t *, nvlist_t **);
extern void nvme_ctrl_info_free(nvme_ctrl_info_t *);

extern nvme_info_err_t nvme_ctrl_info_err(nvme_ctrl_info_t *);
extern int32_t nvme_ctrl_info_syserr(nvme_ctrl_info_t *);
extern const char *nvme_ctrl_info_errmsg(nvme_ctrl_info_t *);
extern size_t nvme_ctrl_info_errlen(nvme_ctrl_info_t *);
extern const char *nvme_ctrl_info_errtostr(nvme_ctrl_info_t *, nvme_info_err_t);

/*
 * Information about an NVMe controller. This information is a combination of
 * the identify data structure which can be retrieved directly by folks who
 * would prefer to use it. Common fields that are used in something like nvmeadm
 * or other utilities who would rather not need to know about the specifics of
 * the data structure or have to think about the version can use that instead.
 *
 * NVMe 2.x has kept the identify controller data structure backwards
 * compatible. If a future version were to invalidate that, then this could
 * possibly return NULL.
 */
extern uint16_t nvme_ctrl_info_vendor(nvme_ctrl_info_t *);
extern const nvme_identify_ctrl_t *nvme_ctrl_info_identify(nvme_ctrl_info_t *);
extern const nvme_version_t *nvme_ctrl_info_version(nvme_ctrl_info_t *);
extern const char *nvme_ctrl_info_model(nvme_ctrl_info_t *);
extern const char *nvme_ctrl_info_serial(nvme_ctrl_info_t *);
extern uint32_t nvme_ctrl_info_fwgran(nvme_ctrl_info_t *);
extern const char *nvme_ctrl_info_fwrev(nvme_ctrl_info_t *);
extern uint32_t nvme_ctrl_info_nns(nvme_ctrl_info_t *);

typedef enum {
	NVME_CTRL_TRANSPORT_PCI,
	NVME_CTRL_TRANSPORT_TCP,
	NVME_CTRL_TRANSPORT_RDMA,
} nvme_ctrl_transport_t;

typedef enum {
	NVME_CTRL_TYPE_UNKNOWN,
	NVME_CTRL_TYPE_IO,
	NVME_CTRL_TYPE_ADMIN,
	NVME_CTRL_TYPE_DISCOVERY,
} nvme_ctrl_type_t;

/*
 * Controller types were explicitly added in the NVMe 1.4 specification. Prior
 * to that all controllers were required to support issuing I/O, hence we return
 * them as NVME_CTRL_TYPE_IO, even though this isn't quite by the spec. In 1.4
 * this was added to the identify controller information. The 'UNKNOWN' type is
 * for cases where we don't recognize the value based upon the standard.
 */
extern nvme_ctrl_type_t nvme_ctrl_info_type(nvme_ctrl_info_t *);
extern nvme_ctrl_transport_t nvme_ctrl_info_transport(nvme_ctrl_info_t *);

/*
 * The following pieces of information are specific to PCI NVMe controllers and
 * are not from the common identify controller data structure. As such they are
 * fallible. The first group come from configuration space while the others are
 * information that comes from the actual controller capability registers.
 */
extern bool nvme_ctrl_info_pci_vid(nvme_ctrl_info_t *, uint16_t *);
extern bool nvme_ctrl_info_pci_did(nvme_ctrl_info_t *, uint16_t *);
extern bool nvme_ctrl_info_pci_rev(nvme_ctrl_info_t *, uint8_t *);
extern bool nvme_ctrl_info_pci_subvid(nvme_ctrl_info_t *, uint16_t *);
extern bool nvme_ctrl_info_pci_subsys(nvme_ctrl_info_t *, uint16_t *);

extern bool nvme_ctrl_info_pci_mps_min(nvme_ctrl_info_t *, uint32_t *);
extern bool nvme_ctrl_info_pci_mps_max(nvme_ctrl_info_t *, uint32_t *);

extern bool nvme_ctrl_info_pci_nintrs(nvme_ctrl_info_t *, uint32_t *);

/*
 * These three items are only present if the device supports Namespace
 * Management.
 */
extern bool nvme_ctrl_info_cap(nvme_ctrl_info_t *, nvme_uint128_t *);
extern bool nvme_ctrl_info_unalloc_cap(nvme_ctrl_info_t *, nvme_uint128_t *);
extern bool nvme_ctrl_info_common_ns(nvme_ctrl_info_t *,
    const nvme_identify_nsid_t **);

/*
 * The following information is specific to the NVM command set for controllers.
 */
extern uint32_t nvme_ctrl_info_nformats(nvme_ctrl_info_t *);
extern bool nvme_ctrl_info_format(nvme_ctrl_info_t *, uint32_t,
    const nvme_nvm_lba_fmt_t **);
extern uint32_t nvme_nvm_lba_fmt_id(const nvme_nvm_lba_fmt_t *);
extern uint32_t nvme_nvm_lba_fmt_meta_size(const nvme_nvm_lba_fmt_t *);
extern uint64_t nvme_nvm_lba_fmt_data_size(const nvme_nvm_lba_fmt_t *);
extern uint32_t nvme_nvm_lba_fmt_rel_perf(const nvme_nvm_lba_fmt_t *);

/*
 * Identify Operations
 *
 * The basic controller and namespace identify operations are a part of the
 * controller and namespace snapshot facilities. These functions are designed to
 * help enumerate and iterate lists of active and inactive namespaces,
 * controllers, and related. The initial interface is a basic form that allows
 * folks to create a request based on one that the library knows about as the
 * kernel doesn't allow unknown requests.
 *
 * Eventually, when the kernel allows for arbitrary identify commands to be
 * issued we can add an nvme_id_req_init() and the ability to set the CSI and
 * CNS.
 */
extern bool nvme_id_req_init_by_cns(nvme_ctrl_t *, nvme_csi_t, uint32_t,
    nvme_id_req_t **);
extern void nvme_id_req_fini(nvme_id_req_t *);

extern bool nvme_id_req_set_nsid(nvme_id_req_t *, uint32_t);
extern bool nvme_id_req_set_ctrlid(nvme_id_req_t *, uint32_t);
extern bool nvme_id_req_set_output(nvme_id_req_t *, void *, size_t);
extern bool nvme_id_req_clear_output(nvme_id_req_t *);
extern bool nvme_id_req_exec(nvme_id_req_t *);

/*
 * NVMe Namespace Discovery
 *
 * Namespaces come in various states. While the controller has a list of
 * namespace IDs. The following enumeration describes namespace information with
 * increasing specificity.
 */
typedef enum {
	/*
	 * This returns all namespaces that are present on the device. This
	 * includes ones that may be ignored by the kernel or more.
	 */
	NVME_NS_DISC_F_ALL = 0,
	/*
	 * Only return namespaces that the controller considers to be allocated.
	 */
	NVME_NS_DISC_F_ALLOCATED,
	/*
	 * Only return namespaces that are active. If the controller does not
	 * support namespace management then all namespaces are considered
	 * active.
	 */
	NVME_NS_DISC_F_ACTIVE,
	/*
	 * The kernel has a notion of a namespace is ignored or not. In general,
	 * this is a subset of active namespaces that can actually be supported.
	 * They may or may not have a blkdev instance attached.
	 */
	NVME_NS_DISC_F_NOT_IGNORED,
	/*
	 * Only return namespaces that have blkdev actively attached. In other
	 * words these are disks that the OS can use.
	 */
	NVME_NS_DISC_F_BLKDEV
} nvme_ns_disc_level_t;

typedef enum nvme_ns_disc_flags {
	NVME_NS_DISC_F_EUI64_VALID	= 1 << 0,
	NVME_NS_DISC_F_NGUID_VALID	= 1 << 1
} nvme_ns_disc_flags_t;

extern uint32_t nvme_ns_disc_nsid(const nvme_ns_disc_t *);
extern nvme_ns_disc_level_t nvme_ns_disc_level(const nvme_ns_disc_t *);
extern nvme_ns_disc_flags_t nvme_ns_disc_flags(const nvme_ns_disc_t *);
extern const uint8_t *nvme_ns_disc_eui64(const nvme_ns_disc_t *);
extern const uint8_t *nvme_ns_disc_nguid(const nvme_ns_disc_t *);

extern bool nvme_ns_discover_init(nvme_ctrl_t *, nvme_ns_disc_level_t,
    nvme_ns_iter_t **);
extern nvme_iter_t nvme_ns_discover_step(nvme_ns_iter_t *,
    const nvme_ns_disc_t **);
extern void nvme_ns_discover_fini(nvme_ns_iter_t *);

typedef bool (*nvme_ns_disc_f)(nvme_ctrl_t *, const nvme_ns_disc_t *, void *);
extern bool nvme_ns_discover(nvme_ctrl_t *, nvme_ns_disc_level_t,
    nvme_ns_disc_f, void *);

extern bool nvme_ns_init(nvme_ctrl_t *, uint32_t, nvme_ns_t **);
extern bool nvme_ns_init_by_name(nvme_ctrl_t *, const char *, nvme_ns_t **);
extern void nvme_ns_fini(nvme_ns_t *);

/*
 * This is a convenience routine for opening up an NVMe controller and/or
 * namespace. Many utilities refer to things as <controller>/<namespace>. As
 * such, this will parse that apart. If no namespace is specified, it will be
 * left as NULL. If the specified controller or namespace cannot be found, then
 * the function will fail.
 *
 * Currently the only supported controller name is nvmeX, though we should
 * support GUIDs at some point. The namespace id, EUI64, and NGUID are all
 * supported for the namespace.
 */
extern bool nvme_ctrl_ns_init(nvme_t *, const char *, nvme_ctrl_t **,
    nvme_ns_t **);

/*
 * NVMe Namespace Information.
 *
 * Namespace information is broken into a few groups. There is basic information
 * about the LBA formats and capacities (which are provided in block sizes).
 * There is information about the IDs. Note the NGUID/EUI64 are fallible
 * because they are optional.
 */
extern bool nvme_ns_info_snap(nvme_ns_t *, nvme_ns_info_t **);
extern bool nvme_ctrl_ns_info_snap(nvme_ctrl_t *, uint32_t, nvme_ns_info_t **);
extern void nvme_ns_info_free(nvme_ns_info_t *);

extern nvme_info_err_t nvme_ns_info_err(nvme_ns_info_t *);
extern int32_t nvme_ns_info_syserr(nvme_ns_info_t *);
extern const char *nvme_ns_info_errmsg(nvme_ns_info_t *);
extern size_t nvme_ns_info_errlen(nvme_ns_info_t *);
extern const char *nvme_ns_info_errtostr(nvme_ns_info_t *, nvme_info_err_t);

extern uint32_t nvme_ns_info_nsid(nvme_ns_info_t *);
extern nvme_ns_disc_level_t nvme_ns_info_level(nvme_ns_info_t *);
extern const nvme_identify_nsid_t *nvme_ns_info_identify(nvme_ns_info_t *);

extern bool nvme_ns_info_nguid(nvme_ns_info_t *, uint8_t [16]);
extern bool nvme_ns_info_eui64(nvme_ns_info_t *, uint8_t [8]);

extern bool nvme_ns_info_size(nvme_ns_info_t *, uint64_t *);
extern bool nvme_ns_info_cap(nvme_ns_info_t *, uint64_t *);
extern bool nvme_ns_info_use(nvme_ns_info_t *, uint64_t *);

extern bool nvme_ns_info_curformat(nvme_ns_info_t *,
    const nvme_nvm_lba_fmt_t **);
extern bool nvme_ns_info_nformats(nvme_ns_info_t *, uint32_t *);
extern bool nvme_ns_info_format(nvme_ns_info_t *, uint32_t,
    const nvme_nvm_lba_fmt_t **);

extern bool nvme_ns_info_bd_addr(nvme_ns_info_t *, const char **);

/*
 * Controller and Namespace Locking
 *
 * A given controller can be active by several different parallel consumers.
 */
extern bool nvme_ctrl_lock(nvme_ctrl_t *, nvme_lock_level_t, nvme_lock_flags_t);
extern void nvme_ctrl_unlock(nvme_ctrl_t *);
extern bool nvme_ns_lock(nvme_ns_t *, nvme_lock_level_t, nvme_lock_flags_t);
extern void nvme_ns_unlock(nvme_ns_t *);

/*
 * Namespace Attach and Detach
 *
 * These operations are used to attach and detach a blkdev device from a given
 * namespace.
 */
extern bool nvme_ns_bd_attach(nvme_ns_t *);
extern bool nvme_ns_bd_detach(nvme_ns_t *);

/*
 * NVMe Log Page Discovery
 *
 * NVMe Log Pages provide some complications around discovery. There are
 * standard log pages, which are either mandatory or optional. There are also
 * vendor-specific log pages that we may know about. While NVMe 2.0 introduced a
 * way to list all of the supported log pages a device implements, that is not
 * true for most devices. Pre 2.x devices sometimes have a vendor-specific way
 * to list all the available logs. The NVMe 2.0 based mechanism also does not
 * provide a means of getting additional information such as required fields, so
 * we'll end up always needing the additional information this interface
 * provides.
 *
 * The log page discovery functions here allow a caller to just ask for all the
 * known IDs that exist for something. The discovery callback will fire once for
 * each log page that may be implemented. Log pages we know that aren't
 * implemented are never called back for.
 */
extern const char *nvme_log_disc_name(const nvme_log_disc_t *);
extern const char *nvme_log_disc_desc(const nvme_log_disc_t *);
extern const char *const *nvme_log_disc_aliases(const nvme_log_disc_t *);
extern size_t nvme_log_disc_naliases(const nvme_log_disc_t *);
extern nvme_csi_t nvme_log_disc_csi(const nvme_log_disc_t *);
extern uint32_t nvme_log_disc_lid(const nvme_log_disc_t *);
extern nvme_log_disc_kind_t nvme_log_disc_kind(const nvme_log_disc_t *);
extern nvme_log_disc_source_t nvme_log_disc_sources(const nvme_log_disc_t *);
extern nvme_log_disc_fields_t nvme_log_disc_fields(const nvme_log_disc_t *);
extern nvme_log_disc_scope_t nvme_log_disc_scopes(const nvme_log_disc_t *);
extern bool nvme_log_disc_impl(const nvme_log_disc_t *);

typedef enum {
	/*
	 * This indicates that the size of a log page is unknown. Instead, we
	 * will return a size that is reasonable enough to hopefully cover most
	 * things.
	 */
	NVME_LOG_SIZE_K_UNKNOWN	= 0,
	/*
	 * This indicates that there is a known fixed size for the log page and
	 * we have indicated what that is.
	 */
	NVME_LOG_SIZE_K_FIXED,
	/*
	 * This indicates that the total log size is variable; however, it can
	 * be determined by reading the specified following number of bytes.
	 * Once that number of bytes has been read, that can be passed to the
	 * nvme_log_disc_cal_size() function, which will attempt to determine
	 * the actual number of bytes based on the returned data.
	 */
	NVME_LOG_SIZE_K_VAR
} nvme_log_size_kind_t;
extern nvme_log_size_kind_t nvme_log_disc_size(const nvme_log_disc_t *,
    uint64_t *);
extern bool nvme_log_disc_calc_size(const nvme_log_disc_t *, uint64_t *,
    const void *, size_t);

/*
 * Duplicate and free log discovery information. The free function should only
 * be used when it is explicitly duplicated or obtained through something like
 * nvme_log_req_init_by_name(). It must not be used on the constant data
 * provided as part of the nvme_log_discover family of functions.
 */
extern bool nvme_log_disc_dup(nvme_ctrl_t *, const nvme_log_disc_t *,
    nvme_log_disc_t **);
extern void nvme_log_disc_free(nvme_log_disc_t *);

extern bool nvme_log_discover_init(nvme_ctrl_t *, nvme_log_disc_scope_t,
    uint32_t, nvme_log_iter_t **);
extern nvme_iter_t nvme_log_discover_step(nvme_log_iter_t *,
    const nvme_log_disc_t **);
extern void nvme_log_discover_fini(nvme_log_iter_t *);

typedef bool (*nvme_log_disc_f)(nvme_ctrl_t *, const nvme_log_disc_t *,
    void *);
extern bool nvme_log_discover(nvme_ctrl_t *, nvme_log_disc_scope_t,
    uint32_t, nvme_log_disc_f, void *);

/*
 * One does not simply request a log page. There are a lot of parameters that
 * are used to get a log page and these have been evolving over time. For
 * example, the size has changed between 1.2 and 1.3, NVMe 1.0 never had UUIDs,
 * LSP, LSIs, there are optional features around supporting offsets, etc.
 *
 * To deal with the fact that this keeps changing and an attempt to create a
 * stable ABI, we instead have an opaque structure that allows various fields to
 * be set and changed. To speed this up, this can be bootstrapped from the
 * discovery information directly or indirectly by the log page short name.
 *
 * Once all of the appropriate fields are set on a log page request then it can
 * be executed. A given request may be executed multiple times.
 *
 * When creating a raw log request, it will be up to the caller to fill in and
 * set up the log ID (lid) and the output information. It is assumed that by
 * default a log request should specify the NVM CSI. When using
 * nvme_log_req_init_by_disc(), the log ID and command set will be filled in
 * automatically. The discovery flags will indicate what other fields are still
 * required.
 */
extern bool nvme_log_req_init(nvme_ctrl_t *, nvme_log_req_t **);
extern bool nvme_log_req_init_by_disc(nvme_ctrl_t *, const nvme_log_disc_t *,
    nvme_log_req_t **);
extern bool nvme_log_req_init_by_name(nvme_ctrl_t *, const char *,
    uint32_t, nvme_log_disc_t **, nvme_log_req_t **);
extern void nvme_log_req_fini(nvme_log_req_t *);

extern bool nvme_log_req_set_lid(nvme_log_req_t *, uint32_t);
extern bool nvme_log_req_set_lsp(nvme_log_req_t *, uint32_t);
extern bool nvme_log_req_set_lsi(nvme_log_req_t *, uint32_t);
extern bool nvme_log_req_set_uuid(nvme_log_req_t *, uint32_t);
extern bool nvme_log_req_set_nsid(nvme_log_req_t *, uint32_t);
extern bool nvme_log_req_set_output(nvme_log_req_t *, void *, size_t);
extern bool nvme_log_req_clear_output(nvme_log_req_t *);
extern bool nvme_log_req_set_offset(nvme_log_req_t *, uint64_t);
extern bool nvme_log_req_set_rae(nvme_log_req_t *, bool);
extern bool nvme_log_req_set_csi(nvme_log_req_t *, nvme_csi_t);
extern bool nvme_log_req_exec(nvme_log_req_t *);

/*
 * Feature Discovery and Management
 *
 * Features are parts of the NVMe specification that can both be retrieved and
 * set. Features are often either a uint32_t or a larger data payload. In
 * addition, there are additional modifiers that are required to select
 * information about features. For example, when getting or setting a
 * temperature threshold feature, a temperature sensor ID is required. Much like
 * with log pages this has changed and added new arguments to getting and
 * setting a feature at the command level and the individual features have grown
 * support for more configuration as well.
 *
 * We currently provide information in discovery to determine what is required
 * to get a feature as well as the ability to fast path that. Currently we
 * provide the raw feature getting API that works at the low level. There is no
 * higher level API for specific features. This works okay for an nvmeadm(8)
 * style implementation, but we should consider adding more here based on
 * feedback from consumers.
 */
extern const char *nvme_feat_disc_short(const nvme_feat_disc_t *);
extern const char *nvme_feat_disc_spec(const nvme_feat_disc_t *);
extern uint32_t nvme_feat_disc_fid(const nvme_feat_disc_t *);
extern nvme_feat_scope_t nvme_feat_disc_scope(const nvme_feat_disc_t *);
extern nvme_feat_kind_t nvme_feat_disc_kind(const nvme_feat_disc_t *);
extern nvme_feat_csi_t nvme_feat_disc_csi(const nvme_feat_disc_t *);
extern nvme_feat_flags_t nvme_feat_disc_flags(const nvme_feat_disc_t *);
extern nvme_get_feat_fields_t nvme_feat_disc_fields_get(
    const nvme_feat_disc_t *);
extern nvme_set_feat_fields_t nvme_feat_disc_fields_set(
    const nvme_feat_disc_t *);
extern nvme_feat_output_t nvme_feat_disc_output_get(const nvme_feat_disc_t *);
extern nvme_feat_output_t nvme_feat_disc_output_set(const nvme_feat_disc_t *);
extern uint64_t nvme_feat_disc_data_size(const nvme_feat_disc_t *);
extern nvme_feat_impl_t nvme_feat_disc_impl(const nvme_feat_disc_t *);
extern nvme_disc_impact_t nvme_feat_disc_impact_set(const nvme_feat_disc_t *);

extern bool nvme_feat_discover_init(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t,
    nvme_feat_iter_t **);
extern nvme_iter_t nvme_feat_discover_step(nvme_feat_iter_t *,
    const nvme_feat_disc_t **);
extern void nvme_feat_discover_fini(nvme_feat_iter_t *);

extern bool nvme_feat_disc_dup(nvme_ctrl_t *, const nvme_feat_disc_t *,
    nvme_feat_disc_t **);
extern void nvme_feat_disc_free(nvme_feat_disc_t *);

typedef bool (*nvme_feat_disc_f)(nvme_ctrl_t *, const nvme_feat_disc_t *,
    void *);
extern bool nvme_feat_discover(nvme_ctrl_t *, nvme_feat_scope_t, uint32_t,
    nvme_feat_disc_f, void *);

/*
 * Get Feature Request
 *
 * The get feature request allows one to build up a get feature command. It is
 * recommended to initiate a request based on discovery information or a
 * feature's name. That will allow the system to perform better validation, know
 * what fields are required or not, and pre-set parameters like the feature id
 * (fid). By default, a get features request will always ask for the current
 * value. Unless you want a saved or default value (and the controller is new
 * enough), then there is no need to set the selector. The only required field
 * when not using discovery information is the fid.
 */
extern bool nvme_get_feat_req_init(nvme_ctrl_t *, nvme_get_feat_req_t **);
extern bool nvme_get_feat_req_init_by_disc(nvme_ctrl_t *,
    const nvme_feat_disc_t *, nvme_get_feat_req_t **);
extern bool nvme_get_feat_req_init_by_name(nvme_ctrl_t *, const char *,
    uint32_t, nvme_feat_disc_t **, nvme_get_feat_req_t **);
extern void nvme_get_feat_req_fini(nvme_get_feat_req_t *);

extern bool nvme_get_feat_req_set_fid(nvme_get_feat_req_t *, uint32_t);
extern bool nvme_get_feat_req_set_sel(nvme_get_feat_req_t *, uint32_t);
extern bool nvme_get_feat_req_set_nsid(nvme_get_feat_req_t *, uint32_t);
extern bool nvme_get_feat_req_set_cdw11(nvme_get_feat_req_t *, uint32_t);
extern bool nvme_get_feat_req_set_output(nvme_get_feat_req_t *, void *, size_t);
extern bool nvme_get_feat_req_clear_output(nvme_get_feat_req_t *);
extern bool nvme_get_feat_req_exec(nvme_get_feat_req_t *);
extern bool nvme_get_feat_req_get_cdw0(nvme_get_feat_req_t *, uint32_t *);

/*
 * Set Feature Request
 *
 * This allows one to set the value of a feature in a similar fashion to get
 * feature. Currently only vendor-specific features are supported by the kernel.
 * By default, a set feature will not save its value. The set of required fields
 * and the impact will be determined automatically if creating a request from a
 * discovery object. Otherwise, this must be specified.
 */
extern bool nvme_set_feat_req_init(nvme_ctrl_t *, nvme_set_feat_req_t **);
extern bool nvme_set_feat_req_init_by_disc(nvme_ctrl_t *,
    const nvme_feat_disc_t *, nvme_set_feat_req_t **);
extern bool nvme_set_feat_req_init_by_name(nvme_ctrl_t *, const char *,
    uint32_t, nvme_feat_disc_t **, nvme_set_feat_req_t **);
extern void nvme_set_feat_req_fini(nvme_set_feat_req_t *);

extern bool nvme_set_feat_req_set_fid(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_save(nvme_set_feat_req_t *, bool);
extern bool nvme_set_feat_req_set_nsid(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_cdw11(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_cdw12(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_cdw13(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_cdw15(nvme_set_feat_req_t *, uint32_t);
extern bool nvme_set_feat_req_set_input(nvme_set_feat_req_t *, const void *,
    size_t);
extern bool nvme_set_feat_req_clear_input(nvme_set_feat_req_t *);
extern bool nvme_set_feat_req_set_impact(nvme_set_feat_req_t *,
    nvme_disc_impact_t);
extern bool nvme_set_feat_req_exec(nvme_set_feat_req_t *);
extern bool nvme_set_feat_req_get_cdw0(nvme_set_feat_req_t *, uint32_t *);

/*
 * NVMe Vendor Unique Command Discovery and Execution
 *
 * There is a standard form of vendor unique commands which are indicated in the
 * identify controller datasheet. The first set of pieces here allows one to
 * discover which vendor-specific commands are supported by a device that are
 * known to the library. These generally have their own implementation
 * function; however, that isn't really linked to from the discovery function.
 * Tied into this is also asking if a given controller supports a given command
 * and getting information about it.
 *
 * The second set of functions here is all around allocating a vendor unique
 * command then executing it. Currently only admin commands are supported
 * through this interface.
 */
extern bool nvme_vuc_discover_init(nvme_ctrl_t *, uint32_t,
    nvme_vuc_iter_t **);
extern nvme_iter_t nvme_vuc_discover_step(nvme_vuc_iter_t *,
    const nvme_vuc_disc_t **);
extern void nvme_vuc_discover_fini(nvme_vuc_iter_t *);

typedef bool (*nvme_vuc_disc_f)(nvme_ctrl_t *, const nvme_vuc_disc_t *, void *);
extern bool nvme_vuc_discover(nvme_ctrl_t *, uint32_t, nvme_vuc_disc_f, void *);

extern bool nvme_vuc_discover_by_name(nvme_ctrl_t *, const char *, uint32_t,
    nvme_vuc_disc_t **);
extern bool nvme_vuc_disc_dup(nvme_ctrl_t *, const nvme_vuc_disc_t *,
    nvme_vuc_disc_t **);
extern void nvme_vuc_disc_free(nvme_vuc_disc_t *);

extern const char *nvme_vuc_disc_name(const nvme_vuc_disc_t *);
extern const char *nvme_vuc_disc_desc(const nvme_vuc_disc_t *);
extern uint32_t nvme_vuc_disc_opcode(const nvme_vuc_disc_t *);
extern nvme_disc_impact_t nvme_vuc_disc_impact(const nvme_vuc_disc_t *);

typedef enum {
	NVME_VUC_DISC_IO_NONE	= 0,
	/*
	 * Indicates that this command needs additional data provided as input
	 * to the command.
	 */
	NVME_VUC_DISC_IO_INPUT	= 1 << 0,
	/*
	 * Indicates that this command writes output back to the host from the
	 * controller and a data buffer is required.
	 */
	NVME_VUC_DISC_IO_OUTPUT	= 1 << 1
} nvme_vuc_disc_io_t;
extern nvme_vuc_disc_io_t nvme_vuc_disc_dt(const nvme_vuc_disc_t *);

typedef enum {
	/*
	 * Indicates that the library has no opinion on whether a lock should be
	 * taken or not.
	 */
	NVME_VUC_DISC_LOCK_NONE	= 0,
	/*
	 * Indicates that a controller or namespace level read lock is
	 * recommended for this operation.
	 */
	NVME_VUC_DISC_LOCK_READ,
	/*
	 * Indicates that a controller or namespace level write lock is
	 * recommended for this operation.
	 */
	NVME_VUC_DISC_LOCK_WRITE
} nvme_vuc_disc_lock_t;
extern nvme_vuc_disc_lock_t nvme_vuc_disc_lock(const nvme_vuc_disc_t *);

extern bool nvme_vuc_req_init(nvme_ctrl_t *, nvme_vuc_req_t **);
extern void nvme_vuc_req_fini(nvme_vuc_req_t *);

extern bool nvme_vuc_req_set_opcode(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_nsid(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_timeout(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_cdw12(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_cdw13(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_cdw14(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_cdw15(nvme_vuc_req_t *, uint32_t);
extern bool nvme_vuc_req_set_impact(nvme_vuc_req_t *, nvme_disc_impact_t);
extern bool nvme_vuc_req_set_input(nvme_vuc_req_t *, const void *, size_t);
extern bool nvme_vuc_req_set_output(nvme_vuc_req_t *, void *, size_t);
extern bool nvme_vuc_req_clear_output(nvme_vuc_req_t *);

/*
 * Execute a request. After a request is executed, the status information
 * becomes available. A call to exec will invalidate any prior results. If the
 * request does not make it to the controller for some reason or some other
 * error occurs, then getting the results will fail. If the controller fails the
 * command, that will set the NVME_ERR_CONTROLLER error and the corresponding
 * SCT/SC values can be retrieved from the controller's error information for
 * inspection.
 */
extern bool nvme_vuc_req_exec(nvme_vuc_req_t *);
extern bool nvme_vuc_req_get_cdw0(nvme_vuc_req_t *, uint32_t *);

/*
 * Firmware Download and Commit (Activation)
 *
 * NVMe devices have a buffer that is used to receive a firmware download. This
 * can then be committed into a firmware slot or a boot slot through the commit
 * action. The commit action may also change which firmware slot is activated on
 * the next boot at the same time as installing an image or a commit can be used
 * to just change the active image. The optional bootloader features will have a
 * similar shape as to the firmware commit routines, but ultimately be different
 * ones to make it more obvious what is being done.
 *
 * The firmware download command has to date not really changed through the NVMe
 * 1.x and 2.0 standards, which is why it is not broken into a request and
 * execution format like others at this time.
 *
 * Firmware must be loaded with a particular granularity and if blocks do not
 * conform to that, nvme_fw_load() will return an error.
 */
extern bool nvme_fw_load(nvme_ctrl_t *, const void *, size_t, uint64_t);

extern bool nvme_fw_commit_req_init(nvme_ctrl_t *, nvme_fw_commit_req_t **);
extern void nvme_fw_commit_req_fini(nvme_fw_commit_req_t *);
extern bool nvme_fw_commit_req_set_slot(nvme_fw_commit_req_t *, uint32_t);
extern bool nvme_fw_commit_req_set_action(nvme_fw_commit_req_t *, uint32_t);
extern bool nvme_fw_commit_req_exec(nvme_fw_commit_req_t *);

/*
 * Format NVM
 *
 * This is used to erase and reformat either all namespaces or a specific one.
 * We currently do not support setting metadata or protection information for
 * namespaces in the kernel which is why this is not present in the library.
 */
extern bool nvme_format_req_init(nvme_ctrl_t *, nvme_format_req_t **);
extern void nvme_format_req_fini(nvme_format_req_t *);
extern bool nvme_format_req_set_lbaf(nvme_format_req_t *, uint32_t);
extern bool nvme_format_req_set_ses(nvme_format_req_t *, uint32_t);
extern bool nvme_format_req_set_nsid(nvme_format_req_t *, uint32_t);
extern bool nvme_format_req_exec(nvme_format_req_t *);

/*
 * NVMe Namespace Attach
 *
 * This is used to attach or detach a collection of controllers to a namespace.
 * Currently the only way to specify a controller is to use the self flag on
 * here. In the future, we will likely have support for listing the explicit
 * controllers to specify here.
 */
extern bool nvme_ns_attach_req_init_by_sel(nvme_ctrl_t *, uint32_t,
    nvme_ns_attach_req_t **);
extern void nvme_ns_attach_req_fini(nvme_ns_attach_req_t *);
extern bool nvme_ns_attach_req_set_nsid(nvme_ns_attach_req_t *, uint32_t);
extern bool nvme_ns_attach_req_set_ctrlid_self(nvme_ns_attach_req_t *);
extern bool nvme_ns_attach_req_exec(nvme_ns_attach_req_t *);

/*
 * NVMe Namesapce Create and Delete
 */
extern bool nvme_ns_create_req_init_by_csi(nvme_ctrl_t *, nvme_csi_t,
    nvme_ns_create_req_t **);
extern void nvme_ns_create_req_fini(nvme_ns_create_req_t *);
extern bool nvme_ns_create_req_set_flbas(nvme_ns_create_req_t *, uint32_t);
extern bool nvme_ns_create_req_set_nsze(nvme_ns_create_req_t *, uint64_t);
extern bool nvme_ns_create_req_set_ncap(nvme_ns_create_req_t *, uint64_t);
extern bool nvme_ns_create_req_set_nmic(nvme_ns_create_req_t *, uint32_t);
extern bool nvme_ns_create_req_exec(nvme_ns_create_req_t *);
extern bool nvme_ns_create_req_get_nsid(nvme_ns_create_req_t *, uint32_t *);

extern bool nvme_ns_delete_req_init(nvme_ctrl_t *, nvme_ns_delete_req_t **);
extern void nvme_ns_delete_req_fini(nvme_ns_delete_req_t *);
extern bool nvme_ns_delete_req_set_nsid(nvme_ns_delete_req_t *, uint32_t);
extern bool nvme_ns_delete_req_exec(nvme_ns_delete_req_t *);

/*
 * Vendor-specific interfaces.
 */

/*
 * WDC resizing functions. These are interfaces supported in the SN840, SN650,
 * SN655, etc. These end up allowing one to adjust the overprovisioning ratio,
 * though this ends up reformatting the device and all namespaces in the
 * process. The values passed and returned are in GB (not GiB).
 */
extern bool nvme_wdc_resize_set(nvme_ctrl_t *, uint32_t);
extern bool nvme_wdc_resize_get(nvme_ctrl_t *, uint32_t *);

/*
 * WDC e6 diagnostic log. The e6 log is a WDC-specific diagnostic log which
 * contains information about the device itself.
 */
extern bool nvme_wdc_e6_req_init(nvme_ctrl_t *, nvme_wdc_e6_req_t **);
extern void nvme_wdc_e6_req_fini(nvme_wdc_e6_req_t *);
extern bool nvme_wdc_e6_req_set_offset(nvme_wdc_e6_req_t *, uint64_t);
extern bool nvme_wdc_e6_req_set_output(nvme_wdc_e6_req_t *, void *,
    size_t);
extern bool nvme_wdc_e6_req_clear_output(nvme_wdc_e6_req_t *);
extern bool nvme_wdc_e6_req_exec(nvme_wdc_e6_req_t *);

/*
 * WDC assert injection and removal.
 */
extern bool nvme_wdc_assert_clear(nvme_ctrl_t *);
extern bool nvme_wdc_assert_inject(nvme_ctrl_t *);

/*
 * Sandisk commands to get PCI eye diagrams and the hardware revision.
 */
extern bool nvme_sndk_pci_eye(nvme_ctrl_t *, uint8_t, void *, size_t);
extern bool nvme_sndk_hw_rev(nvme_ctrl_t *, uint8_t *, uint8_t *);

/*
 * OCP Error Injection.
 */
extern bool nvme_ocp_errinj_req_init(nvme_ctrl_t *, nvme_ocp_errinj_req_t **);
extern void nvme_ocp_errinj_req_fini(nvme_ocp_errinj_req_t *);
extern bool nvme_ocp_errinj_req_set_type(nvme_ocp_errinj_req_t *, uint32_t);
extern bool nvme_ocp_errinj_req_set_nrtde(nvme_ocp_errinj_req_t *, uint32_t);
extern bool nvme_ocp_errinj_req_set_ld(nvme_ocp_errinj_req_t *, uint32_t);
extern bool nvme_ocp_errinj_req_exec(nvme_ocp_errinj_req_t *);

extern bool nvme_ocp_errinj_clear(nvme_ctrl_t *);

#ifdef __cplusplus
}
#endif

#endif /* _LIBNVME_H */