使用说明

nvme.conf.in配置文件

HSAK配置文件默认安装在/etc/spdk/nvme.conf.in,开发人员可以根据实际业务需要对配置文件进行修改,配置文件内容如下:

  • [Global]
  1. ReactorMask: 指定用于轮询IO的核(16进制,不能指定0核,按bit位从低位到高位,分别表示不同CPU核,如:0x1表示0核,0x6表示1、2两个核,以此类推,本字段最大支持34个字符,去掉表示16进制的0x标记,剩余32个计数字符,每个16进制字符最大是F,可表示4个核,所以最多可以支持32*4=128个核)。
  2. LogLevel:HSAK日志打印级别(0:error;1:warning;2:notice;3:info;4:debug)。
  3. MemSize:HSAK占用的内存(最小值为500MB)
  4. MultiQ:是否在同一个块设备上开启多队列。
  5. E2eDif:DIF类型(1:半程保护;2:全程保护),不同厂商的硬盘对DIF支持能力可能不同,具体请参考硬件厂家资料。
  6. IoStat:是否使能IO统计开关(Yes\No)
  7. RpcServer:是否启动rpc侦听线程(Yes\No)
  8. NvmeCUSE:是否启动CUSE功能(Yes\No),开启后在/dev/spdk目录下生成nvme字符设备
  • [Nvme]
  1. TransportID:指定NVMe控制器的PCI地址和名称,使用格式为:TransportID “trtype:PCIe traddr:0000:09:00.0” nvme0
  2. RetryCount:IO失败时的重试次数,0表示不重试,最大255.
  3. TimeoutUsec:IO超市时间,0或者不配置该配置项表示不设置超时时间,单位是μs。
  4. ActionOnTimeout:IO超时行为(None:仅打印信息;Reset:reset控制器;abort:丢弃超时指令),默认None。
  • [Reactor]
  1. BatchSize:支持批量提交提交IO的个数,默认是8,最大是32.

头文件引用

HSAK提供两个对外头文件,开发者在使用HSAK进行开发时需要包含这两个文件:

  1. bdev_rw.h:定义了数据面用户态IO操作的宏、枚举、数据结构和接口API。
  2. ublock.h:定义了管理面设备管理、信息获取等功能的宏、枚举、数据结构和接口API。

业务运行

开发者在进行软件开发编译后,运行前,需要先运行setup.sh脚本程序,用于重新绑定NVMe盘驱动到用户态,该脚本默认安装在:/opt/spdk。 执行如下命令将盘驱动从内核态绑定到用户态,同时预留1024个2M大页:

[root@localhost ~]# cd /opt/spdk
[root@localhost spdk]# ./setup.sh
0000:3f:00.0 (8086 2701): nvme -> uio_pci_generic
0000:40:00.0 (8086 2701): nvme -> uio_pci_generic

执行如下命令将盘驱动从用户态恢复到内核态,同时释放预留的大页:

[root@localhost ~]# cd /opt/spdk
[root@localhost spdk]# ./setup.sh reset
0000:3f:00.0 (8086 2701): uio_pci_generic -> nvme
0000:40:00.0 (8086 2701): uio_pci_generic -> nvme

用户态IO读写场景

