目录

开发适用SCSI协议的设备驱动

简介

在企业级存储解决方案和工业应用场景中,对SCSI(Small Computer System Interface,小型计算机系统接口)设备的使用需求广泛存在,例如:磁盘阵列、磁带库以及特定类型的存储服务器等。当操作系统中缺乏针对这些设备的适配驱动时,会导致设备连接后无法被识别或正常使用。ScsiPeripheralDDK(SCSI Peripheral Driver Development Kit)是为开发者提供的专门用于开发SCSI设备驱动程序的套件,支持开发者基于用户态,在应用层进行SCSI设备驱动的开发。

ScsiPeripheralDDK支持SPC(SCSI Primary Commands)、SBC(SCSI Block Commands)和MMC(MultiMedia Commands)三个命令集中的七个常用命令(INQUIRY、READ CAPACITY、TEST UNIT READY、REQUEST SENSE、READ、WRITE和VERIFY),使得开发者可以使用相对熟悉的命令进行设备驱动开发。

[h2]基本概念

在进行ScsiPeripheralDDK开发前,开发者应了解以下基本概念:

[h2]实现原理

非标外设应用通过扩展外设管理服务获取SCSI设备的ID,通过RPC将ID和要操作的动作下发给SCSI驱动应用,SCSI驱动应用通过调用ScsiPeripheralDDK接口可获取SCSI设备基本信息,读写数据,DDK接口使用HDI服务将指令下发至内核驱动,内核驱动使用指令与设备通信。

图1 ScsiPeripheralDDK调用原理

[h2]约束与限制

环境搭建

请参考环境准备完成开发前的准备工作。

开发指导

[h2]接口说明

名称 描述
int32_t OH_ScsiPeripheral_Init(void) 初始化ScsiPeripheralDDK。
int32_t OH_ScsiPeripheral_Release(void) 释放ScsiPeripheralDDK。
int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev) 打开deviceId和interfaceIndex指定的SCSI设备。其中,deviceId可以通过USB设备的总线编号左移32位后、同其设备地址进行或运算得到,interfaceIndex为需要打开的USB接口的索引值。
int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev) 关闭SCSI设备。
int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request, ScsiPeripheral_Response *response) 检查逻辑单元是否已经准备好。
int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request, ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response) 查询SCSI设备的基本信息。
int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request, ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response) 获取SCSI设备的容量信息。
int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request, ScsiPeripheral_Response *response) 获取sense data(SCSI设备返回给主机的信息,用于报告设备的状态、错误信息以及诊断信息)。
int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, ScsiPeripheral_Response *response) 从指定逻辑块读取数据。
int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, ScsiPeripheral_Response *response) 写数据到设备的指定逻辑块。
int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request, ScsiPeripheral_Response *response) 校验指定逻辑块。
int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request, ScsiPeripheral_Response *response) 以CDB方式发送SCSI命令。
int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size, ScsiPeripheral_DeviceMemMap **devMmap) 创建缓冲区。
int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap) 销毁缓冲区。
int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen, ScsiPeripheral_BasicSenseInfo *senseInfo) 解析基本的sense data,包括Information、Command specific information、Sense key specific字段。

详细的接口说明请参考ScsiPeripheralDDK。

[h2]开发步骤

以下步骤描述了如何使用ScsiPeripheralDDK开发非标SCSI外设的驱动:

添加动态链接库

CMakeLists.txt中添加以下lib。

libscsi.z.so

头文件

#include <scsi_peripheral/scsi_peripheral_api.h>
#include <scsi_peripheral/scsi_peripheral_types.h>
  1. 初始化DDK。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Init 初始化ScsiPeripheralDDK。

    // 初始化SCSI Peripheral DDK
    int32_t ret = OH_ScsiPeripheral_Init();
  2. 打开设备。

    初始化ScsiPeripheralDDK后,使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Open 打开SCSI设备。

    ret = OH_ScsiPeripheral_Open(g_devHandle, interfaceIndex, &g_scsiPeripheralDevice);
  3. 创建缓冲区(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_CreateDeviceMemMap 创建内存缓冲区devMmap。

    ret = OH_ScsiPeripheral_CreateDeviceMemMap(g_scsiPeripheralDevice, DEVICE_MEM_MAP_SIZE, &g_scsiDeviceMemMap);
  4. 检查逻辑单元是否已经准备好(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_TestUnitReady 检查逻辑单元是否已经准备好。

    int32_t ret = OH_ScsiPeripheral_TestUnitReady(g_scsiPeripheralDevice, &request, &response);
  5. 查询SCSI设备的基本信息(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Inquiry 获取SCSI设备的基本信息。

    int32_t ret = OH_ScsiPeripheral_Inquiry(g_scsiPeripheralDevice, &inquiryRequest, &inquiryInfo, &response);
  6. 获取SCSI设备的容量信息(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_ReadCapacity10 获取SCSI设备容量信息。

    ret = OH_ScsiPeripheral_ReadCapacity10(g_scsiPeripheralDevice, &readCapacityRequest, &capacityInfo, &response);
  7. 获取sense data(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_RequestSense 获取sense data。

    int32_t ret = OH_ScsiPeripheral_RequestSense(g_scsiPeripheralDevice, &senseRequest, &response);
  8. 解析sense data(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_ParseBasicSenseInfo 解析基本的sense data,包括Information、Command specific information、Sense key specific字段。

    int32_t ret = OH_ScsiPeripheral_ParseBasicSenseInfo(response.senseData, SCSIPERIPHERAL_MAX_SENSE_DATA_LEN,
        &senseInfo);
  9. 读取数据(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Read10 读取指定逻辑块的数据。

    int32_t ret = OH_ScsiPeripheral_Read10(g_scsiPeripheralDevice, &request, &response);
  10. 写入数据(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Write10 写数据到设备指定逻辑块。

    int32_t ret = OH_ScsiPeripheral_Write10(g_scsiPeripheralDevice, &request, &response);
  11. 校验指定逻辑块(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Verify10 校验指定逻辑块。

    int32_t ret = OH_ScsiPeripheral_Verify10(g_scsiPeripheralDevice, &request, &response);
  12. 以CDB方式发送SCSI命令(可选)。

    使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_SendRequestByCdb 发送SCSI命令。

    int32_t ret = OH_ScsiPeripheral_SendRequestByCdb(g_scsiPeripheralDevice, &request, &response);
  13. 销毁缓冲区(可选)。

    在所有请求处理完毕,程序退出前,使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_DestroyDeviceMemMap 销毁缓冲区。

    ret = OH_ScsiPeripheral_DestroyDeviceMemMap(g_scsiDeviceMemMap);
  14. 关闭设备。

    在销毁缓冲区后,使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Close 关闭设备。

    ret = OH_ScsiPeripheral_Close(&g_scsiPeripheralDevice);
  15. 释放DDK。

    在关闭SCSI设备后,使用 scsi_peripheral_api.h 的 OH_ScsiPeripheral_Release 释放ScsiPeripheralDDK。

    ret = OH_ScsiPeripheral_Release();

[h2]调测验证

驱动应用侧开发完成后,可在HarmonyOS设备上安装应用,测试步骤如下:

  1. 在设备上点击驱动应用,应用在设备上被拉起。
  2. 应用可以读取到SCSI设备的基础信息。
  3. 选择对应的SCSI命令,输入参数,点击发送按钮,可以执行对应的SCSI命令。
  4. 也可以通过输入方向、CDB数据及CDB长度,点击发送按钮,执行对应的SCSI命令。