C接口

宏定义和枚举

bdev_rw.h

enum libstorage_ns_lba_size

1. 原型

enum libstorage_ns_lba_size
{
LIBSTORAGE_NVME_NS_LBA_SIZE_512 = 0x9,
LIBSTORAGE_NVME_NS_LBA_SIZE_4K = 0xc
};

2. 描述

磁盘sector_size（数据）大小。

enum libstorage_ns_md_size

1. 原型

enum libstorage_ns_md_size
{
LIBSTORAGE_METADATA_SIZE_0 = 0,
LIBSTORAGE_METADATA_SIZE_8 = 8,
LIBSTORAGE_METADATA_SIZE_64 = 64
};

2. 描述

磁盘meta data（元数据） size大小。

3. 备注

• ES3000 V3（单端口）支持5种扇区类型的格式化（512+0，512+8，4K+64，4K，4K+8）。

• ES3000 V3（双端口）支持4种扇区类型的格式化（512+0，512+8，4K+64，4K）。

• ES3000 V5 支持5种扇区类型的格式化（512+0，512+8，4K+64，4K，4K+8）。

• Optane盘支持7种扇区类型的格式化（512+0，512+8，512+16,4K，4K+8，4K+64，4K+128）。

enum libstorage_ns_pi_type

1. 原型

enum libstorage_ns_pi_type
{
LIBSTORAGE_FMT_NVM_PROTECTION_DISABLE = 0x0,
LIBSTORAGE_FMT_NVM_PROTECTION_TYPE1 = 0x1,
LIBSTORAGE_FMT_NVM_PROTECTION_TYPE2 = 0x2,
LIBSTORAGE_FMT_NVM_PROTECTION_TYPE3 = 0x3,
};

2. 描述

磁盘支持的保护类型。

3. 备注

ES3000仅支持保护类型0和保护类型3，Optane盘仅支持保护类型0和保护类型1。

enum libstorage_crc_and_prchk

1. 原型

enum libstorage_crc_and_prchk
{
LIBSTORAGE_APP_CRC_AND_DISABLE_PRCHK = 0x0,
LIBSTORAGE_APP_CRC_AND_ENABLE_PRCHK = 0x1,
LIBSTORAGE_LIB_CRC_AND_DISABLE_PRCHK = 0x2,
LIBSTORAGE_LIB_CRC_AND_ENABLE_PRCHK = 0x3,
#define NVME_NO_REF 0x4
LIBSTORAGE_APP_CRC_AND_DISABLE_PRCHK_NO_REF = LIBSTORAGE_APP_CRC_AND_DISABLE_PRCHK | NVME_NO_REF,
LIBSTORAGE_APP_CRC_AND_ENABLE_PRCHK_NO_REF = LIBSTORAGE_APP_CRC_AND_ENABLE_PRCHK | NVME_NO_REF,
};

2. 描述

• LIBSTORAGE_APP_CRC_AND_DISABLE_PRCHK：应用层做CRC校验，HSAK不做CRC校验，关闭盘的CRC校验。

• LIBSTORAGE_APP_CRC_AND_ENABLE_PRCHK：应用层做CRC校验，HSAK不做CRC校验，开启盘的CRC校验。

• LIBSTORAGE_LIB_CRC_AND_DISABLE_PRCHK：应用层不做CRC校验，HSAK做CRC校验，关闭盘的CRC校验。

• LIBSTORAGE_LIB_CRC_AND_ENABLE_PRCHK：应用层不做CRC校验，HSAK做CRC校验，开启盘的CRC校验。

• LIBSTORAGE_APP_CRC_AND_DISABLE_PRCHK_NO_REF：应用层做CRC校验，HSAK不做CRC校验，关闭盘的CRC校验。对于PI TYPE为1的磁盘（Intel optane P4800），关闭盘的REF TAG校验。

• LIBSTORAGE_APP_CRC_AND_ENABLE_PRCHK_NO_REF：应用层做CRC校验，HSAK不做CRC校验，开启盘的CRC校验。对于PI TYPE为1的磁盘（Intel optane P4800），关闭盘的REF TAG校验。

• Intel optane P4800盘PI TYPE为1，默认会校验元数据区的CRC和REF TAG。

• Intel optane P4800盘的512+8格式支持DIF，4096+64格式不支持。

• ES3000 V3和ES3000 V5盘PI TYPE为3，默认只校验元数据区的CRC。

• ES3000 V3的512+8格式支持DIF，4096+64格式不支持。ES3000 V5的512+8和4096+64格式均支持DIF。

总结为如下：

enum libstorage_print_log_level

1. 原型

