From e503d1ea94d48b36a90975b0326ad7afc7eb7cf5 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:06 +0200 Subject: [PATCH 01/10] nvme-types: add spec reference to DOC section Add references on which version of the spec the header is based on. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/mi-types.h | 35 +++++++++++++++++++++++++++ libnvme/src/nvme/nbft-types.h | 18 ++++++++++++-- libnvme/src/nvme/nvme-types-base.h | 13 ++++++++++ libnvme/src/nvme/nvme-types-fabrics.h | 15 ++++++++++++ libnvme/src/nvme/nvme-types-mi.h | 13 +++++++++- libnvme/src/nvme/nvme-types-nvm.h | 13 ++++++++++ libnvme/src/nvme/nvme-types-zns.h | 3 +++ 7 files changed, 107 insertions(+), 3 deletions(-) diff --git a/libnvme/src/nvme/mi-types.h b/libnvme/src/nvme/mi-types.h index 30b98fa1f7..c223c9140b 100644 --- a/libnvme/src/nvme/mi-types.h +++ b/libnvme/src/nvme/mi-types.h @@ -12,6 +12,41 @@ #include #include +/** + * DOC: mi-types.h - NVMe-MI wire protocol and messaging types + * + * This file defines the wire protocol types for NVMe Management Interface + * (NVMe-MI) messaging and transport layer. These are the low-level message + * structures used for MCTP/MI communication between a host and NVMe devices. + * + * Scope + * ===== + * - MCTP message framing and headers + * - MI request/response message structures + * - MI command opcodes and protocol definitions + * - Admin command protocol over MI transport + * - Control primitives for MI communication + * - Asynchronous Event Messages (AEM) + * - Low-level transport and protocol details + * + * This file is primarily used by the libnvme-mi library implementation and + * is **internal to the MI transport layer**. + * + * Separation from nvme-types-mi.h + * ================================ + * This file is **separate** from nvme-types-mi.h, which serves a different purpose: + * + * - **mi-types.h** (this file): Wire protocol, messaging, transport layer + * - Used by: mi.h (MI library internals) + * - Focus: How messages are sent/received over MCTP + * - Analogy: TCP/IP headers and framing + * + * - **nvme-types-mi.h**: NVMe-MI data structures from the MI specification + * - Used by: nvme-types.h (public API), applications + * - Focus: MI data payloads (controller info, health status, VPD) + * - Analogy: HTTP request/response bodies + */ + /** * NVME_MI_MSGTYPE_NVME - MCTP message type for NVMe-MI messages. * diff --git a/libnvme/src/nvme/nbft-types.h b/libnvme/src/nvme/nbft-types.h index 7de874fd06..1bb37c8f53 100644 --- a/libnvme/src/nvme/nbft-types.h +++ b/libnvme/src/nvme/nbft-types.h @@ -11,9 +11,23 @@ #include /** - * DOC: nbft.h + * DOC: nvme-types-nbft.h - NVMe Boot Firmware Table (NBFT) type definitions * - * NVM Express Boot Specification, Revision 1.0 + * This file defines the ACPI table structures for the NVMe Boot Specification. + * These types describe the NVMe Boot Firmware Table (NBFT) used for pre-OS + * boot configuration and discovery of NVMe-oF boot devices. + * + * Scope + * ===== + * - ACPI NBFT table structures + * - Boot device discovery descriptors + * - Host Fabric Interface (HFI) configuration + * - Subsystem/Namespace boot information + * - Security descriptors for boot + * - Discovery service descriptors + * + * This file is part of the nvme-types-*.h family following the established + * naming pattern for NVMe specification type definitions. */ /* diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index db3f2a7329..760eb8c4b9 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -21,6 +21,19 @@ * DOC: nvme-types-base.h * * NVMe Base Specification type definitions + * + * Based on NVM Express Base Specification, + * Revision 2.3, August 1, 2025 (Ratified) + * + * This file contains core NVMe types organized by functional area: + * - Helper Macros: NVME_GET, NVME_SET, NVME_CHECK, NVME_VAL + * - Controller Registers: CAP, CC, CSTS, and other BAR0 registers + * - Identify Structures: Controller, Namespace, and related data + * - Log Pages: SMART, Error, Firmware, and other log structures + * - Features: Feature identifiers and feature-specific data + * - Commands: Admin and I/O command structures + * - Namespace Management: Namespace descriptors and attributes + * - Status & Errors: Status codes and error information */ diff --git a/libnvme/src/nvme/nvme-types-fabrics.h b/libnvme/src/nvme/nvme-types-fabrics.h index 71176a0051..6a06c67f1f 100644 --- a/libnvme/src/nvme/nvme-types-fabrics.h +++ b/libnvme/src/nvme/nvme-types-fabrics.h @@ -21,6 +21,21 @@ * DOC: nvme-types-fabrics.h * * NVMe over Fabrics type definitions + * + * Based on: + * - NVM Express over RDMA Transport Specification, Revision 1.2, + * August 1, 2025 (Ratified) + * - NVM Express over TCP Transport Specification, Revision 1.2, + * August 1, 2025 (Ratified) + * - NVM Express Base Specification (Fabrics command set sections) + * + * This file is organized by functional area: + * - Discovery: Discovery log entries and log pages + * - Transport Configuration: Transport types, addressing, requirements + * - RDMA-Specific: RDMA queue pairs, providers, connection management + * - TCP-Specific: TCP security types + * - Discovery Information Model (DIM): Extended discovery attributes + * - Connection: Connect command data structures */ #define NVME_DISC_SUBSYS_NAME "nqn.2014-08.org.nvmexpress.discovery" diff --git a/libnvme/src/nvme/nvme-types-mi.h b/libnvme/src/nvme/nvme-types-mi.h index 5401cc477c..6c21c84396 100644 --- a/libnvme/src/nvme/nvme-types-mi.h +++ b/libnvme/src/nvme/nvme-types-mi.h @@ -18,9 +18,20 @@ #include /** - * DOC: nvme-types-mi.h + * DOC: nvme-types-mi.h - NVMe-MI data structure type definitions * * NVMe Management Interface type definitions + * + * Based on NVM Express Management Interface Specification, + * Revision 2.1, August 1, 2025 (Ratified) + * + * This file contains core NVMe types organized by functional area: + * - MI command data structures (controller info, port info, etc.) + * - Health status structures (subsystem and controller health) + * - VPD (Vital Product Data) structures + * - MI log page structures + * - Command effects and capabilities + * - Spec-defined data payloads */ /** diff --git a/libnvme/src/nvme/nvme-types-nvm.h b/libnvme/src/nvme/nvme-types-nvm.h index 367d73d7e3..e30e3316b2 100644 --- a/libnvme/src/nvme/nvme-types-nvm.h +++ b/libnvme/src/nvme/nvme-types-nvm.h @@ -21,6 +21,19 @@ * DOC: nvme-types-nvm.h * * NVM Command Set type definitions + * + * Based on NVM Express NVM Command Set Specification, + * Revision 1.2, August 1, 2025 (Ratified) + * + * This file is organized into functional groups: + * - NVM Namespace Identification: Extended LBA formats and namespace-specific data + * - I/O Command Set Support: Command set identification and capabilities + * - Reservation Notifications: Log pages for reservation events + * - Flexible Data Placement (FDP): Comprehensive FDP feature support including + * configuration, events, statistics, and status reporting + * - Data Set Management & Copy: DSM ranges and copy operation formats + * - Reservation Support: Controller registration and reservation management + * - I/O Management: Control flags and management operations */ /** diff --git a/libnvme/src/nvme/nvme-types-zns.h b/libnvme/src/nvme/nvme-types-zns.h index cdc0ff2d89..c2be83e406 100644 --- a/libnvme/src/nvme/nvme-types-zns.h +++ b/libnvme/src/nvme/nvme-types-zns.h @@ -21,6 +21,9 @@ * DOC: nvme-types-zns.h * * Zoned Namespace Command Set type definitions + * + * Based on NVM Express Zoned Namespace Command Set Specification, + * Revision 1.4, August 1, 2025 (Ratified) */ /** From fe8b94d9801c3e37e54fdde251da5f233f272689 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:06 +0200 Subject: [PATCH 02/10] nvme-types: add missing documentation Add missing documentation to the base and fabrics types. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-base.h | 12 ++++++++++++ libnvme/src/nvme/nvme-types-fabrics.h | 17 +++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index 760eb8c4b9..013ed5b594 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -3039,6 +3039,13 @@ enum nvme_ns_id_desc_nidt { NVME_NIDT_CSI = 4, }; +/** + * enum nvme_ns_id_desc_nidt_lens - Namespace Identifier Descriptor Type Lengths + * @NVME_NIDT_EUI64_LEN: IEEE Extended Unique Identifier length (8 bytes) + * @NVME_NIDT_NGUID_LEN: Namespace Globally Unique Identifier length (16 bytes) + * @NVME_NIDT_UUID_LEN: Universally Unique Identifier length (16 bytes) + * @NVME_NIDT_CSI_LEN: Command Set Identifier length (1 byte) + */ enum nvme_ns_id_desc_nidt_lens { NVME_NIDT_EUI64_LEN = 8, NVME_NIDT_NGUID_LEN = 16, @@ -3465,6 +3472,11 @@ struct nvme_error_log_page { __u8 log_page_version; }; +/** + * enum nvme_err_pel - Persistent Error Log Entry masks + * @NVME_ERR_PEL_BYTE_MASK: Byte mask for error location + * @NVME_ERR_PEL_BIT_MASK: Bit mask for error location + */ enum nvme_err_pel { NVME_ERR_PEL_BYTE_MASK = 0xf, NVME_ERR_PEL_BIT_MASK = 0x70, diff --git a/libnvme/src/nvme/nvme-types-fabrics.h b/libnvme/src/nvme/nvme-types-fabrics.h index 6a06c67f1f..99092e73d4 100644 --- a/libnvme/src/nvme/nvme-types-fabrics.h +++ b/libnvme/src/nvme/nvme-types-fabrics.h @@ -137,6 +137,23 @@ union nvmf_tsas { } tcp; }; +/** + * struct nvmf_disc_log_entry - Discovery Log Page Entry + * @trtype: Transport Type (see &enum nvmf_trtype) + * @adrfam: Address Family (see &enum nvmf_addr_family) + * @subtype: Subsystem Type + * @treq: Transport Requirements (see &enum nvmf_treq) + * @portid: Port ID + * @cntlid: Controller ID + * @asqsz: Admin Submission Queue Size + * @eflags: Entry Flags (see &enum nvmf_disc_eflags) + * @rsvd12: Reserved + * @trsvcid: Transport Service Identifier + * @rsvd64: Reserved + * @subnqn: NVM Subsystem Qualified Name + * @traddr: Transport Address + * @tsas: Transport Specific Address Subtype (see &union nvmf_tsas) + */ struct nvmf_disc_log_entry { __u8 trtype; __u8 adrfam; From 798a6f16a52f2e0e464fcce5e7737560756e238a Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:06 +0200 Subject: [PATCH 03/10] nvme-types: add or update missing types and accessors Add or update all missing types, shift/masks and accessors to sync it up with the current specification. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-base.h | 187 +++++++++++++++++++++++--- libnvme/src/nvme/nvme-types-fabrics.h | 13 +- libnvme/src/nvme/nvme-types-mi.h | 55 +++++++- libnvme/src/nvme/nvme-types-nvm.h | 93 ++++++++++++- nvme-print-stdout.c | 29 ++-- nvme.c | 6 +- 6 files changed, 346 insertions(+), 37 deletions(-) diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index 013ed5b594..4d3bdb055f 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -64,6 +64,30 @@ #define NVME_SET(value, name) \ (((__u32)(value) & NVME_##name##_MASK) << NVME_##name##_SHIFT) +/** + * NVMF_GET() - extract field from complex value + * @value: The original value of a complex field + * @name: The name of the sub-field within an nvme value + * + * By convention, this library defines _SHIFT and _MASK such that mask can be + * applied after the shift to isolate a specific set of bits that decode to a + * sub-field. + * + * Returns: The 'name' field from 'value' + */ +#define NVMF_GET(value, name) \ + (((value) >> NVMF_##name##_SHIFT) & NVMF_##name##_MASK) + +/** + * NVMF_SET() - set field into complex value + * @value: The value to be set in its completed position + * @name: The name of the sub-field within an nvme value + * + * Returns: The 'name' field from 'value' + */ +#define NVMF_SET(value, name) \ + (((__u32)(value) & NVMF_##name##_MASK) << NVMF_##name##_SHIFT) + /** * NVME_CHECK() - check value to compare field value * @value: The value to be checked @@ -1897,6 +1921,9 @@ enum nvme_id_ctrl_bpcap { NVME_CTRL_BACAP_RPMBBPWPS_SUPPORTED = 2, }; +#define NVME_CTRL_BACAP_RPMBBPWPS(bpcap) NVME_GET(bpcap, CTRL_BACAP_RPMBBPWPS) +#define NVME_CTRL_BACAP_SFBPWPS(bpcap) NVME_GET(bpcap, CTRL_BACAP_SFBPWPS) + /** * enum nvme_id_ctrl_plsi - Power Loss Signaling Information * @NVME_CTRL_PLSI_PLSEPF_SHIFT: Shift amount to get the PLS Emergency Power Fail from the @@ -1915,6 +1942,9 @@ enum nvme_id_ctrl_plsi { NVME_CTRL_PLSI_PLSFQ_MASK = 0x1, }; +#define NVME_CTRL_PLSI_PLSEPF(plsi) NVME_GET(plsi, CTRL_PLSI_PLSEPF) +#define NVME_CTRL_PLSI_PLSFQ(plsi) NVME_GET(plsi, CTRL_PLSI_PLSFQ) + /** * enum nvme_id_ctrl_crcap - Power Loss Signaling Information * @NVME_CTRL_CRCAP_RRSUP_SHIFT: Shift amount to get the Reachability Reporting Supported @@ -1933,6 +1963,9 @@ enum nvme_id_ctrl_crcap { NVME_CTRL_CRCAP_RGIDC_MASK = 0x1, }; +#define NVME_CTRL_CRCAP_RRSUP(crcap) NVME_GET(crcap, CTRL_CRCAP_RRSUP) +#define NVME_CTRL_CRCAP_RGICS(crcap) NVME_GET(crcap, CTRL_CRCAP_RGICS) + /** * enum nvme_id_ctrl_cntrltype - Controller types * @NVME_CTRL_CNTRLTYPE_IO: NVM I/O controller @@ -2234,6 +2267,9 @@ enum nvme_id_ctrl_dsto { NVME_CTRL_DSTO_HIRS = NVME_VAL(CTRL_DSTO_HIRS), }; +#define NVME_CTRL_DSTO_SDSO(dsto) NVME_GET(dsto, CTRL_DSTO_SDSO) +#define NVME_CTRL_DSTO_HIRS(dsto) NVME_GET(dsto, CTRL_DSTO_HIRS) + /** * enum nvme_id_ctrl_hctm - Flags indicate the attributes of the host * controlled thermal management feature @@ -2321,6 +2357,9 @@ enum nvme_id_ctrl_kpioc { NVME_CTRL_KPIOC_KPIOSC_MASK = 0x1, }; +#define NVME_CTRL_KPIOC_KPIOS(kpioc) NVME_GET(kpioc, CTRL_KPIOC_KPIOS) +#define NVME_CTRL_KPIOC_KPIOSC(kpioc) NVME_GET(kpioc, CTRL_KPIOC_KPIOSC) + /** * enum nvme_id_ctrl_cdpa - Configurable Device Personality Attributes * @NVME_CTRL_CDPA_HMAC_SHA_384: If set, then the controller supports @@ -2348,6 +2387,9 @@ enum nvme_id_ctrl_ipmsr { NVME_CTRL_IPMSR_SRV_MASK = 0x00FF, }; +#define NVME_CTRL_IPMSR_SRS(ipmsr) NVME_GET(ipmsr, CTRL_IPMSR_SRS) +#define NVME_CTRL_IPMSR_SRV(ipmsr) NVME_GET(ipmsr, CTRL_IPMSR_SRV) + /** * enum nvme_id_ctrl_sqes - Defines the required and maximum Submission Queue * entry size when using the NVM Command Set. @@ -2592,6 +2634,10 @@ enum nvme_id_ctrl_trattr { NVME_CTRL_TRATTR_MRTLL_MASK = 0x1, }; +#define NVME_CTRL_TRATTR_THMCS(trattr) NVME_GET(trattr, CTRL_TRATTR_THMCS) +#define NVME_CTRL_TRATTR_TUDCS(trattr) NVME_GET(trattr, CTRL_TRATTR_TUDCS) +#define NVME_CTRL_TRATTR_MRTLL(trattr) NVME_GET(trattr, CTRL_TRATTR_MRTLL) + /** * enum nvme_id_ctrl_fcatt - This field indicates attributes of the controller * that are specific to NVMe over Fabrics. @@ -2644,6 +2690,7 @@ enum nvme_lbaf_rp { NVME_LBAF_RP_BETTER = 1, NVME_LBAF_RP_GOOD = 2, NVME_LBAF_RP_DEGRADED = 3, + NVME_LBAF_RP_SHIFT = 0, NVME_LBAF_RP_MASK = 3, }; @@ -2833,6 +2880,7 @@ enum nvme_id_nsfeat { * enum nvme_id_ns_flbas - This field indicates the LBA data size & metadata * size combination that the namespace has been * formatted with + * @NVME_NS_FLBAS_LOWER_SHIFT: Shift to get the lower 4 bits of LBA format index * @NVME_NS_FLBAS_LOWER_MASK: Mask to get the index of one of the supported * LBA Formats's least significant * 4bits indicated in @@ -2843,17 +2891,23 @@ enum nvme_id_nsfeat { * extended data LBA. If cleared, indicates that all * of the metadata for a command is transferred as a * separate contiguous buffer of data. + * @NVME_NS_FLBAS_HIGHER_SHIFT: Shift to get the higher 2 bits of LBA format index * @NVME_NS_FLBAS_HIGHER_MASK: Mask to get the index of one of * the supported LBA Formats's most significant * 2bits indicated in * :c:type:`struct nvme_id_ns `.lbaf. */ enum nvme_id_ns_flbas { - NVME_NS_FLBAS_LOWER_MASK = 15 << 0, + NVME_NS_FLBAS_LOWER_SHIFT = 0, + NVME_NS_FLBAS_LOWER_MASK = 0xf, NVME_NS_FLBAS_META_EXT = 1 << 4, - NVME_NS_FLBAS_HIGHER_MASK = 3 << 5, + NVME_NS_FLBAS_HIGHER_SHIFT = 5, + NVME_NS_FLBAS_HIGHER_MASK = 0x3, }; +#define NVME_NS_FLBAS_LOWER(flbas) NVME_GET(flbas, NS_FLBAS_LOWER) +#define NVME_NS_FLBAS_HIGHER(flbas) NVME_GET(flbas, NS_FLBAS_HIGHER) + /** * enum nvme_id_ns_mc - This field indicates the capabilities for metadata. @@ -2909,10 +2963,16 @@ enum nvme_id_ns_dps { NVME_NS_DPS_PI_TYPE1 = 1, NVME_NS_DPS_PI_TYPE2 = 2, NVME_NS_DPS_PI_TYPE3 = 3, - NVME_NS_DPS_PI_MASK = 7 << 0, + NVME_NS_DPS_PI_SHIFT = 0, + NVME_NS_DPS_PI_MASK = 0x7, NVME_NS_DPS_PI_FIRST = 1 << 3, + NVME_NS_DPS_PI_FIRST_SHIFT = 3, + NVME_NS_DPS_PI_FIRST_MASK = 0x1, }; +#define NVME_NS_DPS_PI(dps) NVME_GET(dps, NS_DPS_PI) +#define NVME_NS_DPS_PI_FIRST(dps) NVME_GET(dps, NS_DPS_PI_FIRST) + /** * enum nvme_id_ns_nmic - This field specifies multi-path I/O and namespace * sharing capabilities of the namespace. @@ -3173,12 +3233,15 @@ struct nvme_id_uuid_list_entry { * @NVME_ID_UUID_ASSOCIATION_SUBSYSTEM_VENDOR: */ enum nvme_id_uuid { + NVME_ID_UUID_HDR_ASSOCIATION_SHIFT = 0, NVME_ID_UUID_HDR_ASSOCIATION_MASK = 0x3, NVME_ID_UUID_ASSOCIATION_NONE = 0, NVME_ID_UUID_ASSOCIATION_VENDOR = 1, NVME_ID_UUID_ASSOCIATION_SUBSYSTEM_VENDOR = 2, }; +#define NVME_ID_UUID_HDR_ASSOCIATION(uuid) NVME_GET(uuid, ID_UUID_HDR_ASSOCIATION) + /** * struct nvme_id_uuid_list - UUID list * @rsvd0: reserved @@ -3478,8 +3541,10 @@ struct nvme_error_log_page { * @NVME_ERR_PEL_BIT_MASK: Bit mask for error location */ enum nvme_err_pel { + NVME_ERR_PEL_BYTE_SHIFT = 0, NVME_ERR_PEL_BYTE_MASK = 0xf, - NVME_ERR_PEL_BIT_MASK = 0x70, + NVME_ERR_PEL_BIT_SHIFT = 4, + NVME_ERR_PEL_BIT_MASK = 0x7, }; /** @@ -3778,12 +3843,12 @@ enum nvme_smart_crit { NVME_SMART_CRIT_PMR_RO = NVME_VAL(SMART_CW_PMRRO), }; -#define NVME_SMART_CW_ASCBT(cw) NVME_GET(cw, SMART_CW_ASCBT), -#define NVME_SMART_CW_TTC(cw) NVME_GET(cw, SMART_CW_TTC), -#define NVME_SMART_CW_NDR(cw) NVME_GET(cw, SMART_CW_NDR), -#define NVME_SMART_CW_AMRO(cw) NVME_GET(cw, SMART_CW_AMRO), -#define NVME_SMART_CW_VMBF(cw) NVME_GET(cw, SMART_CW_VMBF), -#define NVME_SMART_CW_PMRRO(cw) NVME_GET(cw, SMART_CW_PMRRO), +#define NVME_SMART_CW_ASCBT(crit) NVME_GET(crit, SMART_CW_ASCBT) +#define NVME_SMART_CW_TTC(crit) NVME_GET(crit, SMART_CW_TTC) +#define NVME_SMART_CW_NDR(crit) NVME_GET(crit, SMART_CW_NDR) +#define NVME_SMART_CW_AMRO(crit) NVME_GET(crit, SMART_CW_AMRO) +#define NVME_SMART_CW_VMBF(crit) NVME_GET(crit, SMART_CW_VMBF) +#define NVME_SMART_CW_PMRRO(crit) NVME_GET(crit, SMART_CW_PMRRO) /** * enum nvme_smart_egcw - Endurance Group Critical Warning Summary @@ -3842,16 +3907,21 @@ struct nvme_cmd_effects_log { * @NVME_CMD_EFFECTS_UUID_SEL: UUID Selection Supported */ enum nvme_cmd_effects { - NVME_CMD_EFFECTS_CSUPP = 1 << 0, - NVME_CMD_EFFECTS_LBCC = 1 << 1, - NVME_CMD_EFFECTS_NCC = 1 << 2, - NVME_CMD_EFFECTS_NIC = 1 << 3, - NVME_CMD_EFFECTS_CCC = 1 << 4, - NVME_CMD_EFFECTS_CSER_MASK = 3 << 14, - NVME_CMD_EFFECTS_CSE_MASK = 7 << 16, - NVME_CMD_EFFECTS_UUID_SEL = 1 << 19, + NVME_CMD_EFFECTS_CSUPP = 1 << 0, + NVME_CMD_EFFECTS_LBCC = 1 << 1, + NVME_CMD_EFFECTS_NCC = 1 << 2, + NVME_CMD_EFFECTS_NIC = 1 << 3, + NVME_CMD_EFFECTS_CCC = 1 << 4, + NVME_CMD_EFFECTS_CSER_SHIFT = 14, + NVME_CMD_EFFECTS_CSER_MASK = 0x3, + NVME_CMD_EFFECTS_CSE_SHIFT = 16, + NVME_CMD_EFFECTS_CSE_MASK = 0x7, + NVME_CMD_EFFECTS_UUID_SEL = 1 << 19, }; +#define NVME_CMD_EFFECTS_CSER(effects) NVME_GET(effects, CMD_EFFECTS_CSER) +#define NVME_CMD_EFFECTS_CSE(effects) NVME_GET(effects, CMD_EFFECTS_CSE) + /** * struct nvme_st_result - Self-test Result * @dsts: Device Self-test Status: Indicates the device self-test code and the @@ -3940,9 +4010,12 @@ enum nvme_status_result { NVME_ST_RESULT_ABORTED_UNKNOWN = 0x8, NVME_ST_RESULT_ABORTED_SANITIZE = 0x9, NVME_ST_RESULT_NOT_USED = 0xf, + NVME_ST_RESULT_SHIFT = 0, NVME_ST_RESULT_MASK = 0xf, }; +#define NVME_ST_RESULT(result) NVME_GET(result, ST_RESULT) + /** * enum nvme_st_code - Self-test Code value * @NVME_ST_CODE_RESERVED: Reserved. @@ -3962,8 +4035,11 @@ enum nvme_st_code { NVME_ST_CODE_VS = 0xe, NVME_ST_CODE_ABORT = 0xf, NVME_ST_CODE_SHIFT = 4, + NVME_ST_CODE_MASK = 0xf, }; +#define NVME_ST_CODE(code) NVME_GET(code, ST_CODE) + /** * enum nvme_st_curr_op - Current Device Self-Test Operation * @NVME_ST_CURR_OP_NOT_RUNNING: No device self-test operation in progress. @@ -3982,10 +4058,15 @@ enum nvme_st_curr_op { NVME_ST_CURR_OP_EXTENDED = 0x2, NVME_ST_CURR_OP_VS = 0xe, NVME_ST_CURR_OP_RESERVED = 0xf, + NVME_ST_CURR_OP_SHIFT = 0, NVME_ST_CURR_OP_MASK = 0xf, + NVME_ST_CURR_OP_CMPL_SHIFT = 0, NVME_ST_CURR_OP_CMPL_MASK = 0x7f, }; +#define NVME_ST_CURR_OP(op) NVME_GET(op, ST_CURR_OP) +#define NVME_ST_CURR_OP_CMPL(op) NVME_GET(op, ST_CURR_OP_CMPL) + /** * enum nvme_st_valid_diag_info - Valid Diagnostic Information * @NVME_ST_VALID_DIAG_INFO_NSID: NSID Valid: if set, then the contents of @@ -4842,6 +4923,8 @@ enum nvme_fid_supported_effects { NVME_FID_SUPPORTED_EFFECTS_CDQSCP = 1 << 6, }; +#define NVME_FID_SUPPORTED_EFFECTS_SCOPE(effects) NVME_GET(effects, FID_SUPPORTED_EFFECTS_SCOPE) + /** * struct nvme_fid_supported_effects_log - Feature Identifiers Supported and Effects * @fid_support: Feature Identifier Supported @@ -5443,6 +5526,11 @@ enum nvme_sanitize_sstat { NVME_SANITIZE_SSTAT_MVCNCLD_MASK = 0x1, }; +#define NVME_SANITIZE_SSTAT_STATUS(sstat) NVME_GET(sstat, SANITIZE_SSTAT_STATUS) +#define NVME_SANITIZE_SSTAT_COMPLETED_PASSES(sstat) NVME_GET(sstat, SANITIZE_SSTAT_COMPLETED_PASSES) +#define NVME_SANITIZE_SSTAT_GLOBAL_DATA_ERASED(sstat) NVME_GET(sstat, SANITIZE_SSTAT_GLOBAL_DATA_ERASED) +#define NVME_SANITIZE_SSTAT_MVCNCLD(sstat) NVME_GET(sstat, SANITIZE_SSTAT_MVCNCLD) + /** * enum nvme_sanitize_ssi - Sanitize State Information (SSI) * @NVME_SANITIZE_SSI_SANS_SHIFT: Shift amount to get the value of Sanitize State @@ -5494,6 +5582,9 @@ enum nvme_sanitize_ssi { NVME_SANITIZE_SSI_POST_VERIF_DEALLOC = 6, }; +#define NVME_SANITIZE_SSI_SANS(ssi) NVME_GET(ssi, SANITIZE_SSI_SANS) +#define NVME_SANITIZE_SSI_FAILS(ssi) NVME_GET(ssi, SANITIZE_SSI_FAILS) + /** * enum nvme_lockdown_log_scope - lockdown log page scope attributes * @NVME_LOCKDOWN_ADMIN_CMD: Scope value for Admin commandS @@ -5564,6 +5655,13 @@ enum nvme_pma { NVME_PMA_PMT_MASK = 0xf, }; +#define NVME_PMA_PME(pma) NVME_GET(pma, PMA_PME) +#define NVME_PMA_NCPDF(pma) NVME_GET(pma, PMA_NCPDF) +#define NVME_PMA_EPF(pma) NVME_GET(pma, PMA_EPF) +#define NVME_PMA_MIPWRTS(pma) NVME_GET(pma, PMA_MIPWRTS) +#define NVME_PMA_PHDO(pma) NVME_GET(pma, PMA_PHDO) +#define NVME_PMA_PMT(pma) NVME_GET(pma, PMA_PMT) + /** * struct nvme_power_histogram_desc - Power Histogram Descriptor * @phbc: Power Histogram Bin Count. Does not wrap after %FFFFFFFFh. @@ -6949,6 +7047,8 @@ enum nvme_status_type { NVME_STATUS_TYPE_MI = 1, }; +#define NVME_STATUS_TYPE(type) NVME_GET(type, STATUS_TYPE) + /** * nvme_status_get_type() - extract the type from a nvme_* return value * @status: the (non-negative) return value from the NVMe API @@ -8411,6 +8511,18 @@ enum nvme_lm_cdq_fields { NVME_LM_CREATE_CDQ_CDQID_MASK = 0xffff, }; +#define NVME_LM_CDQ_MOS(fields) NVME_GET(fields, LM_CDQ_MOS) +#define NVME_LM_CDQ_SEL(fields) NVME_GET(fields, LM_CDQ_SEL) + +#define NVME_LM_QT(fields) NVME_GET(fields, LM_QT) +#define NVME_LM_CQS(fields) NVME_GET(fields, LM_CQS) + +#define NVME_LM_CREATE_CDQ_PC(fields) NVME_GET(fields, LM_CREATE_CDQ_PC) +#define NVME_LM_CREATE_CDQ_CNTLID(fields) NVME_GET(fields, LM_CREATE_CDQ_CNTLID) + +#define NVME_LM_DELETE_CDQ_CDQID(fields) NVME_GET(fields, LM_DELETE_CDQ_CDQID) +#define NVME_LM_CREATE_CDQ_CDQID(fields) NVME_GET(fields, LM_CREATE_CDQ_CDQID) + /** * enum nvme_lm_track_send_fields - Track Send command fields * @@ -8447,6 +8559,11 @@ enum nvme_lm_track_send_fields { NVME_LM_LACT_START_LOGGING = 1, }; +#define NVME_LM_TRACK_SEND_MOS(fields) NVME_GET(fields, LM_TRACK_SEND_MOS) +#define NVME_LM_TRACK_SEND_SEL(fields) NVME_GET(fields, LM_TRACK_SEND_SEL) + +#define NVME_LM_LACT(fields) NVME_GET(fields, LM_LACT) + /** * enum nvme_lm_migration_send_fields - Migration Send command fields * @@ -8536,6 +8653,21 @@ enum nvme_lm_migration_send_fields { NVME_LM_SET_CONTROLLER_STATE_CNTLID_MASK = 0xffff, }; +#define NVME_LM_MIGRATION_SEND_MOS(fields) NVME_GET(fields, LM_MIGRATION_SEND_MOS) +#define NVME_LM_MIGRATION_SEND_SEL(fields) NVME_GET(fields, LM_MIGRATION_SEND_SEL) +#define NVME_LM_MIGRATION_SEND_UIDX(fields) NVME_GET(fields, LM_MIGRATION_SEND_UIDX) + +#define NVME_LM_STYPE(fields) NVME_GET(fields, LM_STYPE) +#define NVME_LM_SUSPEND_CNTLID(fields) NVME_GET(fields, LM_SUSPEND_CNTLID) + +#define NVME_LM_RESUME_CNTLID(fields) NVME_GET(fields, LM_RESUME_CNTLID) + +#define NVME_LM_SEQIND(fields) NVME_GET(fields, LM_SEQIND) + +#define NVME_LM_SET_CONTROLLER_STATE_CSUUIDI(fields) NVME_GET(fields, LM_SET_CONTROLLER_STATE_CSUUIDI) +#define NVME_LM_SET_CONTROLLER_STATE_CSVI(fields) NVME_GET(fields, LM_SET_CONTROLLER_STATE_CSVI) +#define NVME_LM_SET_CONTROLLER_STATE_CNTLID(fields) NVME_GET(fields, LM_SET_CONTROLLER_STATE_CNTLID) + /** * enum nvme_lm_migration_recv_fields - Migration Receive command fields * @@ -8583,6 +8715,15 @@ enum nvme_lm_migration_recv_fields { NVME_LM_GET_CONTROLLER_STATE_CSUP = 1 << 0, }; +#define NVME_LM_MIGRATION_RECV_MOS(fields) NVME_GET(fields, LM_MIGRATION_RECV_MOS) +#define NVME_LM_MIGRATION_RECV_SEL(fields) NVME_GET(fields, LM_MIGRATION_RECV_SEL) +#define NVME_LM_MIGRATION_RECV_UIDX(fields) NVME_GET(fields, LM_MIGRATION_RECV_UIDX) + +#define NVME_LM_GET_CONTROLLER_STATE_CSVI(fields) NVME_GET(fields, LM_GET_CONTROLLER_STATE_CSVI) +#define NVME_LM_GET_CONTROLLER_STATE_CSUIDXP(fields) NVME_GET(fields, LM_GET_CONTROLLER_STATE_CSUIDXP) +#define NVME_LM_GET_CONTROLLER_STATE_CSUUIDI(fields) NVME_GET(fields, LM_GET_CONTROLLER_STATE_CSUUIDI) +#define NVME_LM_GET_CONTROLLER_STATE_CNTLID(fields) NVME_GET(fields, LM_GET_CONTROLLER_STATE_CNTLID) + /** * struct nvme_lm_io_submission_queue_data - I/O Submission Queue data structure. Fields related to * the contents of Create I/O Submission Queue command that created an I/O Submission Queue. @@ -8729,6 +8870,14 @@ enum nvme_lm_queue_attributes { NVME_LM_IOCQIV_SHIFT = 16, }; +#define NVME_LM_IOSQPC(attributes) NVME_GET(attributes, LM_IOSQPC) +#define NVME_LM_IOSQPRIO(attributes) NVME_GET(attributes, LM_IOSQPRIO) + +#define NVME_LM_IOCQPC(fid) NVME_GET(fid, LM_IOCQPC) +#define NVME_LM_IOCQIEN(fid) NVME_GET(fid, LM_IOCQIEN) +#define NVME_LM_S0PT(fid) NVME_GET(fid, LM_S0PT) +#define NVME_LM_IOCQIV(fid) NVME_GET(fid, LM_IOCQIV) + /** * enum nvme_lm_ctrl_data_queue_fid - Controller Data Queue - Set Feature * @@ -8740,6 +8889,8 @@ enum nvme_lm_ctrl_data_queue_fid { NVME_LM_CTRL_DATA_QUEUE_ETPT_SHIFT = 31, }; +#define NVME_LM_CTRL_DATA_QUEUE_ETPT(fid) NVME_GET(fid, LM_CTRL_DATA_QUEUE_ETPT) + /** * struct nvme_lm_ctrl_data_queue_fid_data - Get Controller Data Queue feature data * diff --git a/libnvme/src/nvme/nvme-types-fabrics.h b/libnvme/src/nvme/nvme-types-fabrics.h index 99092e73d4..108f00d073 100644 --- a/libnvme/src/nvme/nvme-types-fabrics.h +++ b/libnvme/src/nvme/nvme-types-fabrics.h @@ -211,18 +211,29 @@ enum nvmf_addr_family { /** * enum nvmf_treq - Transport Requirements codes for Discovery Log Page entry TREQ field + * @NVMF_TREQ_SECTYPE_SHIFT: Shift amount to get Secure Channel requirement + * @NVMF_TREQ_SECTYPE_MASK: Mask to get Secure Channel requirement * @NVMF_TREQ_NOT_SPECIFIED: Not specified * @NVMF_TREQ_REQUIRED: Required * @NVMF_TREQ_NOT_REQUIRED: Not Required + * @NVMF_TREQ_DISABLE_SQFLOW_SHIFT: Shift amount to get SQ flow control disable + * @NVMF_TREQ_DISABLE_SQFLOW_MASK: Mask to get SQ flow control disable * @NVMF_TREQ_DISABLE_SQFLOW: SQ flow control disable supported */ enum nvmf_treq { + NVMF_TREQ_SECTYPE_SHIFT = 0, + NVMF_TREQ_SECTYPE_MASK = 0x3, NVMF_TREQ_NOT_SPECIFIED = 0, NVMF_TREQ_REQUIRED = 1, NVMF_TREQ_NOT_REQUIRED = 2, - NVMF_TREQ_DISABLE_SQFLOW = 4, + NVMF_TREQ_DISABLE_SQFLOW_SHIFT = 2, + NVMF_TREQ_DISABLE_SQFLOW_MASK = 0x1, + NVMF_TREQ_DISABLE_SQFLOW = 1 << 2, }; +#define NVMF_TREQ_SECTYPE(treq) NVMF_GET(treq, TREQ_SECTYPE) +#define NVMF_TREQ_DISABLE_SQFLOW_BIT(treq) NVMF_GET(treq, TREQ_DISABLE_SQFLOW) + /** * enum nvmf_rdma_qptype - RDMA QP Service Type codes for Discovery Log Page * entry TSAS RDMA_QPTYPE field diff --git a/libnvme/src/nvme/nvme-types-mi.h b/libnvme/src/nvme/nvme-types-mi.h index 6c21c84396..e0f40f837d 100644 --- a/libnvme/src/nvme/nvme-types-mi.h +++ b/libnvme/src/nvme/nvme-types-mi.h @@ -66,6 +66,8 @@ enum nvme_mi_cmd_supported_effects { NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_NSS = 1 << 5, }; +#define NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE(effects) NVME_GET(effects, MI_CMD_SUPPORTED_EFFECTS_SCOPE) + /** * struct nvme_mi_cmd_supported_effects_log - NVMe-MI Commands Supported and Effects Log * @mi_cmd_support: NVMe-MI Commands Supported @@ -193,10 +195,59 @@ struct nvme_mi_read_sc_list { struct nvme_mi_osc cmds[]; }; +/** + * enum nvme_mi_nss - NVM Subsystem Status + * @NVME_MI_NSS_NRDY_SHIFT: Shift amount to get Not Ready + * @NVME_MI_NSS_NRDY_MASK: Mask to get Not Ready + * @NVME_MI_NSS_DRV_SHIFT: Shift amount to get Drive Ready + * @NVME_MI_NSS_DRV_MASK: Mask to get Drive Ready + */ +enum nvme_mi_nss { + NVME_MI_NSS_NRDY_SHIFT = 0, + NVME_MI_NSS_NRDY_MASK = 0x1, + NVME_MI_NSS_DRV_SHIFT = 1, + NVME_MI_NSS_DRV_MASK = 0x1, +}; + +#define NVME_MI_NSS_NRDY(nss) NVME_GET(nss, MI_NSS_NRDY) +#define NVME_MI_NSS_DRV(nss) NVME_GET(nss, MI_NSS_DRV) + +/** + * enum nvme_mi_sw - Smart Warnings + * @NVME_MI_SW_ST_SHIFT: Shift amount to get Spare Threshold + * @NVME_MI_SW_ST_MASK: Mask to get Spare Threshold + * @NVME_MI_SW_TAUT_SHIFT: Shift amount to get Temperature Above or Under Threshold + * @NVME_MI_SW_TAUT_MASK: Mask to get Temperature Above or Under Threshold + * @NVME_MI_SW_RD_SHIFT: Shift amount to get Reliability Degraded + * @NVME_MI_SW_RD_MASK: Mask to get Reliability Degraded + * @NVME_MI_SW_RO_SHIFT: Shift amount to get Read Only + * @NVME_MI_SW_RO_MASK: Mask to get Read Only + * @NVME_MI_SW_VMBF_SHIFT: Shift amount to get Volatile Memory Backup Failed + * @NVME_MI_SW_VMBF_MASK: Mask to get Volatile Memory Backup Failed + */ +enum nvme_mi_sw { + NVME_MI_SW_ST_SHIFT = 0, + NVME_MI_SW_ST_MASK = 0x1, + NVME_MI_SW_TAUT_SHIFT = 1, + NVME_MI_SW_TAUT_MASK = 0x1, + NVME_MI_SW_RD_SHIFT = 2, + NVME_MI_SW_RD_MASK = 0x1, + NVME_MI_SW_RO_SHIFT = 3, + NVME_MI_SW_RO_MASK = 0x1, + NVME_MI_SW_VMBF_SHIFT = 4, + NVME_MI_SW_VMBF_MASK = 0x1, +}; + +#define NVME_MI_SW_ST(sw) NVME_GET(sw, MI_SW_ST) +#define NVME_MI_SW_TAUT(sw) NVME_GET(sw, MI_SW_TAUT) +#define NVME_MI_SW_RD(sw) NVME_GET(sw, MI_SW_RD) +#define NVME_MI_SW_RO(sw) NVME_GET(sw, MI_SW_RO) +#define NVME_MI_SW_VMBF(sw) NVME_GET(sw, MI_SW_VMBF) + /** * struct nvme_mi_nvm_ss_health_status - Subsystem Management Data Structure - * @nss: NVM Subsystem Status - * @sw: Smart Warnings + * @nss: NVM Subsystem Status (see &enum nvme_mi_nss) + * @sw: Smart Warnings (see &enum nvme_mi_sw) * @ctemp: Composite Temperature * @pdlu: Percentage Drive Life Used * @ccs: Composite Controller Status diff --git a/libnvme/src/nvme/nvme-types-nvm.h b/libnvme/src/nvme/nvme-types-nvm.h index e30e3316b2..b91afe058d 100644 --- a/libnvme/src/nvme/nvme-types-nvm.h +++ b/libnvme/src/nvme/nvme-types-nvm.h @@ -38,19 +38,29 @@ /** * enum nvme_nvm_id_ns_elbaf - This field indicates the extended LBA format + * @NVME_NVM_ELBAF_STS_SHIFT: Shift to get the storage tag size * @NVME_NVM_ELBAF_STS_MASK: Mask to get the storage tag size used to determine * the variable-sized storage tag/reference tag fields + * @NVME_NVM_ELBAF_PIF_SHIFT: Shift to get the protection information format * @NVME_NVM_ELBAF_PIF_MASK: Mask to get the protection information format for * the extended LBA format. + * @NVME_NVM_ELBAF_QPIF_SHIFT: Shift to get the Qualified Protection Information Format * @NVME_NVM_ELBAF_QPIF_MASK: Mask to get the Qualified Protection Information * Format. */ enum nvme_nvm_id_ns_elbaf { - NVME_NVM_ELBAF_STS_MASK = 127 << 0, - NVME_NVM_ELBAF_PIF_MASK = 3 << 7, - NVME_NVM_ELBAF_QPIF_MASK = 15 << 9, + NVME_NVM_ELBAF_STS_SHIFT = 0, + NVME_NVM_ELBAF_STS_MASK = 0x7f, + NVME_NVM_ELBAF_PIF_SHIFT = 7, + NVME_NVM_ELBAF_PIF_MASK = 0x3, + NVME_NVM_ELBAF_QPIF_SHIFT = 9, + NVME_NVM_ELBAF_QPIF_MASK = 0xf, }; +#define NVME_NVM_ELBAF_STS(elbaf) NVME_GET(elbaf, NVM_ELBAF_STS) +#define NVME_NVM_ELBAF_PIF(elbaf) NVME_GET(elbaf, NVM_ELBAF_PIF) +#define NVME_NVM_ELBAF_QPIF(elbaf) NVME_GET(elbaf, NVM_ELBAF_QPIF) + /** * enum nvme_nvm_id_ns_pif - This field indicates the type of the Protection * Information Format @@ -69,6 +79,68 @@ enum nvme_nvm_id_ns_pif { NVME_NVM_PIF_QTYPE = 3, }; +/** + * enum nvme_nvm_id_ns_lbstm - Logical Block Storage Tag Mask + * @NVME_NVM_LBSTM_DEALLOCATED_SHIFT: Shift amount to get Deallocated/Unwritten Logical Block error time + * @NVME_NVM_LBSTM_DEALLOCATED_MASK: Mask to get Deallocated/Unwritten Logical Block error time + * @NVME_NVM_LBSTM_WRITTEN_SHIFT: Shift amount to get Written Logical Block error time + * @NVME_NVM_LBSTM_WRITTEN_MASK: Mask to get Written Logical Block error time + */ +enum nvme_nvm_id_ns_lbstm { + NVME_NVM_LBSTM_DEALLOCATED_SHIFT = 0, + NVME_NVM_LBSTM_DEALLOCATED_MASK = 0xffff, + NVME_NVM_LBSTM_WRITTEN_SHIFT = 16, + NVME_NVM_LBSTM_WRITTEN_MASK = 0xffff, +}; + +#define NVME_NVM_LBSTM_DEALLOCATED(lbstm) NVME_GET(lbstm, NVM_LBSTM_DEALLOCATED) +#define NVME_NVM_LBSTM_WRITTEN(lbstm) NVME_GET(lbstm, NVM_LBSTM_WRITTEN) + +/** + * enum nvme_nvm_id_ns_pic - Protection Information Capabilities + * @NVME_NVM_PIC_PITPS16B_SHIFT:Shift amount to get 16b Guard Protection Information Storage Tag Support + * @NVME_NVM_PIC_PITPS16B_MASK: Mask to get 16b Guard Protection Information Storage Tag Support + * @NVME_NVM_PIC_PISTM16B_SHIFT:Shift amount to get 16b Guard Protection Information Storage Tag Mask + * @NVME_NVM_PIC_PISTM16B_MASK: Mask to get 16b Guard Protection Information Storage Tag Mask + * @NVME_NVM_PIC_STCRS_SHIFT: Shift amount to get Storage Tag Check Read Support + * @NVME_NVM_PIC_STCRS_MASK: Mask to get Storage Tag Check Read Support + * @NVME_NVM_PIC_QPIFS_SHIFT:Shift amount to get Qualified Protection Information Format Support + * @NVME_NVM_PIC_QPIFS_MASK: Mask to get Qualified Protection Information Format Support + */ +enum nvme_nvm_id_ns_pic { + NVME_NVM_PIC_PITPS16B_SHIFT = 0, + NVME_NVM_PIC_PITPS16B_MASK = 0x1, + NVME_NVM_PIC_PISTM16B_SHIFT = 1, + NVME_NVM_PIC_PISTM16B_MASK = 0x1, + NVME_NVM_PIC_STCRS_SHIFT = 2, + NVME_NVM_PIC_STCRS_MASK = 0x1, + NVME_NVM_PIC_QPIFS_SHIFT = 3, + NVME_NVM_PIC_QPIFS_MASK = 0x1, +}; + +#define NVME_NVM_PIC_PITPS16B(pic) NVME_GET(pic, NVM_PIC_PITPS16B) +#define NVME_NVM_PIC_PISTM16B(pic) NVME_GET(pic, NVM_PIC_PISTM16B) +#define NVME_NVM_PIC_STCRS(pic) NVME_GET(pic, NVM_PIC_STCRS) +#define NVME_NVM_PIC_QPIFS(pic) NVME_GET(pic, NVM_PIC_QPIFS) + +/** + * enum nvme_nvm_id_ns_pifa - Protection Information Format Attribute + * @NVME_NVM_PIFA_STMLA_SHIFT: Shift amount to get Storage Tag Masking Level Attribute + * @NVME_NVM_PIFA_STMLA_MASK: Mask to get Storage Tag Masking Level Attribute + * @NVME_NVM_PIFA_BIT_GRANULARITY_MASKING: Bit Granularity Masking + * @NVME_NVM_PIFA_BYTE_GRANULARITY_MASKING: Byte Granularity Masking + * @NVME_NVM_PIFA_MASKING_NOT_SUPPORTED: Masking Not Supported + */ +enum nvme_nvm_id_ns_pifa { + NVME_NVM_PIFA_STMLA_SHIFT = 0, + NVME_NVM_PIFA_STMLA_MASK = 0xf, + NVME_NVM_PIFA_BIT_GRANULARITY_MASKING = 0x0, + NVME_NVM_PIFA_BYTE_GRANULARITY_MASKING = 0x1, + NVME_NVM_PIFA_MASKING_NOT_SUPPORTED = 0x2, +}; + +#define NVME_NVM_PIFA_STMLA(pifa) NVME_GET(pifa, NVM_PIFA_STMLA) + /** * struct nvme_nvm_id_ns - NVME Command Set I/O Command Set Specific Identify Namespace Data Structure * @lbstm: Logical Block Storage Tag Mask @@ -131,6 +203,12 @@ enum nvme_id_iocs_iocsc { NVME_IOCS_IOCSC_CPNCS_MASK = 0x1, }; +#define NVME_IOCS_IOCSC_NVMCS(iocsc) NVME_GET(iocsc, IOCS_IOCSC_NVMCS) +#define NVME_IOCS_IOCSC_KVCS(iocsc) NVME_GET(iocsc, IOCS_IOCSC_KVCS) +#define NVME_IOCS_IOCSC_ZNSCS(iocsc) NVME_GET(iocsc, IOCS_IOCSC_ZNSCS) +#define NVME_IOCS_IOCSC_SLMCS(iocsc) NVME_GET(iocsc, IOCS_IOCSC_SLMCS) +#define NVME_IOCS_IOCSC_CPNCS(iocsc) NVME_GET(iocsc, IOCS_IOCSC_CPNCS) + /** * struct nvme_resv_notification_log - Reservation Notification Log * @lpc: Log Page Count @@ -201,6 +279,10 @@ enum nvme_fdp_config_fdpa { NVME_FDP_CONFIG_FDPA_VALID_MASK = 0x1, }; +#define NVME_FDP_CONFIG_FDPA_RGIF(fdpa) NVME_GET(fdpa, FDP_CONFIG_FDPA_RGIF) +#define NVME_FDP_CONFIG_FDPA_FDPVWC(fdpa) NVME_GET(fdpa, FDP_CONFIG_FDPA_FDPVWC) +#define NVME_FDP_CONFIG_FDPA_VALID(fdpa) NVME_GET(fdpa, FDP_CONFIG_FDPA_VALID) + /** * struct nvme_fdp_config_desc - FDP Configuration Descriptor * @size: Descriptor size @@ -261,6 +343,9 @@ enum nvme_fdp_ruha { NVME_FDP_RUHA_CTRL_MASK = 0x1, }; +#define NVME_FDP_RUHA_HOST(ruha) NVME_GET(ruha, FDP_RUHA_HOST) +#define NVME_FDP_RUHA_CTRL(ruha) NVME_GET(ruha, FDP_RUHA_CTRL) + /** * struct nvme_fdp_ruhu_desc - Reclaim Unit Handle Usage Descriptor * @ruha: Reclaim Unit Handle Attributes (&enum nvme_fdp_ruha) @@ -416,6 +501,8 @@ enum nvme_fdp_supported_event_attributes { NVME_FDP_SUPP_EVENT_ENABLED_MASK = 0x1, }; +#define NVME_FDP_SUPP_EVENT_ENABLED(evta) NVME_GET(evta, FDP_SUPP_EVENT_ENABLED) + /** * struct nvme_fdp_supported_event_desc - Supported FDP Event Descriptor * @evt: FDP Event Type diff --git a/nvme-print-stdout.c b/nvme-print-stdout.c index 3d48642a59..75e2337cbb 100644 --- a/nvme-print-stdout.c +++ b/nvme-print-stdout.c @@ -2790,9 +2790,9 @@ static void stdout_id_ns_nsfeat(__u8 nsfeat) static void stdout_id_ns_flbas(__u8 flbas) { __u8 rsvd = (flbas & 0x80) >> 7; - __u8 msb2_lbaf = (flbas & NVME_NS_FLBAS_HIGHER_MASK) >> 5; - __u8 mdedata = (flbas & 0x10) >> 4; - __u8 lsb4_lbaf = flbas & NVME_NS_FLBAS_LOWER_MASK; + __u8 msb2_lbaf = NVME_FLBAS_HIGHER(flbas); + __u8 mdedata = NVME_FLBAS_META_EXT(flbas); + __u8 lsb4_lbaf = NVME_FLBAS_LOWER(flbas); if (rsvd) printf(" [7:7] : %#x\tReserved\n", rsvd); @@ -4387,21 +4387,30 @@ static void stdout_effects_log_human(__u32 effect) printf(" CCC%s", (effect & NVME_CMD_EFFECTS_CCC) ? set : clr); printf(" USS%s", (effect & NVME_CMD_EFFECTS_UUID_SEL) ? set : clr); - if ((effect & NVME_CMD_EFFECTS_CSER_MASK) >> 14 == 0) + switch (NVME_CMD_EFFECTS_CSER(effect)) { + case 0: printf(" No CSER defined\n"); - else if ((effect & NVME_CMD_EFFECTS_CSER_MASK) >> 14 == 1) + break; + case 1: printf(" No admin command for any namespace\n"); - else + break; + default: printf(" Reserved CSER\n"); + } - if ((effect & NVME_CMD_EFFECTS_CSE_MASK) >> 16 == 0) + switch (NVME_CMD_EFFECTS_CSE(effect)) { + case 0: printf(" No command restriction\n"); - else if ((effect & NVME_CMD_EFFECTS_CSE_MASK) >> 16 == 1) + break; + case 1: printf(" No other command for same namespace\n"); - else if ((effect & NVME_CMD_EFFECTS_CSE_MASK) >> 16 == 2) + break; + case 2: printf(" No other command for any namespace\n"); - else + break; + default: printf(" Reserved CSE\n"); + } } static void stdout_effects_entry(int admin, int index, diff --git a/nvme.c b/nvme.c index dbe58f8ec2..dee92fa524 100644 --- a/nvme.c +++ b/nvme.c @@ -7427,10 +7427,10 @@ static void get_pif_sts(struct nvme_id_ns *ns, struct nvme_nvm_id_ns *nvm_ns, nvme_id_ns_flbas_to_lbaf_inuse(ns->flbas, &lba_index); elbaf = le32_to_cpu(nvm_ns->elbaf[lba_index]); - *sts = elbaf & NVME_NVM_ELBAF_STS_MASK; - *pif = (elbaf & NVME_NVM_ELBAF_PIF_MASK) >> 7; + *sts = NVME_NVM_ELBAF_STS(elbaf); + *pif = NVME_NVM_ELBAF_PIF(elbaf); if (*pif == NVME_NVM_PIF_QTYPE && (nvm_ns->pic & 0x8)) - *pif = (elbaf & NVME_NVM_ELBAF_QPIF_MASK) >> 9; + *pif = NVME_NVM_ELBAF_QPIF(elbaf); } static int get_pi_info(struct libnvme_transport_handle *hdl, From 8557c552dd48b62eaef2f369ed6da866fb3d2392 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:06 +0200 Subject: [PATCH 04/10] nvme-types-mi: remove backwards compat defines Drop these for the upcoming major release. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-mi.h | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/libnvme/src/nvme/nvme-types-mi.h b/libnvme/src/nvme/nvme-types-mi.h index e0f40f837d..85d9d69f3d 100644 --- a/libnvme/src/nvme/nvme-types-mi.h +++ b/libnvme/src/nvme/nvme-types-mi.h @@ -507,17 +507,3 @@ struct nvme_mi_vpd_hdr { __u8 chchk; __u8 vpd[]; }; - -/* backwards compat for old "CCS" definitions */ -#define nvme_mi_css nvme_mi_ccs -#define NVME_MI_CSS_CFS NVME_MI_CCS_CFS -#define NVME_MI_CSS_SHST NVME_MI_CCS_SHST -#define NVME_MI_CSS_NSSRO NVME_MI_CCS_NSSRO -#define NVME_MI_CSS_CECO NVME_MI_CCS_CECO -#define NVME_MI_CSS_NAC NVME_MI_CCS_NAC -#define NVME_MI_CSS_FA NVME_MI_CCS_FA -#define NVME_MI_CSS_CSTS NVME_MI_CCS_CSTS -#define NVME_MI_CSS_CTEMP NVME_MI_CCS_CTEMP -#define NVME_MI_CSS_PDLU NVME_MI_CCS_PDLU -#define NVME_MI_CSS_SPARE NVME_MI_CCS_SPARE -#define NVME_MI_CSS_CCWARN NVME_MI_CCS_CCWARN From 5698a5b4990a0d6df556825c6e3246f15b2f34e3 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:06 +0200 Subject: [PATCH 05/10] nvme-types-mi: update reserved field name The established name is rsvd instead of reserved. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-mi.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libnvme/src/nvme/nvme-types-mi.h b/libnvme/src/nvme/nvme-types-mi.h index 85d9d69f3d..b150082fcf 100644 --- a/libnvme/src/nvme/nvme-types-mi.h +++ b/libnvme/src/nvme/nvme-types-mi.h @@ -71,11 +71,11 @@ enum nvme_mi_cmd_supported_effects { /** * struct nvme_mi_cmd_supported_effects_log - NVMe-MI Commands Supported and Effects Log * @mi_cmd_support: NVMe-MI Commands Supported - * @reserved1: Reserved + * @rsvd128: Reserved */ struct nvme_mi_cmd_supported_effects_log { __le32 mi_cmd_support[NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_MAX]; - __le32 reserved1[NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_RESERVED]; + __le32 rsvd128[NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_RESERVED]; }; /** From 08d2dbaf48e28b4294d5c77f2b88939358554257 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:07 +0200 Subject: [PATCH 06/10] nvme-types-base: drop depricated mask Drop the depricated mask for the next major version. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-base.h | 2 -- 1 file changed, 2 deletions(-) diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index 4d3bdb055f..764406c6a6 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -513,7 +513,6 @@ enum nvme_cc { * @NVME_CSTS_SHST_NORMAL: Normal operation * @NVME_CSTS_SHST_OCCUR: Shutdown processing occurring * @NVME_CSTS_SHST_CMPLT: Shutdown processing complete - * @NVME_CSTS_SHN_MASK: Deprecated mask to get the shutdown status */ enum nvme_csts { NVME_CSTS_RDY_SHIFT = 0, @@ -531,7 +530,6 @@ enum nvme_csts { NVME_CSTS_SHST_NORMAL = 0, NVME_CSTS_SHST_OCCUR = 1, NVME_CSTS_SHST_CMPLT = 2, - NVME_CSTS_SHN_MASK = NVME_CSTS_SHST_MASK, /* Deprecated */ }; #define NVME_CSTS_RDY(csts) NVME_GET(csts, CSTS_RDY) From c543978c43b12f7170373aa811ab1344054499c7 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:07 +0200 Subject: [PATCH 07/10] nvme-types-base: rename notification mask features The naming pattern is not correct for this feature. It should include the notification part in the name to be consistent. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-cmds-base.h | 16 ++++++++-------- libnvme/src/nvme/nvme-cmds.c | 2 +- libnvme/src/nvme/nvme-types-base.h | 4 ++-- libnvme/test/ioctl/features.c | 20 ++++++++++---------- libnvme/test/test.c | 6 +++--- nvme-print-json.c | 6 +++--- nvme-print-stdout.c | 2 +- nvme-print.c | 2 +- nvme.c | 2 +- 9 files changed, 30 insertions(+), 30 deletions(-) diff --git a/libnvme/src/nvme/nvme-cmds-base.h b/libnvme/src/nvme/nvme-cmds-base.h index 8dcef30355..f1b929c2fc 100644 --- a/libnvme/src/nvme/nvme-cmds-base.h +++ b/libnvme/src/nvme/nvme-cmds-base.h @@ -2399,7 +2399,7 @@ nvme_init_set_features_host_id(struct libnvme_passthru_cmd *cmd, } /** - * nvme_init_set_features_resv_mask() - Initialize passthru command for + * nvme_init_set_features_resv_nf_mask() - Initialize passthru command for * Reservation Notification Mask * @cmd: Passthru command to use * @nsid: Namespace ID @@ -2407,13 +2407,13 @@ nvme_init_set_features_host_id(struct libnvme_passthru_cmd *cmd, * @mask: Reservation Notification Mask Field * * Initializes the passthru command buffer for the Set Features command with - * FID value %NVME_FEAT_FID_RESV_MASK + * FID value %NVME_FEAT_FID_RESV_NF_MASK */ static inline void -nvme_init_set_features_resv_mask(struct libnvme_passthru_cmd *cmd, __u32 nsid, +nvme_init_set_features_resv_nf_mask(struct libnvme_passthru_cmd *cmd, __u32 nsid, bool sv, __u32 mask) { - nvme_init_set_features(cmd, NVME_FEAT_FID_RESV_MASK, sv); + nvme_init_set_features(cmd, NVME_FEAT_FID_RESV_NF_MASK, sv); cmd->nsid = nsid; cmd->cdw11 = mask; } @@ -3041,7 +3041,7 @@ nvme_init_get_features_host_id(struct libnvme_passthru_cmd *cmd, } /** - * nvme_init_get_features_resv_mask() - Initialize passthru command for + * nvme_init_get_features_resv_nf_mask() - Initialize passthru command for * Get Features - Reservation Notification Mask * @cmd: Passthru command to use * @nsid: Namespace ID @@ -3049,13 +3049,13 @@ nvme_init_get_features_host_id(struct libnvme_passthru_cmd *cmd, * see &enum nvme_get_features_sel * * Initializes the passthru command buffer for the Get Features command with - * FID value %NVME_FEAT_FID_RESV_MASK + * FID value %NVME_FEAT_FID_RESV_NF_MASK */ static inline void -nvme_init_get_features_resv_mask(struct libnvme_passthru_cmd *cmd, __u32 nsid, +nvme_init_get_features_resv_nf_mask(struct libnvme_passthru_cmd *cmd, __u32 nsid, enum nvme_get_features_sel sel) { - nvme_init_get_features(cmd, NVME_FEAT_FID_RESV_MASK, sel); + nvme_init_get_features(cmd, NVME_FEAT_FID_RESV_NF_MASK, sel); cmd->nsid = nsid; } diff --git a/libnvme/src/nvme/nvme-cmds.c b/libnvme/src/nvme/nvme-cmds.c index cb187c1863..d0bc1b6479 100644 --- a/libnvme/src/nvme/nvme-cmds.c +++ b/libnvme/src/nvme/nvme-cmds.c @@ -618,7 +618,7 @@ __libnvme_public int libnvme_get_feature_length( case NVME_FEAT_FID_SANITIZE: case NVME_FEAT_FID_ENDURANCE_EVT_CFG: case NVME_FEAT_FID_SW_PROGRESS: - case NVME_FEAT_FID_RESV_MASK: + case NVME_FEAT_FID_RESV_NF_MASK: case NVME_FEAT_FID_RESV_PERSIST: case NVME_FEAT_FID_WRITE_PROTECT: case NVME_FEAT_FID_POWER_LIMIT: diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index 764406c6a6..ea781b7ae5 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -7415,7 +7415,7 @@ enum nvme_cmd_get_log_lid { * @NVME_FEAT_FID_NS_METADATA: Namespace Metadata * @NVME_FEAT_FID_SW_PROGRESS: Software Progress Marker * @NVME_FEAT_FID_HOST_ID: Host Identifier - * @NVME_FEAT_FID_RESV_MASK: Reservation Notification Mask + * @NVME_FEAT_FID_RESV_NF_MASK: Reservation Notification Mask * @NVME_FEAT_FID_RESV_PERSIST: Reservation Persistence * @NVME_FEAT_FID_WRITE_PROTECT: Namespace Write Protection Config * @NVME_FEAT_FID_BP_WRITE_PROTECT: Boot Partition Write Protection Config @@ -7465,7 +7465,7 @@ enum nvme_features_id { NVME_FEAT_FID_NS_METADATA = 0x7f, NVME_FEAT_FID_SW_PROGRESS = 0x80, NVME_FEAT_FID_HOST_ID = 0x81, - NVME_FEAT_FID_RESV_MASK = 0x82, + NVME_FEAT_FID_RESV_NF_MASK = 0x82, NVME_FEAT_FID_RESV_PERSIST = 0x83, NVME_FEAT_FID_WRITE_PROTECT = 0x84, NVME_FEAT_FID_BP_WRITE_PROTECT = 0x85, diff --git a/libnvme/test/ioctl/features.c b/libnvme/test/ioctl/features.c index f4bc8d6025..ebeda50bad 100644 --- a/libnvme/test/ioctl/features.c +++ b/libnvme/test/ioctl/features.c @@ -1322,14 +1322,14 @@ static void test_get_host_id_extended(void) cmp(get_hostid, hostid, sizeof(hostid), "incorrect host identifier"); } -static void test_set_resv_mask(void) +static void test_set_resv_nf_mask(void) { uint32_t MASK = 0x23456789; struct mock_cmd mock_admin_cmd = { .opcode = nvme_admin_set_features, .nsid = TEST_NSID, .cdw10 = (uint32_t)1 << 31 /* SAVE */ - | NVME_FEAT_FID_RESV_MASK, + | NVME_FEAT_FID_RESV_NF_MASK, .cdw11 = MASK, .result = TEST_RESULT, }; @@ -1337,7 +1337,7 @@ static void test_set_resv_mask(void) int err; set_mock_admin_cmds(&mock_admin_cmd, 1); - nvme_init_set_features_resv_mask(&cmd, TEST_NSID, true, MASK); + nvme_init_set_features_resv_nf_mask(&cmd, TEST_NSID, true, MASK); err = libnvme_exec_admin_passthru(test_hdl, &cmd); end_mock_cmds(); check(err == 0, "set features returned error %d", err); @@ -1346,19 +1346,19 @@ static void test_set_resv_mask(void) (uint64_t)cmd.result, TEST_RESULT); } -static void test_get_resv_mask(void) +static void test_get_resv_nf_mask(void) { struct mock_cmd mock_admin_cmd = { .opcode = nvme_admin_get_features, .nsid = TEST_NSID, - .cdw10 = TEST_SEL << 8 | NVME_FEAT_FID_RESV_MASK, + .cdw10 = TEST_SEL << 8 | NVME_FEAT_FID_RESV_NF_MASK, .result = TEST_RESULT, }; struct libnvme_passthru_cmd cmd; int err; set_mock_admin_cmds(&mock_admin_cmd, 1); - nvme_init_get_features_resv_mask(&cmd, TEST_NSID, TEST_SEL); + nvme_init_get_features_resv_nf_mask(&cmd, TEST_NSID, TEST_SEL); err = libnvme_exec_admin_passthru(test_hdl, &cmd); end_mock_cmds(); check(err == 0, "get features returned error %d", err); @@ -1491,7 +1491,7 @@ static void test_set_kernel_error(void) struct mock_cmd mock_admin_cmd = { .opcode = nvme_admin_set_features, .nsid = TEST_NSID, - .cdw10 = NVME_FEAT_FID_RESV_MASK, + .cdw10 = NVME_FEAT_FID_RESV_NF_MASK, .cdw11 = MASK, .result = 0, .err = -EIO, @@ -1500,7 +1500,7 @@ static void test_set_kernel_error(void) int err; set_mock_admin_cmds(&mock_admin_cmd, 1); - nvme_init_set_features_resv_mask(&cmd, TEST_NSID, false, MASK); + nvme_init_set_features_resv_nf_mask(&cmd, TEST_NSID, false, MASK); err = libnvme_exec_admin_passthru(test_hdl, &cmd); end_mock_cmds(); check(err == -EIO, "got error %d, expected -EIO", err); @@ -1684,8 +1684,8 @@ int main(void) RUN_TEST(set_host_id_extended); RUN_TEST(get_host_id); RUN_TEST(get_host_id_extended); - RUN_TEST(set_resv_mask); - RUN_TEST(get_resv_mask); + RUN_TEST(set_resv_nf_mask); + RUN_TEST(get_resv_nf_mask); RUN_TEST(set_resv_persist); RUN_TEST(get_resv_persist); RUN_TEST(set_write_protect); diff --git a/libnvme/test/test.c b/libnvme/test/test.c index 633615e13f..2dec671248 100644 --- a/libnvme/test/test.c +++ b/libnvme/test/test.c @@ -303,13 +303,13 @@ static int test_ctrl(libnvme_ctrl_t c) (uint64_t)cmd.result); else if (ret > 0) printf(" ERROR: Sanitize:%x\n", ret); - nvme_init_get_features_resv_mask(&cmd, 0, sel); + nvme_init_get_features_resv_nf_mask(&cmd, 0, sel); ret = libnvme_exec_admin_passthru(hdl, &cmd); if (!ret) - printf(" Reservation Mask:%" PRIu64 "\n", + printf(" Reservation Notification Mask:%" PRIu64 "\n", (uint64_t)cmd.result); else if (ret > 0) - printf(" ERROR: Reservation Mask:%x\n", ret); + printf(" ERROR: Reservation Notification Mask:%x\n", ret); nvme_init_get_features_resv_persist(&cmd, 0, sel); ret = libnvme_exec_admin_passthru(hdl, &cmd); if (!ret) diff --git a/nvme-print-json.c b/nvme-print-json.c index 16e8b618a8..62c8cabf7e 100644 --- a/nvme-print-json.c +++ b/nvme-print-json.c @@ -4053,7 +4053,7 @@ static void json_feature_show_fields_host_id(struct json_object *r, le64_to_cpu(*(__le64 *)hostid)); } -static void json_feature_show_fields_resv_mask(struct json_object *r, unsigned int result) +static void json_feature_show_fields_resv_nf_mask(struct json_object *r, unsigned int result) { obj_add_str(r, "Mask Reservation Preempted Notification (RESPRE)", (result & 8) >> 3 ? "True" : "False"); @@ -4322,8 +4322,8 @@ static void json_feature_show_fields(enum nvme_features_id fid, unsigned int res case NVME_FEAT_FID_HOST_ID: json_feature_show_fields_host_id(r, result, buf); break; - case NVME_FEAT_FID_RESV_MASK: - json_feature_show_fields_resv_mask(r, result); + case NVME_FEAT_FID_RESV_NF_MASK: + json_feature_show_fields_resv_nf_mask(r, result); break; case NVME_FEAT_FID_RESV_PERSIST: json_feature_show_fields_resv_persist(r, result); diff --git a/nvme-print-stdout.c b/nvme-print-stdout.c index 75e2337cbb..4f8845f1a0 100644 --- a/nvme-print-stdout.c +++ b/nvme-print-stdout.c @@ -5483,7 +5483,7 @@ static void stdout_feature_show_fields(enum nvme_features_id fid, case NVME_FEAT_FID_HOST_ID: stdout_feat_host_id(result, buf); break; - case NVME_FEAT_FID_RESV_MASK: + case NVME_FEAT_FID_RESV_NF_MASK: printf("\tMask Reservation Preempted Notification (RESPRE): %s\n", NVME_FEAT_RM_RESPRE(result) ? "True" : "False"); printf("\tMask Reservation Released Notification (RESREL): %s\n", diff --git a/nvme-print.c b/nvme-print.c index 5bed7a1f39..06d3ed28a1 100644 --- a/nvme-print.c +++ b/nvme-print.c @@ -1033,7 +1033,7 @@ const char *nvme_feature_to_string(enum nvme_features_id feature) case NVME_FEAT_FID_NS_METADATA: return "Namespace Metadata"; case NVME_FEAT_FID_SW_PROGRESS: return "Software Progress"; case NVME_FEAT_FID_HOST_ID: return "Host Identifier"; - case NVME_FEAT_FID_RESV_MASK: return "Reservation Notification Mask"; + case NVME_FEAT_FID_RESV_NF_MASK: return "Reservation Notification Mask"; case NVME_FEAT_FID_RESV_PERSIST: return "Reservation Persistence"; case NVME_FEAT_FID_WRITE_PROTECT: return "Namespace Write Protect"; case NVME_FEAT_FID_BP_WRITE_PROTECT: return "Boot Partition Write Protection Config"; diff --git a/nvme.c b/nvme.c index dee92fa524..72763daf87 100644 --- a/nvme.c +++ b/nvme.c @@ -298,7 +298,7 @@ static OPT_VALS(feature_name) = { VAL_BYTE("ns-metadata", NVME_FEAT_FID_NS_METADATA), VAL_BYTE("sw-progress", NVME_FEAT_FID_SW_PROGRESS), VAL_BYTE("host-id", NVME_FEAT_FID_HOST_ID), - VAL_BYTE("resv-mask", NVME_FEAT_FID_RESV_MASK), + VAL_BYTE("resv-nf-mask", NVME_FEAT_FID_RESV_NF_MASK), VAL_BYTE("resv-persist", NVME_FEAT_FID_RESV_PERSIST), VAL_BYTE("write-protect", NVME_FEAT_FID_WRITE_PROTECT), VAL_BYTE("bp-write-protect", NVME_FEAT_FID_BP_WRITE_PROTECT), From a104a6b43a415564027f449f14fbb22b9bdab1c4 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:07 +0200 Subject: [PATCH 08/10] nvme-types-nbft: rename nbft type header The nvme types are defined in the nvme-types-*.h headers. Signed-off-by: Daniel Wagner --- libnvme/doc/meson.build | 2 +- libnvme/src/meson.build | 2 +- libnvme/src/nvme/nbft.h | 2 +- libnvme/src/nvme/{nbft-types.h => nvme-types-nbft.h} | 1 + libnvme/test/meson.build | 3 ++- 5 files changed, 6 insertions(+), 4 deletions(-) rename libnvme/src/nvme/{nbft-types.h => nvme-types-nbft.h} (99%) diff --git a/libnvme/doc/meson.build b/libnvme/doc/meson.build index e23f095229..2b42854694 100644 --- a/libnvme/doc/meson.build +++ b/libnvme/doc/meson.build @@ -19,7 +19,7 @@ api_files = [ 'linux.h', 'mi-types.h', 'mi.h', - 'nbft-types.h', + 'nvme-types-nbft.h', 'nbft.h', 'nvme-cmds.h', 'nvme-types.h', diff --git a/libnvme/src/meson.build b/libnvme/src/meson.build index d0418b8e95..d618ca11aa 100644 --- a/libnvme/src/meson.build +++ b/libnvme/src/meson.build @@ -69,7 +69,7 @@ if want_fabrics headers += [ 'nvme/accessors-fabrics.h', 'nvme/fabrics.h', - 'nvme/nbft-types.h', + 'nvme/nvme-types-nbft.h', 'nvme/nbft.h', ] else diff --git a/libnvme/src/nvme/nbft.h b/libnvme/src/nvme/nbft.h index 1f7f2f8af3..49caa277c4 100644 --- a/libnvme/src/nvme/nbft.h +++ b/libnvme/src/nvme/nbft.h @@ -12,7 +12,7 @@ #include -#include +#include /** * enum libnbft_primary_admin_host_flag - Primary Administrative Host Descriptor Flags diff --git a/libnvme/src/nvme/nbft-types.h b/libnvme/src/nvme/nvme-types-nbft.h similarity index 99% rename from libnvme/src/nvme/nbft-types.h rename to libnvme/src/nvme/nvme-types-nbft.h index 1bb37c8f53..a799e2b374 100644 --- a/libnvme/src/nvme/nbft-types.h +++ b/libnvme/src/nvme/nvme-types-nbft.h @@ -5,6 +5,7 @@ * * Authors: Stuart Hayes * + * NVMe Boot Firmware Table (NBFT) type definitions */ #pragma once diff --git a/libnvme/test/meson.build b/libnvme/test/meson.build index 5ce8ff903c..8c1ae1863f 100644 --- a/libnvme/test/meson.build +++ b/libnvme/test/meson.build @@ -251,7 +251,6 @@ foreach hdr : [ 'linux', 'mi', 'nbft', - 'nbft-types', 'nvme-cmds', 'nvme-cmds-base', 'nvme-cmds-fabrics', @@ -262,6 +261,8 @@ foreach hdr : [ 'nvme-types-base', 'nvme-types-fabrics', 'nvme-types-mi', + 'nvme-types-nbft', + 'nvme-types-nvm', 'nvme-types-zns', 'tree', 'util', From 3f2fe31ad4325db1f20e271d7ac45fedfb4a1b73 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:07 +0200 Subject: [PATCH 09/10] nvme-types-nbft: update to v1.3 Update the nvme-types-nbft header to the latest spec version. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/nvme-types-nbft.h | 33 ++++++++++++++++-------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/libnvme/src/nvme/nvme-types-nbft.h b/libnvme/src/nvme/nvme-types-nbft.h index a799e2b374..3c6eea2114 100644 --- a/libnvme/src/nvme/nvme-types-nbft.h +++ b/libnvme/src/nvme/nvme-types-nbft.h @@ -32,11 +32,11 @@ */ /* - * ACPI NBFT table structures (TP8012 Boot Specification rev. 1.0) + * ACPI NBFT table structures (Boot Specification rev. 1.3) */ /** - * enum nbft_desc_type - NBFT Elements - Descriptor Types (Figure 5) + * enum nbft_desc_type - NBFT Elements - Descriptor Types (Figure 6) * @NBFT_DESC_HEADER: Header: an ACPI structure header with some additional * NBFT specific info. * @NBFT_DESC_CONTROL: Control Descriptor: indicates the location of host, @@ -55,6 +55,8 @@ * @NBFT_DESC_RESERVED_8: Reserved. * @NBFT_DESC_SSNS_EXT_INFO: SSNS Extended Info Descriptor: indicated by an SSNS * Descriptor if required. + * @NBFT_DESC_HFI_EXT_INFO: HFI Extended Info Descriptor: indicated by an HFI Transport + * Info descriptor (added in revision 1.1+). */ enum nbft_desc_type { NBFT_DESC_HEADER = 0, @@ -67,10 +69,11 @@ enum nbft_desc_type { NBFT_DESC_HFI_TRINFO = 7, NBFT_DESC_RESERVED_8 = 8, NBFT_DESC_SSNS_EXT_INFO = 9, + NBFT_DESC_HFI_EXT_INFO = 0xA, }; /** - * enum nbft_trtype - NBFT Interface Transport Types (Figure 7) + * enum nbft_trtype - NBFT Interface Transport Types (Figure 8) * @NBFT_TRTYPE_TCP: NVMe/TCP (802.3 + TCP/IP). String Designator "tcp". */ enum nbft_trtype { @@ -91,7 +94,7 @@ struct nbft_heap_obj { } __attribute__((packed)); /** - * struct nbft_header - NBFT Table - Header (Figure 8) + * struct nbft_header - NBFT Table - Header (Figure 9) * @signature: Signature: An ASCII string representation of the table * identifier. This field shall be set to the value 4E424654h * (i.e. "NBFT", see #NBFT_HEADER_SIG). @@ -151,7 +154,7 @@ struct nbft_header { }; /** - * struct nbft_control - NBFT Table - Control Descriptor (Figure 8) + * struct nbft_control - NBFT Table - Control Descriptor (Figure 9) * @structure_id: Structure ID: This field specifies the element (refer to * &enum nbft_desc_type). This field shall be set to 1h (i.e., * Control, #NBFT_DESC_CONTROL). @@ -269,7 +272,7 @@ enum nbft_control_flags { }; /** - * struct nbft_host - Host Descriptor (Figure 9) + * struct nbft_host - Host Descriptor (Figure 10) * @structure_id: Structure ID: This field shall be set to 2h (i.e., * Host Descriptor; #NBFT_DESC_HOST). * @flags: Host Flags, see &enum nbft_host_flags. @@ -337,7 +340,7 @@ enum nbft_host_flags { }; /** - * struct nbft_hfi - Host Fabric Interface (HFI) Descriptor (Figure 11) + * struct nbft_hfi - Host Fabric Interface (HFI) Descriptor (Figure 12) * @structure_id: Structure ID: This field shall be set to 3h (i.e., Host Fabric * Interface Descriptor; #NBFT_DESC_HFI). * @index: HFI Descriptor Index: This field indicates the number of this @@ -371,7 +374,7 @@ enum nbft_hfi_flags { }; /** - * struct nbft_hfi_info_tcp - HFI Transport Info Descriptor - NVMe/TCP (Figure 13) + * struct nbft_hfi_info_tcp - HFI Transport Info Descriptor - NVMe/TCP (Figure 14) * @structure_id: Structure ID: This field shall be set to 7h (i.e., * HFI Transport Info; #NBFT_DESC_HFI_TRINFO). * @version: Version: This field shall be set to 1h. @@ -486,7 +489,7 @@ enum nbft_hfi_info_tcp_flags { }; /** - * struct nbft_ssns - Subsystem Namespace (SSNS) Descriptor (Figure 15) + * struct nbft_ssns - Subsystem Namespace (SSNS) Descriptor (Figure 17) * @structure_id: Structure ID: This field shall be set to 4h * (i.e., SSNS; #NBFT_DESC_SSNS). * @index: SSNS Descriptor Index: This field indicates the number @@ -600,7 +603,7 @@ struct nbft_ssns { } __attribute__((packed)); /** - * enum nbft_ssns_flags - Subsystem and Namespace Specific Flags Field (Figure 16) + * enum nbft_ssns_flags - Subsystem and Namespace Specific Flags Field (Figure 18) * @NBFT_SSNS_VALID: Descriptor Valid: If set to 1h, then this descriptor * is valid. If cleared to 0h, then this descriptor * is not valid. A host that supports NVMe-oF Boot, @@ -677,7 +680,7 @@ enum nbft_ssns_flags { }; /** - * enum nbft_ssns_trflags - SSNS Transport Specific Flags Field (Figure 17) + * enum nbft_ssns_trflags - SSNS Transport Specific Flags Field (Figure 19) * @NBFT_SSNS_TRFLAG_VALID: Transport Specific Flags in Use: If set to 1h, then * this descriptor is valid. If cleared to 0h, then * this descriptor is not valid. @@ -710,7 +713,7 @@ enum nbft_ssns_trflags { /** * struct nbft_ssns_ext_info - Subsystem and Namespace Extended Information - * Descriptor (Figure 19) + * Descriptor (Figure 21) * @structure_id: Structure ID: This field shall be set to 9h * (i.e., SSNS Extended Info; #NBFT_DESC_SSNS_EXT_INFO). * @version: Version: This field shall be set to 1h. @@ -764,7 +767,7 @@ enum nbft_ssns_ext_info_flags { }; /** - * struct nbft_security - Security Profile Descriptor (Figure 21) + * struct nbft_security - Security Profile Descriptor (Figure 22) * @structure_id: Structure ID: This field shall be set to 5h * (i.e., Security; #NBFT_DESC_SECURITY). * @index: Security Profile Descriptor Index: This field indicates @@ -833,7 +836,7 @@ struct nbft_security { }; /** - * enum nbft_security_flags - Security Profile Descriptor Flags (Figure 22) + * enum nbft_security_flags - Security Profile Descriptor Flags (Figure 22/23) * @NBFT_SECURITY_VALID: Descriptor Valid: If set to 1h, then * this descriptor is valid. If cleared * to 0h, then this descriptor is not valid. @@ -944,7 +947,7 @@ enum nbft_security_secret_type { }; /** - * struct nbft_discovery - Discovery Descriptor (Figure 24) + * struct nbft_discovery - Discovery Descriptor (Figure 26) * @structure_id: Structure ID: This field shall be set to 6h * (i.e., Discovery Descriptor; #NBFT_DESC_DISCOVERY). * @flags: Discovery Descriptor Flags, see &enum nbft_discovery_flags. From a94f768da35be2ec0f01f424fb515c14aa4b76f1 Mon Sep 17 00:00:00 2001 From: Daniel Wagner Date: Fri, 29 May 2026 15:27:07 +0200 Subject: [PATCH 10/10] libnvme: consolidate kdoc return text Fix the return documentation where it is outdated due to the way errors are reported with the new API. Use the same wording everywhere. While at it also drop return text for void functions. Signed-off-by: Daniel Wagner --- libnvme/src/nvme/fabrics.h | 47 ++++++++++++++---------------- libnvme/src/nvme/ioctl.h | 28 +++++++++--------- libnvme/src/nvme/lib.h | 2 +- libnvme/src/nvme/linux.h | 32 ++++++++++---------- libnvme/src/nvme/mi-types.h | 12 ++++---- libnvme/src/nvme/mi.h | 46 ++++++++++++++--------------- libnvme/src/nvme/nbft.h | 2 +- libnvme/src/nvme/nvme-cmds-base.h | 10 ++----- libnvme/src/nvme/nvme-cmds-nvm.h | 5 ++-- libnvme/src/nvme/nvme-cmds.h | 8 ++--- libnvme/src/nvme/nvme-types-base.h | 28 +++++++++--------- libnvme/src/nvme/private-fabrics.h | 6 ++-- libnvme/src/nvme/private.h | 4 +-- libnvme/src/nvme/tree.h | 30 +++++++++---------- libnvme/src/nvme/util.h | 4 +-- 15 files changed, 127 insertions(+), 137 deletions(-) diff --git a/libnvme/src/nvme/fabrics.h b/libnvme/src/nvme/fabrics.h index 5dabdccaaf..4344ef0428 100644 --- a/libnvme/src/nvme/fabrics.h +++ b/libnvme/src/nvme/fabrics.h @@ -139,7 +139,7 @@ const char *libnvmf_cms_str(__u8 cms); * into the topology using @h as parent. * @c must be initialized and not connected to the topology. * - * Return: 0 on success, or an error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_add_ctrl(libnvme_host_t h, libnvme_ctrl_t c); @@ -150,7 +150,7 @@ int libnvmf_add_ctrl(libnvme_host_t h, libnvme_ctrl_t c); * Issues a 'connect' command to the NVMe-oF controller. * @c must be initialized and not connected to the topology. * - * Return: 0 on success, or an error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_connect_ctrl(libnvme_ctrl_t c); @@ -177,7 +177,7 @@ struct libnvmf_uri; * Issues the three-phase Get Log Page protocol against @ctrl, validates * generation-counter atomicity, and normalises each log entry. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_get_discovery_log(libnvme_ctrl_t ctrl, const struct libnvmf_discovery_args *args, @@ -210,7 +210,7 @@ bool libnvmf_is_registration_supported(libnvme_ctrl_t c); * Perform registration task with a Discovery Controller (DC). Three * tasks are supported: register, deregister, and registration update. * - * Return: 0 on success, or an error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_register_ctrl(libnvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result); @@ -224,7 +224,7 @@ int libnvmf_register_ctrl(libnvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result * * nvme+tcp://user@host:port/subsys_nqn/nid?query=val#fragment * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_uri_parse(const char *str, struct libnvmf_uri **uri); @@ -261,7 +261,7 @@ const char *libnvmf_get_default_trsvcid(const char *transport, * Allocates and initializes a new fabrics context for discovery/connect * operations. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_create(struct libnvme_global_ctx *ctx, bool (*decide_retry)(struct libnvmf_context *fctx, int err, @@ -295,7 +295,7 @@ void libnvmf_context_free(struct libnvmf_context *fctx); * * Sets the hooks used during discovery operations for the given context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_discovery_hooks(struct libnvmf_context *fctx, void (*discovery_log)(struct libnvmf_context *fctx, @@ -308,7 +308,6 @@ int libnvmf_context_set_discovery_hooks(struct libnvmf_context *fctx, int (*parser_next_line)(struct libnvmf_context *fctx, void *user_data)); - /** * libnvmf_context_set_connection() - Set connection parameters for context * @fctx: Fabrics context @@ -321,7 +320,7 @@ int libnvmf_context_set_discovery_hooks(struct libnvmf_context *fctx, * * Sets the connection parameters for the context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_connection(struct libnvmf_context *fctx, const char *subsysnqn, const char *transport, @@ -336,7 +335,7 @@ int libnvmf_context_set_connection(struct libnvmf_context *fctx, * * Sets the host NQN and host ID for the context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_hostnqn(struct libnvmf_context *fctx, const char *hostnqn, const char *hostid); @@ -352,14 +351,13 @@ int libnvmf_context_set_hostnqn(struct libnvmf_context *fctx, * * Sets cryptographic and TLS parameters for the context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_crypto(struct libnvmf_context *fctx, const char *hostkey, const char *ctrlkey, const char *keyring, const char *tls_key, const char *tls_key_identity); - /** * libnvmf_context_set_device() - Set device for context * @fctx: Fabrics context @@ -367,7 +365,7 @@ int libnvmf_context_set_crypto(struct libnvmf_context *fctx, * * Sets the device to be used by the context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_device(struct libnvmf_context *fctx, const char *device); @@ -390,7 +388,7 @@ int libnvmf_context_set_device(struct libnvmf_context *fctx, const char *device) * _set_nr_poll_queues(), _set_queue_size(), and _set_disable_sqflow() * accessors are also available when only a subset needs to change. * - * Return: 0 + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_io_queues(struct libnvmf_context *fctx, int nr_io_queues, int nr_write_queues, int nr_poll_queues, @@ -415,12 +413,11 @@ int libnvmf_context_set_io_queues(struct libnvmf_context *fctx, * and _set_fast_io_fail_tmo() accessors are also available when only a * subset needs to change. * - * Return: 0 + * Return: 0 on success, negative error code otherwise. */ int libnvmf_context_set_reconnect_policy(struct libnvmf_context *fctx, int ctrl_loss_tmo, int reconnect_delay, int fast_io_fail_tmo); - /** * libnvmf_discovery() - Perform fabrics discovery * @ctx: Global context @@ -430,7 +427,7 @@ int libnvmf_context_set_reconnect_policy(struct libnvmf_context *fctx, * * Performs discovery for fabrics subsystems and optionally connects. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_discovery(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force); @@ -444,7 +441,7 @@ int libnvmf_discovery(struct libnvme_global_ctx *ctx, * * Performs discovery using a JSON configuration. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_discovery_config_json(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force); @@ -458,7 +455,7 @@ int libnvmf_discovery_config_json(struct libnvme_global_ctx *ctx, * * Performs discovery using a configuration file. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_discovery_config_file(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force); @@ -472,7 +469,7 @@ int libnvmf_discovery_config_file(struct libnvme_global_ctx *ctx, * * Performs discovery using the specified NBFT file. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_discovery_nbft(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, char *nbft_path); @@ -485,7 +482,7 @@ int libnvmf_discovery_nbft(struct libnvme_global_ctx *ctx, * * Creates an unconnected controller to be used for libnvme_add_ctrl(). * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvmf_create_ctrl(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, libnvme_ctrl_t *c); @@ -497,7 +494,7 @@ int libnvmf_create_ctrl(struct libnvme_global_ctx *ctx, * * Connects to the fabrics subsystem using the provided context. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_connect(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx); @@ -519,7 +516,7 @@ int libnvmf_disconnect_ctrl(libnvme_ctrl_t c); * * Connects to the fabrics subsystem using a JSON configuration. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_connect_config_json(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx); @@ -532,7 +529,7 @@ int libnvmf_connect_config_json(struct libnvme_global_ctx *ctx, * Update the current configuration by adding the crypto * information. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_config_modify(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx); @@ -547,7 +544,7 @@ struct nbft_file_entry; * * Reads NBFT files from the specified path and populates a linked list. * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_nbft_read_files(struct libnvme_global_ctx *ctx, char *path, struct nbft_file_entry **head); diff --git a/libnvme/src/nvme/ioctl.h b/libnvme/src/nvme/ioctl.h index 8e53f18193..30d9c9b841 100644 --- a/libnvme/src/nvme/ioctl.h +++ b/libnvme/src/nvme/ioctl.h @@ -33,8 +33,8 @@ * * Uses LIBNVME_IOCTL_ADMIN_CMD for the ioctl request. * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. + * Return: The nvme command status if a response was received (see + * &enum nvme_status_field), or negative error code otherwise. */ int libnvme_submit_admin_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd); @@ -49,7 +49,7 @@ int libnvme_submit_admin_passthru(struct libnvme_transport_handle *hdl, * * This is a no-op when io_uring is not available. * - * Return: 0 on success or a negative error code otherwise. + * Return: 0 on success, negative error code otherwise. */ int libnvme_wait_admin_passthru(struct libnvme_transport_handle *hdl); @@ -63,8 +63,8 @@ int libnvme_wait_admin_passthru(struct libnvme_transport_handle *hdl); * for the common case where commands are sent one at a time. Use the * split-phase API directly when batching multiple commands with io_uring. * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. + * Return: The nvme command status if a response was received (see + * &enum nvme_status_field), or negative error code otherwise. */ static inline int libnvme_exec_admin_passthru( struct libnvme_transport_handle *hdl, @@ -81,8 +81,8 @@ static inline int libnvme_exec_admin_passthru( * * Uses LIBNVME_IOCTL_IO_CMD for the ioctl request. * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. + * Return: The nvme command status if a response was received (see + * &enum nvme_status_field), or negative error code otherwise. */ int libnvme_submit_io_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd); @@ -94,7 +94,7 @@ int libnvme_submit_io_passthru(struct libnvme_transport_handle *hdl, * Counterpart to libnvme_submit_io_passthru() for the split-phase API. * Currently a no-op as the IO passthru path does not yet use io_uring. * - * Return: 0 on success or a negative error code otherwise. + * Return: 0 on success, negative error code otherwise. */ int libnvme_wait_io_passthru(struct libnvme_transport_handle *hdl); @@ -106,8 +106,8 @@ int libnvme_wait_io_passthru(struct libnvme_transport_handle *hdl); * Convenience wrapper combining libnvme_submit_io_passthru() and * libnvme_wait_io_passthru() into a single synchronous call. * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. + * Return: The nvme command status if a response was received (see + * &enum nvme_status_field), or negative error code otherwise. */ static inline int libnvme_exec_io_passthru( struct libnvme_transport_handle *hdl, @@ -123,7 +123,7 @@ static inline int libnvme_exec_io_passthru( * * This should only be sent to controller handles, not to namespaces. * - * Return: Zero if a subsystem reset was initiated or -1 with errno set + * Return: Zero if a subsystem reset was initiated or negative error code * otherwise. */ int libnvme_reset_subsystem(struct libnvme_transport_handle *hdl); @@ -134,7 +134,7 @@ int libnvme_reset_subsystem(struct libnvme_transport_handle *hdl); * * This should only be sent to controller handles, not to namespaces. * - * Return: 0 if a reset was initiated or -1 with errno set otherwise. + * Return: 0 if a reset was initiated or negative error code otherwise. */ int libnvme_reset_ctrl(struct libnvme_transport_handle *hdl); @@ -144,7 +144,7 @@ int libnvme_reset_ctrl(struct libnvme_transport_handle *hdl); * * This should only be sent to controller handles, not to namespaces. * - * Return: 0 if a rescan was initiated or -1 with errno set otherwise. + * Return: 0 if a rescan was initiated or negative error code otherwise. */ int libnvme_rescan_ns(struct libnvme_transport_handle *hdl); @@ -158,7 +158,7 @@ int libnvme_rescan_ns(struct libnvme_transport_handle *hdl); * for many architectures that are incapable of allowing distinguishing a * namespace id > 0x80000000 from a negative error number. * - * Return: 0 if @nsid was set successfully or -1 with errno set otherwise. + * Return: 0 if @nsid was set successfully or negative error code otherwise. */ int libnvme_get_nsid(struct libnvme_transport_handle *hdl, __u32 *nsid); diff --git a/libnvme/src/nvme/lib.h b/libnvme/src/nvme/lib.h index 8df8e9f1fd..863e71f661 100644 --- a/libnvme/src/nvme/lib.h +++ b/libnvme/src/nvme/lib.h @@ -75,7 +75,7 @@ int libnvme_get_logging_level(struct libnvme_global_ctx *ctx, bool *log_pid, * This will look for the handle in /dev/ and validate the name and filetype * match linux conventions. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_open(struct libnvme_global_ctx *ctx, const char *name, struct libnvme_transport_handle **hdl); diff --git a/libnvme/src/nvme/linux.h b/libnvme/src/nvme/linux.h index aa0693a64b..08ac232626 100644 --- a/libnvme/src/nvme/linux.h +++ b/libnvme/src/nvme/linux.h @@ -57,7 +57,7 @@ int libnvme_gen_dhchap_key(struct libnvme_global_ctx *ctx, * * Looks up the serial number of the keyring @keyring. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_lookup_keyring(struct libnvme_global_ctx *ctx, const char *keyring, long *key); @@ -86,7 +86,7 @@ char *libnvme_describe_key_serial(struct libnvme_global_ctx *ctx, * Looks up the serial number of the key @identity * with type %type in the current session keyring. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_lookup_key(struct libnvme_global_ctx *ctx, const char *type, const char *identity, long *key); @@ -99,7 +99,7 @@ int libnvme_lookup_key(struct libnvme_global_ctx *ctx, const char *type, * Links @keyring_id into the session keyring such that * its keys are available for further key lookups. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_set_keyring(struct libnvme_global_ctx *ctx, long keyring_id); @@ -116,7 +116,7 @@ int libnvme_set_keyring(struct libnvme_global_ctx *ctx, long keyring_id); * The generated raw secret can subsequently be passed to libnvme_read_key() * or libnvme_update_key(). * - * Return: 0 on success, or a negative error code on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvme_create_raw_secret(struct libnvme_global_ctx *ctx, const char *secret, size_t key_len, unsigned char **raw_secret); @@ -134,7 +134,7 @@ int libnvme_create_raw_secret(struct libnvme_global_ctx *ctx, * @len holds the size of the returned buffer. * If @keyring is 0 the default keyring '.nvme' is used. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_read_key(struct libnvme_global_ctx *ctx, long keyring_id, long key_id, int *len, unsigned char **key); @@ -154,7 +154,7 @@ int libnvme_read_key(struct libnvme_global_ctx *ctx, long keyring_id, * The old key with identity @identity will be revoked to make it * inaccessible. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_update_key(struct libnvme_global_ctx *ctx, long keyring_id, const char *key_type, const char *identity, @@ -207,7 +207,7 @@ int libnvme_scan_tls_keys(struct libnvme_global_ctx *ctx, const char *keyring, * Derives a 'retained' TLS key as specified in NVMe TCP 1.0a and * stores it as type @key_type in the keyring specified by @keyring. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_insert_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, @@ -231,7 +231,7 @@ int libnvme_insert_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, * @version s set to '0') or NVMe TP8028 (if @version is set to '1) and * stores it as type @key_type in the keyring specified by @keyring. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_insert_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, @@ -286,7 +286,7 @@ int libnvme_insert_tls_key_compat(struct libnvme_global_ctx *ctx, * * It is the responsibility of the caller to free the returned string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_generate_tls_key_identity(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, @@ -313,7 +313,7 @@ int libnvme_generate_tls_key_identity(struct libnvme_global_ctx *ctx, * * It is the responsibility of the caller to free the returned string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_generate_tls_key_identity_compat(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, @@ -327,7 +327,7 @@ int libnvme_generate_tls_key_identity_compat(struct libnvme_global_ctx *ctx, * @key_type: Type of the key to revoke * @identity: Key identity string * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_revoke_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *identity); @@ -345,7 +345,7 @@ int libnvme_revoke_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, * It is the responsibility of the caller to free the returned * string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_export_tls_key(struct libnvme_global_ctx *ctx, const unsigned char *key_data, int key_len, char **identity); @@ -366,7 +366,7 @@ int libnvme_export_tls_key(struct libnvme_global_ctx *ctx, * It is the responsibility of the caller to free the returned * string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_export_tls_key_versioned(struct libnvme_global_ctx *ctx, unsigned char version, unsigned char hmac, @@ -386,7 +386,7 @@ int libnvme_export_tls_key_versioned(struct libnvme_global_ctx *ctx, * * It is the responsibility of the caller to free the returned string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_import_tls_key(struct libnvme_global_ctx *ctx, const char *encoded_key, int *key_len, unsigned int *hmac, @@ -407,7 +407,7 @@ int libnvme_import_tls_key(struct libnvme_global_ctx *ctx, * * It is the responsibility of the caller to free the returned string. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_import_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *encoded_key, unsigned char *version, @@ -415,7 +415,7 @@ int libnvme_import_tls_key_versioned(struct libnvme_global_ctx *ctx, /** * libnvme_generate_hostnqn() - Generate a machine specific host nqn - * Returns: An nvm namespace qualified name string based on the machine + * Return: An nvm namespace qualified name string based on the machine * identifier, or NULL if not successful. */ char *libnvme_generate_hostnqn(void); diff --git a/libnvme/src/nvme/mi-types.h b/libnvme/src/nvme/mi-types.h index c223c9140b..5dd60b7ff6 100644 --- a/libnvme/src/nvme/mi-types.h +++ b/libnvme/src/nvme/mi-types.h @@ -302,7 +302,7 @@ struct nvme_mi_aem_supported_item { * nvme_mi_aem_aesi_get_aese() - return aese from aesi field * @aesi: aesi field from @nvme_mi_aem_supported_item * - * Returns: A bool representing the aese value + * Return: A bool representing the aese value */ bool nvme_mi_aem_aesi_get_aese(__le16 aesi); @@ -310,7 +310,7 @@ bool nvme_mi_aem_aesi_get_aese(__le16 aesi); * nvme_mi_aem_aesi_get_aesid() - return aesid from aesi field * @aesi: aesi field from @nvme_mi_aem_supported_item * - * Returns: aesid value + * Return: aesid value */ __u8 nvme_mi_aem_aesi_get_aesid(__le16 aesi); @@ -354,7 +354,7 @@ struct nvme_mi_aem_enable_item { * nvme_mi_aem_aeei_get_aee() - return aee from aeei field * @aeei: aeei field from @nvme_mi_aem_enable_item * - * Returns: aee value + * Return: aee value */ bool nvme_mi_aem_aeei_get_aee(__le16 aeei); @@ -362,7 +362,7 @@ bool nvme_mi_aem_aeei_get_aee(__le16 aeei); * nvme_mi_aem_aeei_get_aeeid() - return aeeid from aeei field * @aeei: aeei field from @nvme_mi_aem_enable_item * - * Returns: aeeid value + * Return: aeeid value */ __u8 nvme_mi_aem_aeei_get_aeeid(__le16 aeei); @@ -453,7 +453,7 @@ struct nvme_mi_aem_occ_list_hdr { * nvme_mi_aem_aemti_get_aemgn() - return aemgn from aemti field * @aemti: aemti field from @nvme_mi_aem_occ_list_hdr * - * Returns: aemgn value + * Return: aemgn value */ __u8 nvme_mi_aem_aemti_get_aemgn(__u8 aemti); @@ -461,7 +461,7 @@ __u8 nvme_mi_aem_aemti_get_aemgn(__u8 aemti); * nvme_mi_aem_aeolli_get_aeoltl() - return aeoltl from aeolli field * @aeolli: Pointer to 3 byte aeolli field from @nvme_mi_aem_occ_list_hdr * - * Returns: aeoltl value + * Return: aeoltl value */ __u32 nvme_mi_aem_aeolli_get_aeoltl(__u8 *aeolli); diff --git a/libnvme/src/nvme/mi.h b/libnvme/src/nvme/mi.h index 7704af9f28..dbd908ce0c 100644 --- a/libnvme/src/nvme/mi.h +++ b/libnvme/src/nvme/mi.h @@ -96,7 +96,7 @@ * * Returned string is const, and should not be free()ed. * - * Returns: A string representing the status value + * Return: A string representing the status value */ const char *libnvme_mi_status_to_string(int status); @@ -325,7 +325,7 @@ struct libnvme_global_ctx *libnvme_mi_scan_mctp(void); * hold a reference to those across this call. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise. + * &enum nvme_status_field) or negative error code otherwise. * * See: &libnvme_mi_for_each_ctrl */ @@ -396,7 +396,7 @@ char *libnvme_mi_endpoint_desc(libnvme_mi_ep_t ep); * See: &struct nvme_mi_mi_req_hdr and &struct nvme_mi_mi_resp_hdr. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_xfer(libnvme_mi_ep_t ep, struct nvme_mi_mi_req_hdr *mi_req, @@ -414,7 +414,7 @@ int libnvme_mi_mi_xfer(libnvme_mi_ep_t ep, * NVMe version information. See &struct nvme_mi_read_nvm_ss_info. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_read_mi_data_subsys(libnvme_mi_ep_t ep, struct nvme_mi_read_nvm_ss_info *s); @@ -433,7 +433,7 @@ int libnvme_mi_mi_read_mi_data_subsys(libnvme_mi_ep_t ep, * See &struct nvme_mi_read_port_info. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_read_mi_data_port(libnvme_mi_ep_t ep, __u8 portid, struct nvme_mi_read_port_info *p); @@ -451,7 +451,7 @@ int libnvme_mi_mi_read_mi_data_port(libnvme_mi_ep_t ep, __u8 portid, * See &struct nvme_ctrl_list. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_read_mi_data_ctrl_list(libnvme_mi_ep_t ep, __u8 start_ctrlid, struct nvme_ctrl_list *list); @@ -469,7 +469,7 @@ int libnvme_mi_mi_read_mi_data_ctrl_list(libnvme_mi_ep_t ep, __u8 start_ctrlid, * See &struct nvme_mi_read_ctrl_info. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_read_mi_data_ctrl(libnvme_mi_ep_t ep, __u16 ctrl_id, struct nvme_mi_read_ctrl_info *ctrl); @@ -488,7 +488,7 @@ int libnvme_mi_mi_read_mi_data_ctrl(libnvme_mi_ep_t ep, __u16 ctrl_id, * See &struct nvme_mi_nvm_ss_health_status. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_subsystem_health_status_poll(libnvme_mi_ep_t ep, bool clear, struct nvme_mi_nvm_ss_health_status *nshds); @@ -511,7 +511,7 @@ int libnvme_mi_mi_subsystem_health_status_poll(libnvme_mi_ep_t ep, bool clear, * See &enum nvme_mi_config_id for identifiers. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_config_get(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1, __u32 *nmresp); @@ -529,7 +529,7 @@ int libnvme_mi_mi_config_get(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1, * See &enum nvme_mi_config_id for identifiers. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_config_set(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1); @@ -544,7 +544,7 @@ int libnvme_mi_mi_config_set(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1); * frequency * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ static inline int libnvme_mi_mi_config_get_smbus_freq(libnvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq *freq) @@ -573,7 +573,7 @@ static inline int libnvme_mi_mi_config_get_smbus_freq(libnvme_mi_ep_t ep, __u8 p * for the port. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ static inline int libnvme_mi_mi_config_set_smbus_freq(libnvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq freq) @@ -599,7 +599,7 @@ static inline int libnvme_mi_mi_config_set_smbus_freq(libnvme_mi_ep_t ep, __u8 p * values in @mask. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ static inline int libnvme_mi_mi_config_set_health_status_change(libnvme_mi_ep_t ep, __u32 mask) @@ -624,7 +624,7 @@ static inline int libnvme_mi_mi_config_set_health_status_change(libnvme_mi_ep_t * may not accept MCTP messages larger than the configured MTU. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ static inline int libnvme_mi_mi_config_get_mctp_mtu(libnvme_mi_ep_t ep, __u8 port, __u16 *mtu) @@ -655,7 +655,7 @@ static inline int libnvme_mi_mi_config_get_mctp_mtu(libnvme_mi_ep_t ep, __u8 por * interface(s) to match. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ static inline int libnvme_mi_mi_config_set_mctp_mtu(libnvme_mi_ep_t ep, __u8 port, __u16 mtu) @@ -678,7 +678,7 @@ static inline int libnvme_mi_mi_config_set_mctp_mtu(libnvme_mi_ep_t ep, __u8 por * Events. On success, populates @aeelver and the @list with current info, * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_config_get_async_event(libnvme_mi_ep_t ep, __u8 *aeelver, @@ -709,7 +709,7 @@ int libnvme_mi_mi_config_get_async_event(libnvme_mi_ep_t ep, * ACK versus Sync conditions * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_mi_config_set_async_event(libnvme_mi_ep_t ep, bool envfa, @@ -766,7 +766,7 @@ static inline int libnvme_mi_aem_ack(libnvme_mi_ep_t ep, * See: &struct nvme_mi_admin_req_hdr and &struct nvme_mi_admin_resp_hdr. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise.. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_admin_xfer(struct libnvme_transport_handle *hdl, struct nvme_mi_admin_req_hdr *admin_req, @@ -785,7 +785,7 @@ int libnvme_mi_admin_xfer(struct libnvme_transport_handle *hdl, * Perform a Control Primitive command, using the opcode specified in @opcode * Stores the result from the CPSR field in @result_cpsr if set. * - * Return: 0 on success, non-zero on failure + * Return: 0 on success, negative error code otherwise. * * See: &enum nvme_mi_control_opcode * @@ -908,7 +908,7 @@ int libnvme_mi_aem_get_fd(libnvme_mi_ep_t ep); * At this point the application can call libnvme_mi_aem_get_next_event() to get information for * each triggered event. * - * Return: 0 is a success, nonzero is an error and errno may be read for further details + * Return: 0 on success, negative error code otherwise. */ int libnvme_mi_aem_enable(libnvme_mi_ep_t ep, struct libnvme_mi_aem_config *config, @@ -920,7 +920,7 @@ int libnvme_mi_aem_enable(libnvme_mi_ep_t ep, * @ep: Endpoint to check enabled status * @enabled: libnvme_mi_aem_enabled_map indexed by AE event ID of enabled state * - * Return: 0 is a success, nonzero is an error and errno may be read for further details + * Return: 0 on success, negative error code otherwise. */ int libnvme_mi_aem_get_enabled(libnvme_mi_ep_t ep, struct libnvme_mi_aem_enabled_map *enabled); @@ -929,7 +929,7 @@ int libnvme_mi_aem_get_enabled(libnvme_mi_ep_t ep, * libnvme_mi_aem_disable() - Disable AE on the provided endpoint * @ep: Endpoint to disable AEs * - * Return: 0 is a success, nonzero is an error and errno may be read for further details + * Return: 0 on success, negative error code otherwise. */ int libnvme_mi_aem_disable(libnvme_mi_ep_t ep); @@ -944,7 +944,7 @@ int libnvme_mi_aem_disable(libnvme_mi_ep_t ep); * application can call libnvme_mi_aem_get_next_event() from within this callback to get * aem event data. The callback function should return NVME_MI_AEM_HNA_ACK for normal operation. * - * Return: 0 is a success, nonzero is an error and errno may be read for further details + * Return: 0 on success, negative error code otherwise. */ int libnvme_mi_aem_process(libnvme_mi_ep_t ep, void *userdata); diff --git a/libnvme/src/nvme/nbft.h b/libnvme/src/nvme/nbft.h index 49caa277c4..f9c6a572f0 100644 --- a/libnvme/src/nvme/nbft.h +++ b/libnvme/src/nvme/nbft.h @@ -255,7 +255,7 @@ struct libnbft_info { * Read and parse the specified NBFT file into a struct libnbft_info. * Free with libnvmf_free_nbft(). * - * Return: 0 on success, errno otherwise. + * Return: 0 on success, negative error code otherwise. */ int libnvmf_read_nbft(struct libnvme_global_ctx *ctx, struct libnbft_info **nbft, const char *filename); diff --git a/libnvme/src/nvme/nvme-cmds-base.h b/libnvme/src/nvme/nvme-cmds-base.h index f1b929c2fc..33af015724 100644 --- a/libnvme/src/nvme/nvme-cmds-base.h +++ b/libnvme/src/nvme/nvme-cmds-base.h @@ -1746,9 +1746,6 @@ nvme_init_identify_domain_list(struct libnvme_passthru_cmd *cmd, * @cmd: Command data structure to initialize * @enggid: Endurance group identifier * @list: Array of endurance group identifiers - * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. */ static inline void nvme_init_identify_endurance_group_id(struct libnvme_passthru_cmd *cmd, @@ -1811,9 +1808,6 @@ nvme_init_identify_csi_id_ns_data_structure(struct libnvme_passthru_cmd *cmd, * * Retrieves list of the controller's supported io command set vectors. See * &struct nvme_id_iocs. - * - * Return: 0 on success, the nvme command status if a response was - * received (see &enum nvme_status_field) or a negative error otherwise. */ static inline void nvme_init_identify_command_set_structure(struct libnvme_passthru_cmd *cmd, @@ -3244,7 +3238,7 @@ nvme_init_fw_commit(struct libnvme_passthru_cmd *cmd, __u8 fs, * * Note: Caller must ensure data_len and offset are DWord-aligned (0x4). * - * Returns: 0 on success, or error code if arguments are invalid. + * Return: 0 on success, negative error code otherwise. */ static inline int nvme_init_fw_download(struct libnvme_passthru_cmd *cmd, void *data, @@ -3562,7 +3556,7 @@ nvme_init_directive_recv_stream_allocate(struct libnvme_passthru_cmd *cmd, * Initializes the passthru command buffer for the Directive Receive - Stream * Status command. * - * Return: 0 on success, or error code if arguments are invalid. + * Return: 0 on success, negative error code otherwise. */ static inline int nvme_init_directive_recv_stream_status(struct libnvme_passthru_cmd *cmd, diff --git a/libnvme/src/nvme/nvme-cmds-nvm.h b/libnvme/src/nvme/nvme-cmds-nvm.h index 6d1aa1fa93..5e29a1fc94 100644 --- a/libnvme/src/nvme/nvme-cmds-nvm.h +++ b/libnvme/src/nvme/nvme-cmds-nvm.h @@ -724,9 +724,6 @@ nvme_init_app_tag(struct libnvme_passthru_cmd *cmd, * * Each array must be the same size of size 'nr_ranges'. This is intended to be * used with constructing a payload for nvme_dsm(). - * - * Return: The nvme command status if a response was received or -errno - * otherwise. */ static inline void nvme_init_dsm_range(struct nvme_dsm_range *dsm, __u32 *ctx_attrs, @@ -871,6 +868,8 @@ nvme_init_copy_range_f3(struct nvme_copy_range_f3 *copy, __u32 *snsids, * Initializes the passthru command buffer fields cdw2, cdw3, and cdw14 * for commands supporting Extended LBA. This logic is usually called from * the command-specific init function (like nvme_init_zns_append). + * + * Return: 0 on success, -EINVAL otherwise. */ static inline int nvme_init_var_size_tags(struct libnvme_passthru_cmd *cmd, diff --git a/libnvme/src/nvme/nvme-cmds.h b/libnvme/src/nvme/nvme-cmds.h index f9d4d7f7c9..ee140c7354 100644 --- a/libnvme/src/nvme/nvme-cmds.h +++ b/libnvme/src/nvme/nvme-cmds.h @@ -53,7 +53,7 @@ int libnvme_get_log(struct libnvme_transport_handle *hdl, * behavior support feature had been changed * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_set_etdas(struct libnvme_transport_handle *hdl, bool *changed); @@ -65,7 +65,7 @@ int libnvme_set_etdas(struct libnvme_transport_handle *hdl, bool *changed); * behavior support feature had been changed * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_clear_etdas(struct libnvme_transport_handle *hdl, bool *changed); @@ -75,7 +75,7 @@ int libnvme_clear_etdas(struct libnvme_transport_handle *hdl, bool *changed); * @uuid_list: UUID list returned by identify UUID * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_get_uuid_list(struct libnvme_transport_handle *hdl, struct nvme_id_uuid_list *uuid_list); @@ -193,7 +193,7 @@ size_t libnvme_get_ana_log_len_from_id_ctrl(const struct nvme_id_ctrl *id_ctrl, * * Return: If successful, returns 0 and sets *len to the actual log page length. * If unsuccessful, returns the nvme command status if a response was received - * (see &enum nvme_status_field) or -1 with errno set otherwise. + * (see &enum nvme_status_field) or negative error code otherwise. * Sets errno = EINVAL if retries == 0. * Sets errno = EAGAIN if unable to read the log page atomically * because chgcnt changed during each of the retries attempts. diff --git a/libnvme/src/nvme/nvme-types-base.h b/libnvme/src/nvme/nvme-types-base.h index ea781b7ae5..2c43d0c8bd 100644 --- a/libnvme/src/nvme/nvme-types-base.h +++ b/libnvme/src/nvme/nvme-types-base.h @@ -49,7 +49,7 @@ * applied after the shift to isolate a specific set of bits that decode to a * sub-field. * - * Returns: The 'name' field from 'value' + * Return: The 'name' field from 'value' */ #define NVME_GET(value, name) \ (((value) >> NVME_##name##_SHIFT) & NVME_##name##_MASK) @@ -59,7 +59,7 @@ * @value: The value to be set in its completed position * @name: The name of the sub-field within an nvme value * - * Returns: The 'name' field from 'value' + * Return: The 'name' field from 'value' */ #define NVME_SET(value, name) \ (((__u32)(value) & NVME_##name##_MASK) << NVME_##name##_SHIFT) @@ -94,7 +94,7 @@ * @name: The name of the sub-field within an nvme value * @check: The sub-field value to check * - * Returns: The result of compare the value and the sub-field value + * Return: The result of compare the value and the sub-field value */ #define NVME_CHECK(value, name, check) ((value) == NVME_##name##_##check) @@ -102,7 +102,7 @@ * NVME_VAL() - get mask value shifted * @name: The name of the sub-field within an nvme value * - * Returns: The mask value shifted + * Return: The mask value shifted */ #define NVME_VAL(name) (NVME_##name##_MASK << NVME_##name##_SHIFT) @@ -281,7 +281,7 @@ enum nvme_register_offsets { * specific transport. For example, BPMBL(Boot Partition Memory Buffer * Location) register is not supported by fabrics, but it can be checked here. * - * Returns: true if given offset is 64bit register, otherwise it returns false. + * Return: true if given offset is 64bit register, otherwise it returns false. */ static inline bool nvme_is_64bit_reg(__u32 offset) { @@ -685,7 +685,7 @@ enum nvme_cmbsz { * nvme_cmb_size() - Calculate size of the controller memory buffer * @cmbsz: Value from controller register %NVME_REG_CMBSZ * - * Returns: size of controller memory buffer in bytes + * Return: size of controller memory buffer in bytes */ static inline __u64 nvme_cmb_size(__u32 cmbsz) { @@ -1000,7 +1000,7 @@ enum nvme_pmrebs { * buffer * @pmrebs: Value from controller register %NVME_REG_PMREBS * - * Returns: size of controller persistent memory buffer in bytes + * Return: size of controller persistent memory buffer in bytes */ static inline __u64 nvme_pmr_size(__u32 pmrebs) { @@ -1037,7 +1037,7 @@ enum nvme_pmrswtp { * nvme_pmr_throughput() - Calculate throughput of persistent memory buffer * @pmrswtp: Value from controller register %NVME_REG_PMRSWTP * - * Returns: throughput of controller persistent memory buffer in bytes/second + * Return: throughput of controller persistent memory buffer in bytes/second */ static inline __u64 nvme_pmr_throughput(__u32 pmrswtp) { @@ -1145,7 +1145,7 @@ enum nvme_power_measurement_action { * nvme_psd_power_scale() - power scale occupies the upper 3 bits * @ps: power scale value * - * Returns: power scale value + * Return: power scale value */ static inline unsigned int nvme_psd_power_scale(__u8 ps) { @@ -6999,7 +6999,7 @@ enum nvme_status_field { * @status_field: The NVMe Completion Queue Entry's Status Field * See &enum nvme_status_field * - * Returns: status code type + * Return: status code type */ static inline __u16 nvme_status_code_type(__u16 status_field) { @@ -7011,7 +7011,7 @@ static inline __u16 nvme_status_code_type(__u16 status_field) * @status_field: The NVMe Completion Queue Entry's Status Field * See &enum nvme_status_field * - * Returns: status code + * Return: status code */ static inline __u16 nvme_status_code(__u16 status_field) { @@ -7051,7 +7051,7 @@ enum nvme_status_type { * nvme_status_get_type() - extract the type from a nvme_* return value * @status: the (non-negative) return value from the NVMe API * - * Returns: the type component of the status. + * Return: the type component of the status. */ static inline __u32 nvme_status_get_type(int status) { @@ -7063,7 +7063,7 @@ static inline __u32 nvme_status_get_type(int status) * value * @status: the (non-negative) return value from the NVMe API * - * Returns: the value component of the status; the set of values will depend + * Return: the value component of the status; the set of values will depend * on the status type. */ static inline __u32 nvme_status_get_value(int status) @@ -7077,7 +7077,7 @@ static inline __u32 nvme_status_get_value(int status) * @type: the status type * @value: the status value * - * Returns: true if @status is of the specified type and value + * Return: true if @status is of the specified type and value */ static inline __u32 nvme_status_equals(int status, enum nvme_status_type type, unsigned int value) diff --git a/libnvme/src/nvme/private-fabrics.h b/libnvme/src/nvme/private-fabrics.h index 34af13c48a..712a285b37 100644 --- a/libnvme/src/nvme/private-fabrics.h +++ b/libnvme/src/nvme/private-fabrics.h @@ -111,7 +111,7 @@ struct libnvmf_uri { // !generate-accessors * libnvmf_exat_len() - Return length rounded up by 4 * @val_len: Value length * - * Return the size in bytes, rounded to a multiple of 4 (e.g., size of + * Calculate the size in bytes, rounded to a multiple of 4 (e.g., size of * __u32), of the buffer needed to hold the exat value of size * @val_len. * @@ -127,7 +127,7 @@ static inline __u16 libnvmf_exat_len(size_t val_len) * @val_len: This is the length of the data to be copied to the "exatval" * field of a "struct nvmf_ext_attr". * - * Return the size of the "struct nvmf_ext_attr" needed to hold + * Calculate the size of the "struct nvmf_ext_attr" needed to hold * a value of size @val_len. * * Return: The size in bytes, rounded to a multiple of 4 (i.e. size of @@ -150,7 +150,7 @@ static inline __u16 libnvmf_exat_size(size_t val_len) * on the returned data. The cache will be freed when the global * context is freed. * - * Return: Pointer to I/F data, NULL on error (with errno set). + * Return: Pointer to I/F data, NULL on error. */ const struct ifaddrs *libnvmf_getifaddrs(struct libnvme_global_ctx *ctx); #endif /* HAVE_NETDB || CONFIG_FABRICS */ diff --git a/libnvme/src/nvme/private.h b/libnvme/src/nvme/private.h index a9c2e9efc6..2596738e2c 100644 --- a/libnvme/src/nvme/private.h +++ b/libnvme/src/nvme/private.h @@ -643,7 +643,7 @@ char *kv_keymatch(const char *kv, const char *key); * remain cached until the ns object is deleted or * libnvme_ns_release_transport_handle() is called. * - * Return: On success 0, else error code. + * Return: 0 on success, negative error code otherwise. */ int libnvme_ns_get_transport_handle(struct libnvme_ns *n, struct libnvme_transport_handle **hdl); @@ -669,7 +669,7 @@ void libnvme_ns_release_transport_handle(struct libnvme_ns *n); * so the & data_len parameter must be less than 4097. * * Return: The nvme command status if a response was received (see - * &enum nvme_status_field) or -1 with errno set otherwise. + * &enum nvme_status_field) or negative error code otherwise. */ int libnvme_mi_admin_admin_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd); diff --git a/libnvme/src/nvme/tree.h b/libnvme/src/nvme/tree.h index e3aa0af563..a81dd36db2 100644 --- a/libnvme/src/nvme/tree.h +++ b/libnvme/src/nvme/tree.h @@ -125,7 +125,7 @@ bool libnvme_host_is_pdc_enabled(libnvme_host_t h, bool fallback); * Returns a host object based on the hostnqn/hostid values or the default if * hostnqn/hostid are NULL. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_get_host(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *hostid, libnvme_host_t *h); @@ -614,7 +614,7 @@ int libnvme_ns_write_uncorrectable(libnvme_ns_t n, off_t offset, size_t count); * libnvme_ns_flush() - Flush data to a namespace * @n: Namespace instance * - * Return: 0 on success, -1 on error. + * Return: 0 on success, negative error code otherwise. */ int libnvme_ns_flush(libnvme_ns_t n); @@ -626,7 +626,7 @@ int libnvme_ns_flush(libnvme_ns_t n); * Writes the data returned by the 'identify namespace' command * into @ns. * - * Return: 0 on success, -1 on error. + * Return: 0 on success, negative error code otherwise. */ int libnvme_ns_identify(libnvme_ns_t n, struct nvme_id_ns *ns); @@ -638,7 +638,7 @@ int libnvme_ns_identify(libnvme_ns_t n, struct nvme_id_ns *ns); * Writes the data returned by the 'identify descriptors' command * into @descs. * - * Return: 0 on success, -1 on error. + * Return: 0 on success, negative error code otherwise. */ int libnvme_ns_identify_descs(libnvme_ns_t n, struct nvme_ns_id_desc *descs); @@ -721,7 +721,7 @@ void libnvme_path_reset_stat(libnvme_path_t p); * @diffstat: If set to true then getters return the diff stat otherwise * return the current absolute stat * - * Return: 0 on success, -1 on error + * Return: 0 on success, negative error code otherwise. */ int libnvme_path_update_stat(libnvme_path_t p, bool diffstat); @@ -857,7 +857,7 @@ libnvme_subsystem_t libnvme_ctrl_get_subsystem(libnvme_ctrl_t c); * libnvme_ns_head_get_sysfs_dir() - sysfs dir of namespave head * @head: namespace head instance * - * Returns: sysfs directory name of @head + * Return: sysfs directory name of @head */ const char *libnvme_ns_head_get_sysfs_dir(libnvme_ns_head_t head); @@ -867,7 +867,7 @@ const char *libnvme_ns_head_get_sysfs_dir(libnvme_ns_head_t head); * @diffstat: If set to true then getters return the diff stat otherwise * return the current absolute stat * - * Returns: 0 on success, -1 on error + * Return: 0 on success, negative error code otherwise. */ int libnvme_ns_update_stat(libnvme_ns_t n, bool diffstat); @@ -987,7 +987,7 @@ long libnvme_ctrl_get_reconnect_count(libnvme_ctrl_t c); * Issues an 'identify controller' command to @c and copies the * data into @id. * - * Return: 0 on success or -1 on failure. + * Return: 0 on success, negative error code otherwise. */ int libnvme_ctrl_identify(libnvme_ctrl_t c, struct nvme_id_ctrl *id); @@ -999,7 +999,7 @@ int libnvme_ctrl_identify(libnvme_ctrl_t c, struct nvme_id_ctrl *id); * * Scans a controller with sysfs name @name and add it to @r. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_scan_ctrl(struct libnvme_global_ctx *ctx, const char *name, libnvme_ctrl_t *c); @@ -1017,7 +1017,7 @@ void libnvme_rescan_ctrl(libnvme_ctrl_t c); * @c: libnvme_ctrl_t object * @instance: Instance number (e.g. 1 for nvme1) * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_init_ctrl(libnvme_host_t h, libnvme_ctrl_t c, int instance); @@ -1042,7 +1042,7 @@ void libnvme_unlink_ctrl(struct libnvme_ctrl *c); * Scans the NVMe topology and filters out the resulting elements * by applying @f. * - * Return: 0 on success, or negative error code otherwise. + * Return: 0 on success, negative error code otherwise. */ int libnvme_scan_topology(struct libnvme_global_ctx *ctx, libnvme_scan_filter_t f, void *f_args); @@ -1071,7 +1071,7 @@ void libnvme_free_host(libnvme_host_t h); * Read in the contents of @config_file and merge them with * the elements in @r. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_read_config(struct libnvme_global_ctx *ctx, const char *config_file); @@ -1092,7 +1092,7 @@ void libnvme_refresh_topology(struct libnvme_global_ctx *ctx); * Writes the current contents of the JSON configuration * to the file descriptor fd. * - * Return: 0 on success, or negative error code otherwise. + * Return: 0 on success, negative error code otherwise. */ int libnvme_dump_config(struct libnvme_global_ctx *ctx, int fd); @@ -1103,7 +1103,7 @@ int libnvme_dump_config(struct libnvme_global_ctx *ctx, int fd); * Prints the internal object tree in JSON format * to stdout. * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_dump_tree(struct libnvme_global_ctx *ctx); @@ -1185,7 +1185,7 @@ char *libnvme_get_path_attr(libnvme_path_t p, const char *attr); * @name: sysfs name of the namespace to scan * @ns: &libnvme_ns_t object to return * - * Return: 0 on success or negative error code otherwise + * Return: 0 on success, negative error code otherwise. */ int libnvme_scan_namespace(struct libnvme_global_ctx *ctx, const char *name, libnvme_ns_t *ns); diff --git a/libnvme/src/nvme/util.h b/libnvme/src/nvme/util.h index 8a9165a442..bd09f49468 100644 --- a/libnvme/src/nvme/util.h +++ b/libnvme/src/nvme/util.h @@ -254,8 +254,8 @@ int libnvme_random_uuid(unsigned char uuid[NVME_UUID_LEN]); * @uuid_list: UUID list returned by identify UUID * @uuid: Binary encoded input UUID * - * Return: The array position where given UUID is present, or -1 on failure - * with errno set. + * Return: The array position where given UUID is present, or negative + * error code otherwise. */ int libnvme_find_uuid(struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN]);