开发者通过以下顺序调用HSAK接口,实现经由用户态IO通道的业务数据读写:

  1. 初始化HSAK UIO模块 可调用接口libstorage_init_module,完成HSAK用户态IO通道的初始化。

  2. 打开磁盘块设备 可调用libstorage_open,打开指定块设备,如需打开多个块设备,需要多次重复调用。

  3. 申请IO内存 可调用接口libstorage_alloc_io_buf或libstorage_mem_reserve,前者最大可申请单个65K的IO,后者没有限制(除非无可用空间)。

  4. 对磁盘进行读写操作 根据实际业务需要,可调用如下接口进行读写操作:

    • libstorage_async_read
    • libstorage_async_readv
    • libstorage_async_write
    • libstorage_async_writev
    • libstorage_sync_read
    • libstorage_sync_write
  5. 释放IO内存 可调用接口libstorage_free_io_buf或libstorage_mem_free,需要与申请时调用的接口对应。

  6. 关闭磁盘块设备 可调用接口libstorage_close,关闭指定块设备,如果打开了多个块设备,则需要多次重复调用接口进行关闭。

    接口名称功能描述
    libstorage_init_moduleHSAK模块初始化接口
    libstorage_open打开块设备
    libstorage_alloc_io_buf从SPDK的buf_small_pool或者buf_large_pool中分配内存。
    libstorage_mem_reserve从DPDK预留的大页内存中分配内存空间
    libstorage_async_readHSAK下发异步IO读请求的接口(读缓冲区为连续buffer)。
    libstorage_async_readvHSAK下发异步IO读请求的接口(读缓冲区为离散buffer)。
    libstorage_async_writeHSAK下发异步IO写请求的接口(写缓冲区为连续buffer)。
    libstorage_async_wrtievHSAK下发异步IO写请求的接口(写缓冲区为离散buff)。
    libstorage_sync_readHSAK下发同步IO读请求的接口(读缓冲区为连续buffer)。
    libstorage_sync_writeHSAK下发同步IO写请求的接口(写缓冲区为连续buffer)。
    libstorage_free_io_buf释放所分配的内存到SPDK的buf_small_pool或者buf_large_pool中
    libstorage_mem_free释放libstorage_mem_reserve所申请的内存空间。
    libstorage_close关闭块设备。
    libstorage_exit_moduleHSAK模块退出接口

盘管理场景

HSAK包含一组C接口,可以对盘进行格式化、创建、删除namespace操作。

  1. 首先需要调用C接口对HSAK UIO组件进行初始化,如果已经初始化过了,就不需要再调用了。

    libstorage_init_module

  2. 根据业务需要,调用相应的接口进行盘操作,以下接口可单独调用:

    • libstorage_create_namespace

    • libstorage_delete_namespace

    • libstorage_delete_all_namespace

    • libstorage_nvme_create_ctrlr

    • libstorage_nvme_delete_ctrlr

    • libstorage_nvme_reload_ctrlr

    • libstorage_low_level_format_nvm

    • libstorage_deallocate_block

  3. 最后如果退出程序,则需要销毁HSAK UIO,如果还有其他业务在使用,不需要退出,则不用销毁。

    libstorage_exit_module

    接口名称功能描述
    libstorage_create_namespace在指定控制器上创建namespace(前提是控制器具有namespace管理能力)
    libstorage_delete_namespace在指定控制器上删除namespace。
    libstorage_delete_all_namespace删除指定控制器上所有namespace。
    libstorage_nvme_create_ctrlr根据PCI地址创建NVMe控制器
    libstorage_nvme_delete_ctrlr根据控制器名称销毁NVMe控制器
    libstorage_nvme_reload_ctrlr根据传入的配置文件自动创建或销毁NVMe控制器
    libstorage_low_level_format_nvm低级格式化NVMe盘
    libstorage_deallocate_block告知NVMe盘可释放的块,用于垃圾回收

数据面盘信息查询

在HSAK的IO数据面提供一组C接口,用于查询盘信息,上层业务可根据查询到的信息进行相关的业务逻辑处理。

  1. 首先需要调用C接口对HSAK UIO进行初始化,如果已经初始化过了,就不需要再调用了。

    libstorage_init_module

  2. 根据业务需要,调用相应接口进行信息查询,以下接口可单独调用:

    • libstorage_get_nvme_ctrlr_info

    • libstorage_get_mgr_info_by_esn

    • libstorage_get_mgr_smart_by_esn

    • libstorage_get_bdev_ns_info

    • libstorage_get_ctrl_ns_info

  3. 最后如果退出程序,则需要销毁HSAK UIO,如果还有其他业务在使用,不需要退出,则不用销毁

    libstorage_exit_module

    接口名称功能描述
    libstorage_get_nvme_ctrlr_info获取所有控制器信息。
    libstorage_get_mgr_info_by_esn数据面获取设备序列号(ESN)对应的磁盘的管理信息。
    libstorage_get_mgr_smart_by_esn数据面获取设备序列号(ESN)对应的磁盘的SMART信息。
    libstorage_get_bdev_ns_info根据设备名称,获取namespace信息。
    libstorage_get_ctrl_ns_info根据控制器名称,获取所有namespace信息。

管理面盘信息查询场景