enum libstorage_print_log_level
{
LIBSTORAGE_PRINT_LOG_ERROR,
LIBSTORAGE_PRINT_LOG_WARN,
LIBSTORAGE_PRINT_LOG_NOTICE,
LIBSTORAGE_PRINT_LOG_INFO,
LIBSTORAGE_PRINT_LOG_DEBUG,
};

2. 描述

SPDK日志打印级别：ERROR、WARN、NOTICE、INFO、DEBUG，分别对应配置文件中的0~4。

MAX_BDEV_NAME_LEN

1. 原型

#define MAX_BDEV_NAME_LEN 24

2. 描述

块设备名最大长度限制。

MAX_CTRL_NAME_LEN

1. 原型

#define MAX_CTRL_NAME_LEN 16

2. 描述

控制器名最大长度限制。

LBA_FORMAT_NUM

1. 原型

#define LBA_FORMAT_NUM 16

2. 描述

控制器所支持的LBA格式数目。

LIBSTORAGE_MAX_DSM_RANGE_DESC_COUNT

1. 原型

#define LIBSTORAGE_MAX_DSM_RANGE_DESC_COUNT 256

2. 描述

数据集管理命令中16字节集的最大数目。

ublock.h

UBLOCK_NVME_UEVENT_SUBSYSTEM_UIO

1. 原型

#define UBLOCK_NVME_UEVENT_SUBSYSTEM_UIO 1

2. 描述

用于定义uevent事件所对应的子系统是内核uio，在业务收到uevent事件时，通过该宏定义判断是否为需要处理的内核uio事件。

数据结构struct ublock_uevent中成员int subsystem的值取值为UBLOCK_NVME_UEVENT_SUBSYSTEM_UIO，当前仅此一个可选值。

UBLOCK_TRADDR_MAX_LEN

1. 原型

#define UBLOCK_TRADDR_MAX_LEN 256

2. 描述

以"域:总线:设备.功能"（%04x:%02x:%02x.%x）格式表示的PCI地址字符串的最大长度，实际长度远小于256字节。

UBLOCK_PCI_ADDR_MAX_LEN

1. 原型

#define UBLOCK_PCI_ADDR_MAX_LEN 256

2. 描述

PCI地址字符串最大长度，实际长度远小于256字节；此处PCI地址格式可能的形式为：

• 全地址：%x:%x:%x.%x 或 %x.%x.%x.%x。

• 功能值为0：%x:%x:%x。

• 域值为0：%x:%x.%x 或 %x.%x.%x。

• 域和功能值为0：%x:%x 或 %x.%x。

UBLOCK_SMART_INFO_LEN

1. 原型

#define UBLOCK_SMART_INFO_LEN 512

2. 描述

获取NVMe盘SMART信息结构体的大小，为512字节。

enum ublock_rpc_server_status

1. 原型

enum ublock_rpc_server_status {
// start rpc server or not
UBLOCK_RPC_SERVER_DISABLE = 0,
UBLOCK_RPC_SERVER_ENABLE = 1,
};

2. 描述

用于表示HSAK内部RPC服务状态，启用或关闭。

enum ublock_nvme_uevent_action

1. 原型

enum ublock_nvme_uevent_action {
UBLOCK_NVME_UEVENT_ADD = 0,
UBLOCK_NVME_UEVENT_REMOVE = 1,
UBLOCK_NVME_UEVENT_INVALID,
};

2. 描述

用于表示uevent热插拔事件是插入硬盘还是移除硬盘。

enum ublock_subsystem_type

1. 原型

enum ublock_subsystem_type {
SUBSYSTEM_UIO = 0,
SUBSYSTEM_NVME = 1,
SUBSYSTEM_TOP
};

2. 描述

指定回调函数类型，用于区分产品注册回调函数时是针对于uio驱动还是针对于内核nvme驱动。

数据结构

bdev_rw.h

struct libstorage_namespace_info

1. 原型

struct libstorage_namespace_info
{
char name[MAX_BDEV_NAME_LEN];
uint64_t size; /** namespace size in bytes */
uint64_t sectors; /** number of sectors */
uint32_t sector_size; /** sector size in bytes */
uint32_t md_size; /** metadata size in bytes */
uint32_t max_io_xfer_size; /** maximum i/o size in bytes */
uint16_t id; /** namespace id */
uint8_t pi_type; /** end-to-end data protection information type */
uint8_t is_active :1; /** namespace is active or not */
uint8_t ext_lba :1; /** namespace support extending LBA size or not */
uint8_t dsm :1; /** namespace supports Dataset Management or not */
uint8_t pad :3;
uint64_t reserved;
};

2. 描述

该数据结构中包含硬盘namespace相关信息。

3. 结构体成员

struct libstorage_nvme_ctrlr_info

1. 原型

struct libstorage_nvme_ctrlr_info
{
char name[MAX_CTRL_NAME_LEN];
char address[24];
struct
{
uint32_t domain;
uint8_t bus;
uint8_t dev;
uint8_t func;
} pci_addr;
uint64_t totalcap; /* Total NVM Capacity in bytes */
uint64_t unusecap; /* Unallocated NVM Capacity in bytes */
int8_t sn[20]; /* Serial number */
uint8_t fr[8]; /* Firmware revision */
uint32_t max_num_ns; /* Number of namespaces */
uint32_t version;
uint16_t num_io_queues; /* num of io queues */
uint16_t io_queue_size; /* io queue size */
uint16_t ctrlid; /* Controller id */
uint16_t pad1;
struct
{
struct
{
/** metadata size */
uint32_t ms : 16;
/** lba data size */
uint32_t lbads : 8;
uint32_t reserved : 8;
} lbaf[LBA_FORMAT_NUM];
uint8_t nlbaf;
uint8_t pad2[3];
uint32_t cur_format : 4;
uint32_t cur_extended : 1;
uint32_t cur_pi : 3;
uint32_t cur_pil : 1;
uint32_t cur_can_share : 1;
uint32_t mc_extented : 1;
uint32_t mc_pointer : 1;
uint32_t pi_type1 : 1;
uint32_t pi_type2 : 1;
uint32_t pi_type3 : 1;
uint32_t md_start : 1;
uint32_t md_end : 1;
uint32_t ns_manage : 1; /* Supports the Namespace Management and Namespace Attachment commands */
uint32_t directives : 1; /* Controller support Directives or not */
uint32_t streams : 1; /* Controller support Streams Directives or not */
uint32_t dsm : 1; /* Controller support Dataset Management or not */
uint32_t reserved : 11;
} cap_info;
};

1. 描述

该数据结构中包含硬盘控制器相关信息。

2. 结构体成员

struct cap_info子结构体成员：

struct libstorage_dsm_range_desc

1. 原型

struct libstorage_dsm_range_desc
{
/* RESERVED */
uint32_t reserved;

/* NUMBER OF LOGICAL BLOCKS */
uint32_t block_count;

/* UNMAP LOGICAL BLOCK ADDRESS */uint64_t lba;};

2. 描述

数据管理命令集中单个16字节集的定义。

3. 结构体成员

struct libstorage_ctrl_streams_param

1. 原型

struct libstorage_ctrl_streams_param
{
/* MAX Streams Limit */
uint16_t msl;

/* NVM Subsystem Streams Available */
uint16_t nssa;

/* NVM Subsystem Streams Open */uint16_t nsso;

uint16_t pad;
};

2. 描述

NVMe盘支持的Streams属性值。

3. 结构体成员

struct libstorage_bdev_streams_param

1. 原型

struct libstorage_bdev_streams_param
{
/* Stream Write Size */
uint32_t sws;

/* Stream Granularity Size */
uint16_t sgs;

/* Namespace Streams Allocated */
uint16_t nsa;

/* Namespace Streams Open */
uint16_t nso;

uint16_t reserved[3];
};

2. 描述

Namespace的Streams属性值。

3. 结构体成员

struct libstorage_mgr_info

1. 原型

struct libstorage_mgr_info
{
char pci[24];
char ctrlName[MAX_CTRL_NAME_LEN];
uint64_t sector_size;
uint64_t cap_size;
uint16_t device_id;
uint16_t subsystem_device_id;
uint16_t vendor_id;
uint16_t subsystem_vendor_id;
uint16_t controller_id;
int8_t serial_number[20];
int8_t model_number[40];
uint8_t firmware_revision[8];
};

2. 描述

磁盘管理信息（与管理面使用的磁盘信息一致）。

3. 结构体成员

struct attribute((packed)) libstorage_smart_info

1. 原型

/* same with struct spdk_nvme_health_information_page in nvme_spec.h */
struct __attribute__((packed)) libstorage_smart_info {
/* details of uint8_t critical_warning

union spdk_nvme_critical_warning_state {

uint8_t raw;
*

struct {

uint8_t available_spare : 1;

uint8_t temperature : 1;

uint8_t device_reliability : 1;

uint8_t read_only : 1;

uint8_t volatile_memory_backup : 1;

uint8_t reserved : 3;

} bits;

};
*/
uint8_t critical_warning;
uint16_t temperature;
uint8_t available_spare;
uint8_t available_spare_threshold;
uint8_t percentage_used;
uint8_t reserved[26];

/*

Note that the following are 128-bit values, but are

defined as an array of 2 64-bit values.
*/
/* Data Units Read is always in 512-byte units. */
uint64_t data_units_read[2];
/* Data Units Written is always in 512-byte units. */
uint64_t data_units_written[2];
/* For NVM command set, this includes Compare commands. */
uint64_t host_read_commands[2];
uint64_t host_write_commands[2];
/* Controller Busy Time is reported in minutes. */
uint64_t controller_busy_time[2];
uint64_t power_cycles[2];
uint64_t power_on_hours[2];
uint64_t unsafe_shutdowns[2];
uint64_t media_errors[2];
uint64_t num_error_info_log_entries[2];
/* Controller temperature related. */
uint32_t warning_temp_time;
uint32_t critical_temp_time;
uint16_t temp_sensor[8];
uint8_t reserved2[296];
};