在HSAK的管理面组件ublock提供一组C接口,用于支持在管理面对盘信息进行查询。

  1. 首先调用C接口对HSAK ublock服务端进行初始化

  2. 根据业务需要,在另一个进程中调用HSAK UIO组件初始化接口。

  3. 如果需要多个进程查询盘信息,则初始化ublock客户端

  4. 可在ublock服务端进程或客户端进程调用如下接口进行相应的信息查询业务:

  5. 对于块设备列表,在获取相应信息后需要调用以下接口进行资源释放:

  6. 最后如果退出程序,则需要销毁HSAK ublock模块(服务端和客户端销毁方法相同)。

    接口名称功能描述
    init_ublock初始化ublock功能模块,本接口必须在其他所有ublock接口之前被调用,同一个进程只能初始化一次,原因是init_ublock接口中会初始化DPDK,而DPDK初始化所分配的内存同进程PID绑定,一个PID只能绑定一块内存,且DPDK没有提供释放这块内存的接口,只能通过进程退出来释放。
    ublock_init本身是对init_ublock接口的宏定义,可理解为将ublock初始化为需要RPC服务。
    ublock_init_norpc本身是对init_ublock接口的宏定义,可理解为ublock初始化为无RPC服务。
    ublock_get_bdevs业务进程通过调用本接口获取设备列表,获取的设备列表中只有PCI地址,不包含具体设备信息,需要获取具体设备信息,请调用接口ublock_get_bdev。
    ublock_get_bdev进程通过调用本接口获取具体某个设备的信息,设备信息中包括:设备的序列号、型号、fw版本号信息以字符数组形式保持,不是字符串形式。
    ublock_get_bdev_by_esn进程通过调用该接口,根据给定的ESN号获取对应设备的信息,设备信息中:序列号、型号、fw版本号。
    ublock_get_SMART_info进程通过调用本接口获取指定设备的SMART信息。
    ublock_get_SMART_info_by_esn进程通过调用本接口获取ESN号对应设备的SMART信息。
    ublock_get_error_log_info进程通过调用本接口获取设备的Error log信息。
    ublock_get_log_page进程通过调用本接口获取指定设备,指定log page的信息。
    ublock_free_bdevs进程通过调用本接口释放设备列表。
    ublock_free_bdev进程通过调用本接口释放设备资源。
    ublock_fini销毁ublock功能模块,本接口将销毁ublock模块以及内部创建的资源,本接口同ublock初始化接口需要配对使用。

日志管理

HSAK的日志当前是通过syslog默认输出到/var/log/messages中,由操作系统的rsyslog服务管理。如果您需要自定义日志目录,可以通过rsyslog配置。

  1. 首先需要在配置文件/etc/rsyslog.conf中增加如下修改:

  2. 重启rsyslog服务:

    if ($programname == 'LibStorage') then {
        action(type="omfile" fileCreateMode="0600" file="/var/log/HSAK/run.log")
        stop
    }
    
  3. 启动HSAK进程,日志信息即重定向到对应目录。

    sysemctl restart rsyslog
    
  4. 重定向日志如果需要转储,需要用户在/etc/logrotate.d/syslog文件中手动配置。

文档捉虫

“有虫”文档片段

问题描述

提交类型 issue
有点复杂...
找人问问吧。
PR
小问题,全程线上修改...
一键搞定!
问题类型
规范和低错类

● 错别字或拼写错误;标点符号使用错误;

● 链接错误、空单元格、格式错误;

● 英文中包含中文字符;

● 界面和描述不一致,但不影响操作;

● 表述不通顺,但不影响理解;

● 版本号不匹配:如软件包名称、界面版本号;

易用性

● 关键步骤错误或缺失,无法指导用户完成任务;

● 缺少必要的前提条件、注意事项等;

● 图形、表格、文字等晦涩难懂;

● 逻辑不清晰,该分类、分项、分步骤的没有给出;

正确性

● 技术原理、功能、规格等描述和软件不一致,存在错误;

● 原理图、架构图等存在错误;

● 命令、命令参数等错误;

● 代码片段错误;

● 命令无法完成对应功能;

● 界面错误,无法指导操作;

风险提示

● 对重要数据或系统存在风险的操作,缺少安全提示;

内容合规

● 违反法律法规,涉及政治、领土主权等敏感词;

● 内容侵权;

您对文档的总体满意度

非常不满意
非常满意
提交
根据您的反馈,会自动生成issue模板。您只需点击按钮,创建issue即可。