1. 描述

该数据结构定义了硬盘SMART INFO信息内容。

2. 结构体成员

libstorage_dpdk_contig_mem

1. 原型

struct libstorage_dpdk_contig_mem {
uint64_t virtAddr;
uint64_t memLen;
uint64_t allocLen;
};

2. 描述

DPDK内存初始化之后，通知业务层初始化完成的回调函数参数中描述一段连续虚拟内存的信息。

当前HSAK预留了800M内存，其他内存通过该结构体中的allocLen返回给业务层，用于业务层申请内存自行管理。

HSAK需要预留的总内存是800M左右，每一个内存段上预留的内存是根据环境的NUMA节点数来计算的。在NUMA节点过多时，每个内存段上预留的内存过小，会导致HSAK初始化失败。因此HSAK只支持最多4个NUMA节点的环境。

3. 结构体成员

struct libstorage_dpdk_init_notify_arg

1. 原型

struct libstorage_dpdk_init_notify_arg {
uint64_t baseAddr;
uint16_t memsegCount;
struct libstorage_dpdk_contig_mem *memseg;
};

2. 描述

用于DPDK内存初始化之后，通知业务层初始化完成的回调函数参数，表示所有虚拟内存段信息。

3. 结构体成员

struct libstorage_dpdk_init_notify

1. 原型

struct libstorage_dpdk_init_notify {
const char *name;
void (*notifyFunc)(const struct libstorage_dpdk_init_notify_arg *arg);
TAILQ_ENTRY(libstorage_dpdk_init_notify) tailq;
};

2. 描述

用于DPDK内存初始化之后，通知业务层回调函数注册的结构体。

3. 结构体成员

ublock.h

struct ublock_bdev_info

1. 原型

struct ublock_bdev_info {
uint64_t sector_size;
uint64_t cap_size; // cap_size
uint16_t device_id;
uint16_t subsystem_device_id; // subsystem device id of nvme control
uint16_t vendor_id;
uint16_t subsystem_vendor_id;
uint16_t controller_id;
int8_t serial_number[20];
int8_t model_number[40];
int8_t firmware_revision[8];
};

2. 描述

该数据结构中包含硬盘设备信息。

3. 结构体成员

struct ublock_bdev

1. 原型

struct ublock_bdev {
char pci[UBLOCK_PCI_ADDR_MAX_LEN];
struct ublock_bdev_info info;
struct spdk_nvme_ctrlr *ctrlr;
TAILQ_ENTRY(ublock_bdev) link;
};

2. 描述

该数据结构中包含指定PCI地址的硬盘信息，而结构本身为队列的一个节点。

3. 结构体成员

struct ublock_bdev_mgr

1. 原型

struct ublock_bdev_mgr {
TAILQ_HEAD(, ublock_bdev) bdevs;
};

2. 描述

该数据结构内定义了一个ublock_bdev队列的头结构。

3. 结构体成员

struct attribute((packed)) ublock_SMART_info

1. 原型

struct __attribute__((packed)) ublock_SMART_info {
uint8_t critical_warning;
uint16_t temperature;
uint8_t available_spare;
uint8_t available_spare_threshold;
uint8_t percentage_used;
uint8_t reserved[26];
/*

Note that the following are 128-bit values, but are

defined as an array of 2 64-bit values.
*/
/* Data Units Read is always in 512-byte units. */
uint64_t data_units_read[2];
/* Data Units Written is always in 512-byte units. */
uint64_t data_units_written[2];
/* For NVM command set, this includes Compare commands. */
uint64_t host_read_commands[2];
uint64_t host_write_commands[2];
/* Controller Busy Time is reported in minutes. */
uint64_t controller_busy_time[2];
uint64_t power_cycles[2];
uint64_t power_on_hours[2];
uint64_t unsafe_shutdowns[2];
uint64_t media_errors[2];
uint64_t num_error_info_log_entries[2];
/* Controller temperature related. */
uint32_t warning_temp_time;
uint32_t critical_temp_time;
uint16_t temp_sensor[8];
uint8_t reserved2[296];
};

2. 描述

该数据结构定义了硬盘SMART INFO信息内容。

3. 结构体成员

struct ublock_nvme_error_info

1. 原型

struct ublock_nvme_error_info {
uint64_t error_count;
uint16_t sqid;
uint16_t cid;
uint16_t status;
uint16_t error_location;
uint64_t lba;
uint32_t nsid;
uint8_t vendor_specific;
uint8_t reserved[35];
};

2. 描述

该数据结构中包含设备控制器中单条错误信息具体内容，不同控制器可支持的错误条数可能不同。

3. 结构体成员

struct ublock_uevent

1. 原型

struct ublock_uevent {
enum ublock_nvme_uevent_action action;
int subsystem;
char traddr[UBLOCK_TRADDR_MAX_LEN + 1];
};

2. 描述

该数据结构中包含用于表示uevent事件的相关参数。

3. 结构体成员

struct ublock_hook

1. 原型

struct ublock_hook
{
ublock_callback_func ublock_callback;
void *user_data;
};

2. 描述

该数据结构用于注册回调函数。

3. 结构体成员

struct ublock_ctrl_iostat_info

1. 原型

struct ublock_ctrl_iostat_info
{
uint64_t num_read_ops;
uint64_t num_write_ops;
uint64_t read_latency_ms;
uint64_t write_latency_ms;
uint64_t io_outstanding;
uint64_t num_poll_timeout;
uint64_t io_ticks_ms;
};

2. 描述

该数据结构用于获取控制器的IO统计信息。

3. 结构体成员

API

bdev_rw.h

libstorage_get_nvme_ctrlr_info

1. 接口原型

uint32_t libstorage_get_nvme_ctrlr_info(struct libstorage_nvme_ctrlr_info** ppCtrlrInfo);

2. 接口描述

获取所有控制器信息。

3. 参数

4. 返回值

libstorage_get_mgr_info_by_esn

1. 接口原型

int32_t libstorage_get_mgr_info_by_esn(const char *esn, struct libstorage_mgr_info *mgr_info);

2. 接口描述

数据面获取设备序列号（ESN）对应的NVMe磁盘的管理信息。

3. 参数

4. 返回值

libstorage_get_mgr_smart_by_esn

1. 接口原型

int32_t libstorage_get_mgr_smart_by_esn(const char *esn, uint32_t nsid, struct libstorage_smart_info *mgr_smart_info);

2. 接口描述

数据面获取设备序列号（ESN）对应的NVMe磁盘的SMART信息。

3. 参数

4. 返回值

libstorage_get_bdev_ns_info

1. 接口原型

uint32_t libstorage_get_bdev_ns_info(const char* bdevName, struct libstorage_namespace_info** ppNsInfo);

2. 接口描述

根据设备名称，获取namespace信息。

3. 参数

4. 返回值

libstorage_get_ctrl_ns_info

1. 接口原型

uint32_t libstorage_get_ctrl_ns_info(const char* ctrlName, struct libstorage_namespace_info** ppNsInfo);

2. 接口描述

根据控制器名称，获取所有namespace信息。

3. 参数

4. 返回值

libstorage_create_namespace

1. 接口原型

int32_t libstorage_create_namespace(const char* ctrlName, uint64_t ns_size, char** outputName);

2. 接口描述

在指定控制器上创建namespace（前提是控制器具有namespace管理能力）。

Optane盘基于NVMe 1.0协议，不支持namespace管理，因此不支持该接口的使用。

ES3000 V3和V5默认只支持一个namespace。在控制器上默认会存在一个namespace，如果要创建新的namespace，需要将原有namespace删除。

3. 参数

4. 返回值

libstorage_delete_namespace

1. 接口原型

int32_t libstorage_delete_namespace(const char* ctrlName, uint32_t ns_id);

2. 接口描述

在指定控制器上删除namespace。Optane盘基于NVMe 1.0协议，不支持namespace管理，因此不支持该接口的使用。

3. 参数

4. 返回值

libstorage_delete_all_namespace

1. 接口原型

int32_t libstorage_delete_all_namespace(const char* ctrlName);

2. 接口描述

删除指定控制器上所有namespace。Optane盘基于NVMe 1.0协议，不支持namespace管理，因此不支持该接口的使用。

3. 参数

4. 返回值

libstorage_nvme_create_ctrlr

1. 接口原型

int32_t libstorage_nvme_create_ctrlr(const char *pci_addr, const char *ctrlr_name);

2. 接口描述

根据PCI地址创建NVMe控制器。

3. 参数

4. 返回值

libstorage_nvme_delete_ctrlr

1. 接口原型

int32_t libstorage_nvme_delete_ctrlr(const char *ctrlr_name);

1. 接口描述

根据控制器名称销毁NVMe控制器。

2. 参数

确保已下发的io已经全部返回后方可调用本接口。

3. 返回值

libstorage_nvme_reload_ctrlr

1. 接口原型

int32_t libstorage_nvme_reload_ctrlr(const char *cfgfile);

2. 接口描述

根据配置文件增删NVMe控制器。

3. 参数

使用本接口删盘时，需要确保已下发的io已经全部返回。

4. 返回值

使用限制

• 目前最多支持在配置文件中配置36个控制器。

• 重加载接口会尽可能创建多的控制器，某个控制器创建失败，不会影响其他控制器的创建。

• 无法保证并发场景下最终的盘初始化情况与最后调用传入的配置文件相符。

• 对正在下发io的盘通过reload删除时，会导致io失败。

• 修改配置文件中pci地址对应的控制器名称(e.g.nvme0)，调用此接口后无法生效。

• reload仅针对于增删盘的场景有效，配置文件中的其他配置项修改无法重载。

libstorage_low_level_format_nvm

1. 接口原型

int8_t libstorage_low_level_format_nvm(const char* ctrlName, uint8_t lbaf,
enum libstorage_ns_pi_type piType,
bool pil_start, bool ms_extented, uint8_t ses);

2. 接口描述

低级格式化NVMe盘。

3. 参数

4. 返回值

使用限制

• 该低级格式化接口会清除磁盘namespace的数据和元数据，请谨慎使用。

• ES3000盘在格式化时耗时数秒，Intel Optane盘在格式化时需耗时数分钟，在使用该接口时需要等待其执行完成。若强行杀掉格式化进程，会导致格式化失败。

• 在格式化执行之前，需要停止数据面的IO操作。如果当前磁盘正在处理IO请求，格式化操作会概率性出现失败，并且在格式化成功的情况下会存在硬盘丢弃正在处理的IO的可能，所以在格式化前，请保证数据面的IO操作已停止。

• 格式化过程中会reset控制器，导致之前已经初始化的磁盘资源不可用。因此格式化完成之后，需要重启数据面IO进程。

• ES3000 V3支持保护类型0和3，支持PI start和PI end，仅支持mc extended。ES3000 V3的512+8格式支持DIF，4096+64格式不支持。

• ES3000 V5支持保护类型0和3，支持PI start和PI end，支持mc extended和mc pointer。ES3000 V5的512+8和4096+64格式均支持DIF。

• Optane盘支持保护类型0和1，仅支持PI end，仅支持mc extended。Optane的512+8格式支持DIF，4096+64格式不支持。

LIBSTORAGE_CALLBACK_FUNC

1. 接口原型

typedef void (*LIBSTORAGE_CALLBACK_FUNC)(int32_t cb_status, int32_t sct_code, void* cb_arg);

2. 接口描述

注册的HSAK io完成回调函数。

3. 参数

4. 返回值

无。

libstorage_deallocate_block

1. 接口原型

int32_t libstorage_deallocate_block(int32_t fd, struct libstorage_dsm_range_desc *range, uint16_t range_count, LIBSTORAGE_CALLBACK_FUNC cb, void* cb_arg);

2. 接口描述

告知NVMe盘可释放的块。

3. 参数

4. 返回值

libstorage_async_write

1. 接口原型

int32_t libstorage_async_write(int32_t fd, void *buf, size_t nbytes, off64_t offset, void *md_buf, size_t md_len, enum libstorage_crc_and_prchk dif_flag, LIBSTORAGE_CALLBACK_FUNC cb, void* cb_arg);

2. 接口描述

HSAK下发异步IO写请求的接口（写缓冲区为连续buffer）。

3. 参数

4. 返回值

libstorage_async_read

1. 接口原型

int32_t libstorage_async_read(int32_t fd, void *buf, size_t nbytes, off64_t offset, void *md_buf, size_t md_len, enum libstorage_crc_and_prchk dif_flag, LIBSTORAGE_CALLBACK_FUNC cb, void* cb_arg);

2. 接口描述

HSAK下发异步IO读请求的接口（读缓冲区为连续buffer）。

3. 参数

4. 返回值

libstorage_async_writev

1. 接口原型

int32_t libstorage_async_writev(int32_t fd, struct iovec *iov, int iovcnt, size_t nbytes, off64_t offset, void *md_buf, size_t md_len, enum libstorage_crc_and_prchk dif_flag, LIBSTORAGE_CALLBACK_FUNC cb, void* cb_arg);

2. 接口描述

HSAK下发异步IO写请求的接口（写缓冲区为离散buffer）。

3. 参数

4. 返回值

libstorage_async_readv

1. 接口原型

int32_t libstorage_async_readv(int32_t fd, struct iovec *iov, int iovcnt, size_t nbytes, off64_t offset, void *md_buf, size_t md_len, enum libstorage_crc_and_prchk dif_flag, LIBSTORAGE_CALLBACK_FUNC cb, void* cb_arg);

2. 接口描述

HSAK下发异步IO读请求的接口（读缓冲区为离散buffer）。

3. 参数

4. 返回值

libstorage_sync_write

1. 接口原型

int32_t libstorage_sync_write(int fd, const void *buf, size_t nbytes, off_t offset);

2. 接口描述

HSAK下发同步IO写请求的接口（写缓冲区为连续buffer）。

3. 参数

4. 返回值

libstorage_sync_read

1. 接口原型

int32_t libstorage_sync_read(int fd, const void *buf, size_t nbytes, off_t offset);

2. 接口描述

HSAK下发同步IO读请求的接口（读缓冲区为连续buffer）。

3. 参数

4. 返回值

libstorage_open

1. 接口原型

int32_t libstorage_open(const char* devfullname);

2. 接口描述

打开块设备。

3. 参数

4. 返回值

开启nvme.conf.in中的MultiQ开关以后，同一个线程多次打开同一个设备，会返回不同的fd；否则仍返回同一个fd。该特性只针对NVME设备。

libstorage_close

1. 接口原型

int32_t libstorage_close(int32_t fd);

2. 接口描述

关闭块设备。

3. 参数

4. 返回值

libstorage_mem_reserve

1. 接口原型

void* libstorage_mem_reserve(size_t size, size_t align);

2. 接口描述

从DPDK预留的大页内存中分配内存空间。

3. 参数

4. 返回值

libstorage_mem_free

1. 接口原型

void libstorage_mem_free(void* ptr);

2. 接口描述

释放ptr指向的内存空间。

3. 参数

4. 返回值

无。

libstorage_alloc_io_buf

1. 接口原型

void* libstorage_alloc_io_buf(size_t nbytes);

2. 接口描述

从SPDK的buf_small_pool或者buf_large_pool中分配内存。

3. 参数

4. 返回值

libstorage_free_io_buf

1. 接口原型

int32_t libstorage_free_io_buf(void *buf, size_t nbytes);

2. 接口描述

释放所分配的内存到SPDK的buf_small_pool或者buf_large_pool中。

3. 参数

4. 返回值

libstorage_init_module

1. 接口原型

int32_t libstorage_init_module(const char* cfgfile);

2. 接口描述

HSAK模块初始化接口。

3. 参数

4. 返回值

libstorage_exit_module

1. 接口原型

int32_t libstorage_exit_module(void);

2. 接口描述

HSAK模块退出接口。

3. 参数

无。

4. 返回值

LIBSTORAGE_REGISTER_DPDK_INIT_NOTIFY

1. 接口原型

LIBSTORAGE_REGISTER_DPDK_INIT_NOTIFY(_name, _notify)

2. 接口描述

业务层注册函数，用于注册DPDK初始化完成时的回调函数。

3. 参数

4. 返回值

无

ublock.h

init_ublock

1. 接口原型

int init_ublock(const char *name, enum ublock_rpc_server_status flg);

2. 接口描述

初始化Ublock功能模块，本接口必须在其他所有Ublock接口之前被调用。如果flag被置为UBLOCK_RPC_SERVER_ENABLE，即ublock作为rpc server，则同一个进程只能初始化一次。

在ublock作为rpc server启动时，会同时启动一个server的monitor线程。monitor线程监控到rpc server线程出现异常（如卡死时），会主动调用exit触发进程退出。

此时依赖于产品的脚本再次拉起相关进程。

3. 参数

4. 返回值

ublock_init

1. 接口原型

#define ublock_init(name) init_ublock(name, UBLOCK_RPC_SERVER_ENABLE)

2. 接口描述

本身是对init_ublock接口的宏定义，可理解为将Ublock初始化为需要RPC服务。

3. 参数

4. 返回值

ublock_init_norpc

1. 接口原型

#define ublock_init_norpc(name) init_ublock(name, UBLOCK_RPC_SERVER_DISABLE)

2. 接口描述

本身是对init_ublock接口的宏定义，可理解为将Ublock初始化为无RPC服务。

3. 参数

4. 返回值

ublock_fini

1. 接口原型

void ublock_fini(void);

2. 接口描述

销毁Ublock功能模块，本接口将销毁Ublock模块以及内部创建的资源，本接口同Ublock初始化接口需要配对使用。

3. 参数

无。

4. 返回值

无。

ublock_get_bdevs

1. 接口原型

int ublock_get_bdevs(struct ublock_bdev_mgr* bdev_list);

2. 接口描述

业务进程通过调用本接口获取设备列表（环境上所有的NVME设备，包括内核态驱动和用户态驱动），获取的NVMe设备列表中只有PCI地址，不包含具体设备信息，需要获取具体设备信息，请调用接口ublock_get_bdev。

3. 参数

4. 返回值

ublock_free_bdevs

1. 接口原型

void ublock_free_bdevs(struct ublock_bdev_mgr* bdev_list);

2. 接口描述

业务进程通过调用本接口释放设备列表。

3. 参数

4. 返回值

无。

ublock_get_bdev

1. 接口原型

int ublock_get_bdev(const char *pci, struct ublock_bdev *bdev);

2. 接口描述

业务进程通过调用本接口获取具体某个设备的信息，设备信息中：NVMe设备的序列号、型号、fw版本号信息以字符数组形式保存，不是字符串形式（不同硬盘控制器返回形式不同，不保证数组结尾必定含有"0"）。

本接口调用后，对应设备会被Ublock占用，请务必在完成相应业务操作后立即调用ublock_free_bdev释放资源。

3. 参数

4. 返回值

ublock_get_bdev_by_esn

1. 接口原型

int ublock_get_bdev_by_esn(const char *esn, struct ublock_bdev *bdev);

2. 接口描述

业务进程通过调用本接口，根据给定的ESN号获取对应设备的信息，设备信息中：NVMe设备的序列号、型号、fw版本号信息以字符数组形式保存，不是字符串形式（不同硬盘控制器返回形式不同，不保证数组结尾必定含有"0"）。

本接口调用后，对应设备会被Ublock占用，请务必在完成相应业务操作后立即调用ublock_free_bdev释放资源。

3. 参数

4. 返回值

ublock_free_bdev

1. 接口原型

void ublock_free_bdev(struct ublock_bdev *bdev);

2. 接口描述

业务进程通过调用本接口释放设备资源。

3. 参数

4. 返回值

无。

TAILQ_FOREACH_SAFE

1. 接口原型

#define TAILQ_FOREACH_SAFE(var, head, field, tvar) 
for ((var) = TAILQ_FIRST((head)); 
(var) && ((tvar) = TAILQ_NEXT((var), field), 1); 
(var) = (tvar))

2. 接口描述

提供安全访问队列每个成员的宏定义。

3. 参数

4. 返回值

无。

ublock_get_SMART_info

1. 接口原型

int ublock_get_SMART_info(const char *pci, uint32_t nsid, struct ublock_SMART_info *smart_info);

2. 接口描述

业务进程通过调用本接口获取指定设备的SMART信息。

3. 参数

4. 返回值

ublock_get_SMART_info_by_esn

1. 接口原型

int ublock_get_SMART_info_by_esn(const char *esn, uint32_t nsid, struct ublock_SMART_info *smart_info);

2. 接口描述

业务进程通过调用本接口获取ESN号对应设备的SMART信息。

3. 参数

4. 返回值

ublock_get_error_log_info

1. 接口原型

int ublock_get_error_log_info(const char *pci, uint32_t err_entries, struct ublock_nvme_error_info *errlog_info);

2. 接口描述

业务进程通过调用本接口获取指定设备的Error log信息。

3. 参数

4. 返回值

ublock_get_log_page

1. 接口原型

int ublock_get_log_page(const char *pci, uint8_t log_page, uint32_t nsid, void *payload, uint32_t payload_size);

2. 接口描述

业务进程通过调用本接口获取指定设备，指定log page的信息。

3. 参数

4. 返回值

ublock_info_get_pci_addr

1. 接口原型

char *ublock_info_get_pci_addr(const void *info);

2. 接口描述

业务进程的回调函数中，通过调用本接口获取热插拔设备的PCI地址。

info占用的内存以及返回的PCI地址占用得内存不需要业务进程进行释放。

3. 参数

4. 返回值

ublock_info_get_action

1. 接口原型

enum ublock_nvme_uevent_action ublock_info_get_action(const void *info);

2. 接口描述

业务进程的回调函数中，通过调用本接口获取热插拔事件的类型。

info占用的内存不需要业务进程进行释放。

3. 参数

4. 返回值

ublock_get_ctrl_iostat

1. 接口原型

int ublock_get_ctrl_iostat(const char* pci, struct ublock_ctrl_iostat_info *ctrl_iostat);

2. 接口描述

业务进程通过调用本接口获取控制器的IO统计信息。

3. 参数

4. 返回值

ublock_nvme_admin_passthru

1. 接口原型

int32_t ublock_nvme_admin_passthru(const char *pci, void *cmd, void *buf, size_t nbytes);

2. 接口描述

业务进程通过调用该接口透传nvme admin命令给nvme设备。当前仅支持获取identify字段的nvme admin命令。

3. 参数

4. 返回值

附录

GENERIC

通用类型错误码参考

COMMAND_SPECIFIC

特定命令错误码参考

MEDIA_DATA_INTERGRITY_ERROR

介质异常错误码参考