From a548094f482505873027621c754177d824445f33 Mon Sep 17 00:00:00 2001 From: wu-chengwen Date: Mon, 10 Oct 2022 21:13:24 +0800 Subject: [PATCH] feature(usb):update usb js docs and driver docs Signed-off-by: wu-chengwen --- .../application-dev/device/usb-guidelines.md | 3 +- .../reference/apis/js-apis-usb-deprecated.md | 862 ++++++++++++++++++ .../reference/apis/js-apis-usb.md | 136 ++- .../reference/errorcodes/errcode-usb.md | 19 + .../driver/driver-peripherals-usb-des.md | 153 ++-- 5 files changed, 1074 insertions(+), 99 deletions(-) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md create mode 100644 zh-cn/application-dev/reference/errorcodes/errcode-usb.md diff --git a/zh-cn/application-dev/device/usb-guidelines.md b/zh-cn/application-dev/device/usb-guidelines.md index cd215f3a67..f144e2cf39 100644 --- a/zh-cn/application-dev/device/usb-guidelines.md +++ b/zh-cn/application-dev/device/usb-guidelines.md @@ -4,7 +4,7 @@ ## 场景介绍 -Host模式下，可以获取到已经连接的设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。 +Host模式下，可以获取到已经连接的USB设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。 ## 接口说明 @@ -19,6 +19,7 @@ USB类开放能力如下，具体请查阅[API参考文档](../reference/apis/js | ------------------------------------------------------------ | ------------------------------------------------------------ | | hasRight(deviceName: string): boolean | 如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 | | requestRight(deviceName: string): Promise<boolean> | 请求给定软件包的临时权限以访问设备。 | +| removeRight(deviceName: string): boolean | 移除软件包对设备的访问权限。| | connectDevice(device: USBDevice): Readonly<USBDevicePipe> | 根据`getDevices()`返回的设备信息打开USB设备。 | | getDevices(): Array<Readonly<USBDevice>> | 返回USB设备列表。 | | setConfiguration(pipe: USBDevicePipe, config: USBConfig): number | 设置设备的配置。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md b/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md new file mode 100644 index 0000000000..0c20c4b3b4 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md @@ -0,0 +1,862 @@ +# USB管理 + +本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。 + +> **说明：** +> +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +> 从API version 9开始，该接口不再维护，推荐使用新接口[`@ohos.usbV9`](js-apis-usb.md)。 + +## 导入模块 + +```js +import usb from "@ohos.usb"; +``` + +## usb.getDevices + +getDevices(): Array<Readonly<USBDevice>> + +获取USB设备列表。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------------------- | ------- | +| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 | + +**示例：** + +```js +let devicesList = usb.getDevices(); +console.log(`devicesList = ${JSON.stringify(devicesList)}`); +//devicesList 返回的数据结构 +//此处提供一个简单的示例，如下 +[ + { + name: "1-1", + serial: "", + manufacturerName: "", + productName: "", + version: "", + vendorId: 7531, + productId: 2, + clazz: 9, + subclass: 0, + protocol: 1, + devAddress: 1, + busNum: 1, + configs: [ + { + id: 1, + attributes: 224, + isRemoteWakeup: true, + isSelfPowered: true, + maxPower: 0, + name: "1-1", + interfaces: [ + { + id: 0, + protocol: 0, + clazz: 9, + subclass: 0, + alternateSetting: 0, + name: "1-1", + endpoints: [ + { + address: 129, + attributes: 3, + interval: 12, + maxPacketSize: 4, + direction: 128, + number: 1, + type: 3, + interfaceId: 0, + }, + ], + }, + ], + }, + ], + }, +] +``` + +## usb.connectDevice + +connectDevice(device: USBDevice): Readonly<USBDevicePipe> + +打开USB设备。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| device | [USBDevice](#usbdevice) | 是 | USB设备信息。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | + +**示例：** + +```js +let devicepipe= usb.connectDevice(device); +console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); +``` + +## usb.hasRight + +hasRight(deviceName: string): boolean + +判断是否有权访问该设备。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 | + +**示例：** + +```js +let devicesName="1-1"; +let bool = usb.hasRight(devicesName); +console.log(bool); +``` + +## usb.requestRight + +requestRight(deviceName: string): Promise<boolean> + +请求软件包的临时权限以访问设备。使用Promise异步回调。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 | + +**示例：** + +```js +let devicesName="1-1"; +usb.requestRight(devicesName).then((ret) => { + console.log(`requestRight = ${JSON.stringify(ret)}`); +}); +``` + +## usb.claimInterface + +claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number + +注册通信接口。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引。 | +| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.claimInterface(devicepipe, interfaces); +console.log(`claimInterface = ${ret}`); +``` + +## usb.releaseInterface + +releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number + +释放注册过的通信接口。 + +需要调用[usb.claimInterface](#usbclaiminterface)先获取接口，才能使用此方法释放接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 释放接口成功返回0；释放接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.releaseInterface(devicepipe, interfaces); +console.log(`releaseInterface = ${ret}`); +``` + +## usb.setConfiguration + +setConfiguration(pipe: USBDevicePipe, config: USBConfig): number + +设置设备配置。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及config；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| config | [USBConfig](#usbconfig) | 是 | 用于确定需要设置的配置。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.setConfiguration(devicepipe, config); +console.log(`setConfiguration = ${ret}`); +``` + +## usb.setInterface + +setInterface(pipe: USBDevicePipe, iface: USBInterface): number + +设置设备接口。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数；调用[usb.claimInterface](#usbclaiminterface)注册通信接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------------------------------- | --- | ------------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | +| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.setInterface(devicepipe, interfaces); +console.log(`setInterface = ${ret}`); +``` + +## usb.getRawDescriptor + +getRawDescriptor(pipe: USBDevicePipe): Uint8Array + +获取原始的USB描述符。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Uint8Array | 返回获取的原始数据；失败返回undefined。 | + +**示例：** + +```js +let ret = usb.getRawDescriptor(devicepipe); +``` + +## usb.getFileDescriptor + +getFileDescriptor(pipe: USBDevicePipe): number + +获取文件描述符。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | -------------------- | +| number | 返回设备对应的文件描述符；失败返回-1。 | + +**示例：** + +```js +let ret = usb.getFileDescriptor(devicepipe); +``` + +## usb.controlTransfer + +controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number> + +控制传输。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | +| contrlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数。 | +| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | + +**示例：** + +```js +usb.controlTransfer(devicepipe, USBControlParams).then((ret) => { + console.log(`controlTransfer = ${JSON.stringify(ret)}`); +}) +``` + +## usb.bulkTransfer + +bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number> + +批量传输。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备信息列表以及endpoint；再调用[usb.requestRight](#usbrequestright)获取设备请求权限；然后调用[usb.connectDevice](#usbconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usb.claimInterface](#usbclaiminterface)；再调用usb.bulkTransfer接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | +| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口。 | +| buffer | Uint8Array | 是 | 用于写入或读取的缓冲区。 | +| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。| + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | + +**示例：** + +```js +//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。 +//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后； +//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。 +usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => { + console.log(`bulkTransfer = ${JSON.stringify(ret)}`); +}); +``` + +## usb.closePipe + +closePipe(pipe: USBDevicePipe): number + +关闭设备消息控制通道。 + +需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 | + +**示例：** + +```js +let ret = usb.closePipe(devicepipe); +console.log(`closePipe = ${ret}`); +``` + +## usb.usbFunctionsFromString9+ + +usbFunctionsFromString(funcs: string): number + +在设备模式下，将字符串形式的USB功能列表转化为数字掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------- | +| funcs | string | 是 | 字符串形式的功能列表。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------ | +| number | 转化后的数字掩码。 | + +**示例：** + +```js +let funcs = "acm"; +let ret = usb.usbFunctionsFromString(funcs); +``` + +## usb.usbFunctionsToString9+ + +usbFunctionsToString(funcs: FunctionType): string + +在设备模式下，将数字掩码形式的USB功能列表转化为字符串。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | ----------------- | +| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------ | +| string | 转化后的字符串形式的功能列表。 | + +**示例：** + +```js +let funcs = ACM | ECM; +let ret = usb.usbFunctionsToString(funcs); +``` + +## usb.setCurrentFunctions9+ + +setCurrentFunctions(funcs: FunctionType): Promise\ + +在设备模式下，设置当前的USB功能列表。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | ----------------- | +| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 | + +**示例：** + +```js +let funcs = HDC; +let ret = usb.setCurrentFunctions(funcs); +``` + +## usb.getCurrentFunctions9+ + +getCurrentFunctions(): FunctionType + +在设备模式下，获取当前的USB功能列表的数字组合掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ------------------------------ | --------------------------------- | +| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 | + +**示例：** + +```js +let ret = usb.getCurrentFunctions(); +``` + +## usb.getPorts9+ + +getPorts(): Array\ + +获取所有物理USB端口描述信息。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | --------------------- | +| [Array\](#usbport9) | USB端口描述信息列表。 | + +**示例：** + +```js +let ret = usb.getPorts(); +``` + +## usb.getSupportedModes9+ + +getSupportedModes(portId: number): PortModeType + +获取指定的端口支持的模式列表的组合掩码。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------- | +| portId | number | 是 | 端口号。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------ | -------------------------- | +| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 | + +**示例：** + +```js +let ret = usb.getSupportedModes(0); +``` + +## usb.setPortRoles9+ + +setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\ + +设置指定的端口支持的角色模式，包含充电角色、数据传输角色。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | -------------------------------- | ---- | ---------------- | +| portId | number | 是 | 端口号。 | +| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 | +| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 | + +**示例：** + +```js +let ret = usb.getSupportedModes(0); +``` + +## USBEndpoint + +通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ------------- | ------------------------------------------- | ------------- | +| address | number | 端点地址。 | +| attributes | number | 端点属性。 | +| interval | number | 端点间隔。 | +| maxPacketSize | number | 端点最大数据包大小。 | +| direction | [USBRequestDirection](#usbrequestdirection) | 端点的方向。 | +| number | number | 端点号。 | +| type | number | 端点类型。 | +| interfaceId | number | 端点所属的接口的唯一标识。 | + +## USBInterface + +一个[USBConfig](#usbconfig)中可以含有多个USBInterface，每个USBInterface提供一个功能。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | ---------------------------------------- | --------------------- | +| id | number | 接口的唯一标识。 | +| protocol | number | 接口的协议。 | +| clazz | number | 设备类型。 | +| subClass | number | 设备子类。 | +| alternateSetting | number | 在同一个接口中的多个描述符中进行切换设置。 | +| name | string | 接口名称。 | +| endpoints | Array<[USBEndpoint](#usbendpoint)> | 当前接口所包含的端点。 | + +## USBConfig + +USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| -------------- | ------------------------------------------------ | --------------- | +| id | number | 配置的唯一标识。 | +| attributes | number | 配置的属性。 | +| maxPower | number | 最大功耗，以毫安为单位。 | +| name | string | 配置的名称，可以为空。 | +| isRemoteWakeup | boolean | 检查当前配置是否支持远程唤醒。 | +| isSelfPowered | boolean | 检查当前配置是否支持独立电源。 | +| interfaces | Array <[USBInterface](#usbinterface)> | 配置支持的接口属性。 | + +## USBDevice + +USB设备信息。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | ------------------------------------ | ---------- | +| busNum | number | 总线地址。 | +| devAddress | number | 设备地址。 | +| serial | string | 序列号。 | +| name | string | 设备名字。 | +| manufacturerName | string | 产商信息。 | +| productName | string | 产品信息。 | +| version | string | 版本。 | +| vendorId | number | 厂商ID。 | +| productId | number | 产品ID。 | +| clazz | number | 设备类。 | +| subClass | number | 设备子类。 | +| protocol | number | 设备协议码。 | +| configs | Array<[USBConfig](#usbconfig)> | 设备配置描述符信息。 | + +## USBDevicePipe + +USB设备消息传输通道，用于确定设备。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------- | ------ | ----- | +| busNum | number | 总线地址。 | +| devAddress | number | 设备地址。 | + +## USBControlParams + +控制传输参数。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ------- | ----------------------------------------------- | ---------------- | +| request | number | 请求类型。 | +| target | [USBRequestTargetType](#usbrequesttargettype) | 请求目标类型。 | +| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 请求控制类型。 | +| value | number | 请求参数。 | +| index | number | 请求参数value对应的索引值。 | +| data | Uint8Array | 用于写入或读取的缓冲区。 | + +## USBPort9+ + +USB设备端口。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| -------------- | -------------------------------- | ----------------------------------- | +| id | number | USB端口唯一标识。 | +| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 | +| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 | + +## USBPortStatus9+ + +USB设备端口角色信息。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 参数类型 | 说明 | +| ---------------- | -------- | ---------------------- | +| currentMode | number | 当前的USB模式。 | +| currentPowerRole | number | 当前设备充电模式。 | +| currentDataRole | number | 当前设备数据传输模式。 | + +## USBRequestTargetType + +请求目标类型。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ---------------------------- | ---- | ------ | +| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | +| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | +| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | +| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | + +## USBControlRequestType + +控制请求类型。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------------------------- | ---- | ------ | +| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | +| USB_REQUEST_TYPE_CLASS | 1 | 类。 | +| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | + +## USBRequestDirection + +请求方向。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| --------------------------- | ---- | ------------------------ | +| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | +| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | + +## FunctionType9+ + +USB设备侧功能。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------------ | ---- | ---------- | +| NONE | 0 | 没有功能。 | +| ACM | 1 | acm功能。 | +| ECM | 2 | ecm功能。 | +| HDC | 4 | hdc功能。 | +| MTP | 8 | 暂不支持。 | +| PTP | 16 | 暂不支持。 | +| RNDIS | 32 | 暂不支持。 | +| MIDI | 64 | 暂不支持。 | +| AUDIO_SOURCE | 128 | 暂不支持。 | +| NCM | 256 | 暂不支持。 | + +## PortModeType9+ + +USB端口模式类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| --------- | ---- | ---------------------------------------------------- | +| NONE | 0 | 无。 | +| UFP | 1 | 数据上行，需要外部供电。 | +| DFP | 2 | 数据下行，对外提供电源。 | +| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | +| NUM_MODES | 4 | 当前不支持。 | + +## PowerRoleType9+ + +电源角色类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------ | ---- | ---------- | +| NONE | 0 | 无。 | +| SOURCE | 1 | 外部供电。 | +| SINK | 2 | 内部供电。 | + +## DataRoleType9+ + +数据角色类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +| 名称 | 值 | 说明 | +| ------ | ---- | ------------ | +| NONE | 0 | 无。 | +| HOST | 1 | 主设备角色。 | +| DEVICE | 2 | 从设备角色。 | + diff --git a/zh-cn/application-dev/reference/apis/js-apis-usb.md b/zh-cn/application-dev/reference/apis/js-apis-usb.md index 5e0aee35a7..ffa8e471f0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-usb.md +++ b/zh-cn/application-dev/reference/apis/js-apis-usb.md @@ -1,22 +1,22 @@ # USB管理 -本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。 +本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。 > **说明：** > -> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 ```js -import usb from "@ohos.usb"; +import usb from "@ohos.usbV9"; ``` ## usb.getDevices getDevices(): Array<Readonly<USBDevice>> -获取USB设备列表。 +获取接入主设备的USB设备列表。如果没有设备接入，那么将会返回一个空的列表。 **系统能力：** SystemCapability.USB.USBManager @@ -89,7 +89,7 @@ connectDevice(device: USBDevice): Readonly<USBDevicePipe> 打开USB设备。 -需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。 +需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)请求使用该设备的权限。 **系统能力：** SystemCapability.USB.USBManager @@ -105,10 +105,26 @@ connectDevice(device: USBDevice): Readonly<USBDevicePipe> | -------- | -------- | | Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | +**错误码：** + +以下错误码的详细介绍参见[USB错误码](../errorcodes/errcode-usb.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------- | +| 14400001 |Permission denied. Need call requestRight to get permission. | + **示例：** ```js -let devicepipe= usb.connectDevice(device); +let devicesList = usb.getDevices(); +if (devicesList.length == 0) { + console.log(`device list is empty`); + return; +} + +let device = devicesList[0]; +usb.requestRight(device.name); +let devicepipe = usb.connectDevice(device); console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); ``` @@ -169,6 +185,70 @@ usb.requestRight(devicesName).then((ret) => { }); ``` +## usb.removeRight + +removeRight(deviceName: string): boolean; + +移除软件包访问设备的权限。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | 返回权限移除结果。返回true表示权限移除成功；返回false则表示权限移除失败。 | + +**示例：** + +```js +let devicesName="1-1"; +if (usb.removeRight(devicesName) { + console.log(`Succeed in removing right`); +} +``` + +## usb.addRight + +addRight(bundleName: string, deviceName: string): boolean; + +添加软件包访问设备的权限。 + +[requestRight](#usbrequestright)的会触发弹框请求用户授权；addRight不会触发弹框，而是直接添加软件包访问设备的权限。 + +**系统接口：** 此接口为系统接口。 + +**系统能力：** SystemCapability.USB.USBManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 是 | 设备名称。 | +| bundleName | string | 是 | 软件包名称。| + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 | + +**示例：** + +```js +let devicesName = "1-1"; +let bundleName = "com.example.hello"; +if (usb.addRight(bundleName, devicesName) { + console.log(`Succeed in adding right`); +} +``` + ## usb.claimInterface claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number @@ -443,7 +523,7 @@ let ret = usb.closePipe(devicepipe); console.log(`closePipe = ${ret}`); ``` -## usb.usbFunctionsFromString9+ +## usb.usbFunctionsFromString usbFunctionsFromString(funcs: string): number @@ -472,7 +552,7 @@ let funcs = "acm"; let ret = usb.usbFunctionsFromString(funcs); ``` -## usb.usbFunctionsToString9+ +## usb.usbFunctionsToString usbFunctionsToString(funcs: FunctionType): string @@ -486,7 +566,7 @@ usbFunctionsToString(funcs: FunctionType): string | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | +| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | **返回值：** @@ -501,7 +581,7 @@ let funcs = ACM | ECM; let ret = usb.usbFunctionsToString(funcs); ``` -## usb.setCurrentFunctions9+ +## usb.setCurrentFunctions setCurrentFunctions(funcs: FunctionType): Promise\ @@ -515,7 +595,7 @@ setCurrentFunctions(funcs: FunctionType): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 | +| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | **返回值：** @@ -530,7 +610,7 @@ let funcs = HDC; let ret = usb.setCurrentFunctions(funcs); ``` -## usb.getCurrentFunctions9+ +## usb.getCurrentFunctions getCurrentFunctions(): FunctionType @@ -544,7 +624,7 @@ getCurrentFunctions(): FunctionType | 类型 | 说明 | | ------------------------------ | --------------------------------- | -| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 | +| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 | **示例：** @@ -552,7 +632,7 @@ getCurrentFunctions(): FunctionType let ret = usb.getCurrentFunctions(); ``` -## usb.getPorts9+ +## usb.getPorts getPorts(): Array\ @@ -566,7 +646,7 @@ getPorts(): Array\ | 类型 | 说明 | | ----------------------------- | --------------------- | -| [Array\](#usbport9) | USB端口描述信息列表。 | +| [Array\](#usbport) | USB端口描述信息列表。 | **示例：** @@ -574,7 +654,7 @@ getPorts(): Array\ let ret = usb.getPorts(); ``` -## usb.getSupportedModes9+ +## usb.getSupportedModes getSupportedModes(portId: number): PortModeType @@ -594,7 +674,7 @@ getSupportedModes(portId: number): PortModeType | 类型 | 说明 | | ------------------------------ | -------------------------- | -| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 | +| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 | **示例：** @@ -602,7 +682,7 @@ getSupportedModes(portId: number): PortModeType let ret = usb.getSupportedModes(0); ``` -## usb.setPortRoles9+ +## usb.setPortRoles setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\ @@ -617,8 +697,8 @@ setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): | 参数名 | 类型 | 必填 | 说明 | | --------- | -------------------------------- | ---- | ---------------- | | portId | number | 是 | 端口号。 | -| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 | -| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 | +| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 | +| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 | **返回值：** @@ -729,7 +809,7 @@ USB设备消息传输通道，用于确定设备。 | index | number | 请求参数value对应的索引值。 | | data | Uint8Array | 用于写入或读取的缓冲区。 | -## USBPort9+ +## USBPort USB设备端口。 @@ -740,10 +820,10 @@ USB设备端口。 | 名称 | 参数类型 | 说明 | | -------------- | -------------------------------- | ----------------------------------- | | id | number | USB端口唯一标识。 | -| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 | -| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 | +| supportedModes | [PortModeType](#portmodetype) | USB端口所支持的模式的数字组合掩码。 | +| status | [USBPortStatus](#usbportstatus) | USB端口角色。 | -## USBPortStatus9+ +## USBPortStatus USB设备端口角色信息。 @@ -793,7 +873,7 @@ USB设备端口角色信息。 | USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | | USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | -## FunctionType9+ +## FunctionType USB设备侧功能。 @@ -814,7 +894,7 @@ USB设备侧功能。 | AUDIO_SOURCE | 128 | 暂不支持。 | | NCM | 256 | 暂不支持。 | -## PortModeType9+ +## PortModeType USB端口模式类型。 @@ -830,7 +910,7 @@ USB端口模式类型。 | DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | | NUM_MODES | 4 | 当前不支持。 | -## PowerRoleType9+ +## PowerRoleType 电源角色类型。 @@ -844,7 +924,7 @@ USB端口模式类型。 | SOURCE | 1 | 外部供电。 | | SINK | 2 | 内部供电。 | -## DataRoleType9+ +## DataRoleType 数据角色类型。 diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-usb.md b/zh-cn/application-dev/reference/errorcodes/errcode-usb.md new file mode 100644 index 0000000000..4a7910cc0b --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-usb.md @@ -0,0 +1,19 @@ +# USB服务错误码 + +## 14400001 连接USB设备被拒绝 + +**错误信息** + +Permission denied. Need call requestRight to get permission. + +**错误描述** + +当调用USB模块部分接口时，如果没有相关权限，会报此错误码。 + +**可能原因** + +没有获取到设备的使用权限。 + +**处理步骤** + +调用requestRight方法申请设备的使用权限。 \ No newline at end of file diff --git a/zh-cn/device-dev/driver/driver-peripherals-usb-des.md b/zh-cn/device-dev/driver/driver-peripherals-usb-des.md index bdb313049f..c7dc8513b9 100644 --- a/zh-cn/device-dev/driver/driver-peripherals-usb-des.md +++ b/zh-cn/device-dev/driver/driver-peripherals-usb-des.md @@ -36,51 +36,51 @@ USB驱动模型Host侧开放的API接口功能，参考USB Host驱动模型图 | int32_t UsbInitHostSdk(struct UsbSession \*\*session); | USB主机端驱动开发工具包初始化 | | int32_t UsbExitHostSdk(const struct UsbSession
\*session); | USB主机端驱动开发工具包退出 | | const struct UsbInterface \*UsbClaimInterface(const
struct UsbSession \*session, uint8_t busNum, uint8_t
usbAddr, uint8_t interfaceIndex); | 获取USB接口对象 | -| int UsbReleaseInterface(const struct UsbInterface
\*interfaceObj); | 释放USB接口对象 | -| int UsbAddOrRemoveInterface(const struct UsbSession
\*session, uint8_t busNum, uint8_t usbAddr, uint8_t
interfaceIndex, UsbInterfaceStatus status); | 增加移除接口 | +| int32_t UsbReleaseInterface(const struct UsbInterface
\*interfaceObj); | 释放USB接口对象 | +| int32_t UsbAddOrRemoveInterface(const struct UsbSession
\*session, uint8_t busNum, uint8_t usbAddr, uint8_t
interfaceIndex, UsbInterfaceStatus status); | 增加移除接口 | | UsbInterfaceHandle \*UsbOpenInterface(const struct
UsbInterface \*interfaceObj); | 打开USB对象接口 | | int32_t UsbCloseInterface(const UsbInterfaceHandle
\*interfaceHandle); | 关闭USB接口对象 | | int32_t UsbSelectInterfaceSetting(const
UsbInterfaceHandle \*interfaceHandle, uint8_t
settingIndex, struct UsbInterface \*\*interfaceObj); | 设置可选配置 | | int32_t UsbGetPipeInfo(const UsbInterfaceHandle
\*interfaceHandle, uint8_t settingIndex, uint8_t pipeId,
struct UsbPipeInfo \*pipeInfo); | 获取指定可选设置的管道信息 | | int32_t UsbClearInterfaceHalt(const
UsbInterfaceHandle \*interfaceHandle, uint8_t
pipeAddress); | 清除指定索引的管道状态 | -| struct UsbRequest \*UsbAllocRequest(const
UsbInterfaceHandle \*interfaceHandle, int isoPackets
, int length); | 分配请求对象 | -| int UsbFreeRequest(const struct UsbRequest
\*request); | 释放请求对象 | -| int UsbSubmitRequestAsync(const struct UsbRequest
\*request); | 发送异步请求 | +| struct UsbRequest \*UsbAllocRequest(const
UsbInterfaceHandle \*interfaceHandle, int32_t isoPackets
, int32_t length); | 分配请求对象 | +| int32_t UsbFreeRequest(const struct UsbRequest
\*request); | 释放请求对象 | +| int32_t UsbSubmitRequestAsync(const struct UsbRequest
\*request); | 发送异步请求 | | int32_t UsbFillRequest(const struct UsbRequest
\*request, const UsbInterfaceHandle \*interfaceHandle,
const struct UsbRequestParams \*params); | 填充请求 | -| sint UsbCancelRequest(const struct UsbRequest
\*request); | 取消异步请求 | -| int UsbSubmitRequestSync(const struct UsbRequest
\*request); | 发送同步请求 | +| int32_t UsbCancelRequest(const struct UsbRequest
\*request); | 取消异步请求 | +| int32_t UsbSubmitRequestSync(const struct UsbRequest
\*request); | 发送同步请求 | **表2** usb_raw_api.h | 接口名称 | 功能描述 | | -------- | -------- | -| int UsbRawInit(struct UsbSession \*\*session); | USB驱动开发工具包专家模式初始化 | -| int UsbRawExit(const struct UsbSession \*session); | USB驱动开发工具包专家模式退出 | +| int32_t UsbRawInit(struct UsbSession \*\*session); | USB驱动开发工具包专家模式初始化 | +| int32_t UsbRawExit(const struct UsbSession \*session); | USB驱动开发工具包专家模式退出 | | UsbRawHandle \*UsbRawOpenDevice(const struct
UsbSession \*session, uint8_t busNum, uint8_t
usbAddr); | 打开USB设备对象 | -| int UsbRawCloseDevice(const UsbRawHandle
\*devHandle); | 关闭USB设备对象 | -| int UsbRawSendControlRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbControlRequestData
\*requestData); | 执行同步控制传输 | -| int UsbRawSendBulkRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步批量传输 | -| int UsbRawSendInterruptRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步中断传输 | -| int UsbRawGetConfigDescriptor(const UsbRawDevice
\*rawDev, uint8_t configIndex, struct
UsbRawConfigDescriptor \*\*config); | 获取给定设备指定ID的设备配置描述符 | +| int32_t UsbRawCloseDevice(const UsbRawHandle
\*devHandle); | 关闭USB设备对象 | +| int32_t UsbRawSendControlRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbControlRequestData
\*requestData); | 执行同步控制传输 | +| int32_t UsbRawSendBulkRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步批量传输 | +| int32_t UsbRawSendInterruptRequest(const struct
UsbRawRequest \*request, const UsbRawHandle
\*devHandle, const struct UsbRequestData
\*requestData); | 执行同步中断传输 | +| int32_t UsbRawGetConfigDescriptor(const UsbRawDevice
\*rawDev, uint8_t configIndex, struct
UsbRawConfigDescriptor \*\*config); | 获取给定设备指定ID的设备配置描述符 | | void UsbRawFreeConfigDescriptor(const struct
UsbRawConfigDescriptor \*config); | 释放配置描述符内存空间 | -| int UsbRawGetConfiguration(const UsbRawHandle
\*devHandle, int \*config); | 获取当前激活配置 | -| int UsbRawSetConfiguration(const UsbRawHandle
\*devHandle, int config); | 设置当前激活配置 | -| int UsbRawGetDescriptor(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawDescriptorParam \*param, const unsigned char
\*data); | 获取描述符信息 | +| int32_t UsbRawGetConfiguration(const UsbRawHandle
\*devHandle, int32_t \*config); | 获取当前激活配置 | +| int32_t UsbRawSetConfiguration(const UsbRawHandle
\*devHandle, int32_t config); | 设置当前激活配置 | +| int32_t UsbRawGetDescriptor(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawDescriptorParam \*param, const unsigned char
\*data); | 获取描述符信息 | | UsbRawDevice \*UsbRawGetDevice(const UsbRawHandle
\*devHandle); | 由设备句柄获取设备指针 | -| int UsbRawGetDeviceDescriptor(const UsbRawDevice
\*rawDev, struct
UsbDeviceDescriptor \*desc); | 获取给定设备的USB设备描述符 | -| int UsbRawClaimInterface(const UsbRawHandle
\*devHandle, int
interfaceNumber); | 声明给定设备句柄上的接口 | -| int UsbRawReleaseInterface(const UsbRawHandle
\*devHandle, in
t interfaceNumber); | 释放之前声明的接口 | -| int UsbRawResetDevice(const UsbRawHandle
\*devHandle); | 复位设备 | -| struct UsbRawRequest \*UsbRawAllocRequest(const
UsbRawHandle
\*devHandle, int isoPackets, int length); | 分配一个带有指定数量的同步包描述符的传输请求 | -| int UsbRawFreeRequest(const struct UsbRawRequest
\*request); | 释放之前分配的传输请求 | -| int UsbRawFillBulkRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充批量传输请求所需信息 | -| int UsbRawFillControlSetup(const unsigned char \*setup,
const struct UsbControlRequestData \*requestData); | 填充控制传输设置包所需信息 | -| int UsbRawFillControlRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充控制传输请求所需信息 | -| int UsbRawFillInterruptRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充中断传输请求所需信息 | -| int UsbRawFillIsoRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充同步传输（Isochronous Transfers）请求所需信息 | -| int UsbRawSubmitRequest(const struct UsbRawRequest
\*request); | 提交一个传输请求 | -| int UsbRawCancelRequest(const struct UsbRawRequest
\*request); | 取消一个传输请求 | -| int UsbRawHandleRequests(const UsbRawHandle
\*devHandle); | 传输请求事件完成处理 | +| int32_t UsbRawGetDeviceDescriptor(const UsbRawDevice
\*rawDev, struct
UsbDeviceDescriptor \*desc); | 获取给定设备的USB设备描述符 | +| int32_t UsbRawClaimInterface(const UsbRawHandle
\*devHandle, int32_t
interfaceNumber); | 声明给定设备句柄上的接口 | +| int32_t UsbRawReleaseInterface(const UsbRawHandle
\*devHandle, in
t interfaceNumber); | 释放之前声明的接口 | +| int32_t UsbRawResetDevice(const UsbRawHandle
\*devHandle); | 复位设备 | +| struct UsbRawRequest \*UsbRawAllocRequest(const
UsbRawHandle
\*devHandle, int32_t isoPackets, int32_t length); | 分配一个带有指定数量的同步包描述符的传输请求 | +| int32_t UsbRawFreeRequest(const struct UsbRawRequest
\*request); | 释放之前分配的传输请求 | +| int32_t UsbRawFillBulkRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充批量传输请求所需信息 | +| int32_t UsbRawFillControlSetup(const unsigned char \*setup,
const struct UsbControlRequestData \*requestData); | 填充控制传输设置包所需信息 | +| int32_t UsbRawFillControlRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充控制传输请求所需信息 | +| int32_t UsbRawFillInterruptRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充中断传输请求所需信息 | +| int32_t UsbRawFillIsoRequest(const struct UsbRawRequest
\*request, const UsbRawHandle \*devHandle, const struct
UsbRawFillRequestData \*fillData); | 填充同步传输（Isochronous Transfers）请求所需信息 | +| int32_t UsbRawSubmitRequest(const struct UsbRawRequest
\*request); | 提交一个传输请求 | +| int32_t UsbRawCancelRequest(const struct UsbRawRequest
\*request); | 取消一个传输请求 | +| int32_t UsbRawHandleRequests(const UsbRawHandle
\*devHandle); | 传输请求事件完成处理 | USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型图。 @@ -89,19 +89,19 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型 | 接口名称 | 功能描述 | | -------- | -------- | | const struct UsbFnDevice \*UsbFnCreateDevice(const
char \*udcName, const struct UsbFnDescriptorData
\*descriptor); | 创建USB设备 | -| int UsbFnRemoveDevice(struct UsbFnDevice
\*fnDevice); | 删除USB设备 | +| int32_t UsbFnRemoveDevice(struct UsbFnDevice
\*fnDevice); | 删除USB设备 | | const struct UsbFnDevice \*UsbFnGetDevice(const char
\*udcName); | 获取USB设备 | **表4** usbfn_interface.h | 接口名称 | 功能描述 | | -------- | -------- | -| int UsbFnStartRecvInterfaceEvent(struct
UsbFnInterface \*interface, uint32_t eventMask,
UsbFnEventCallback callback, void \*context); | 开始接受Event事件 | -| int UsbFnStopRecvInterfaceEvent(struct
UsbFnInterface \*interface); | 停止接受Event事件 | +| int32_t UsbFnStartRecvInterfaceEvent(struct
UsbFnInterface \*interface, uint32_t eventMask,
UsbFnEventCallback callback, void \*context); | 开始接受Event事件 | +| int32_t UsbFnStopRecvInterfaceEvent(struct
UsbFnInterface \*interface); | 停止接受Event事件 | | UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface \*interface); | 打开一个接口 | -| int UsbFnCloseInterface(UsbFnInterfaceHandle handle); | 关闭一个接口 | -| int UsbFnGetInterfacePipeInfo(struct UsbFnInterface
\*interface, uint8_t pipeId, struct UsbFnPipeInfo \*info); | 获取管道信息 | -| int UsbFnSetInterfaceProp(const struct UsbFnInterface
\*interface, const char \*name, const char \*value); | 设置自定义属性 | +| int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle); | 关闭一个接口 | +| int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface
\*interface, uint8_t pipeId, struct UsbFnPipeInfo \*info); | 获取管道信息 | +| int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface
\*interface, const char \*name, const char \*value); | 设置自定义属性 | **表5** usbfn_request.h @@ -109,10 +109,10 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型 | -------- | -------- | | struct UsbFnRequest
\*UsbFnAllocCtrlRequest(UsbFnInterfaceHandle handle,
uint32_t len); | 申请一个控制请求 | | struct UsbFnRequest \*UsbFnAllocRequest(UsbFnInterfaceHandle handle,
uint8_t pipe, uint32_t len); | 申请一个数据请求 | -| int UsbFnFreeRequest(struct UsbFnRequest \*req); | 释放一个请求 | -| int UsbFnSubmitRequestAsync(struct UsbFnRequest
\*req); | 发送异步请求 | -| int UsbFnSubmitRequestSync(struct UsbFnRequest
\*req, uint32_t timeout); | 发送同步请求 | -| int UsbFnCancelRequest(struct UsbFnRequest \*req); | 取消请求 | +| int32_t UsbFnFreeRequest(struct UsbFnRequest \*req); | 释放一个请求 | +| int32_t UsbFnSubmitRequestAsync(struct UsbFnRequest
\*req); | 发送异步请求 | +| int32_t UsbFnSubmitRequestSync(struct UsbFnRequest
\*req, uint32_t timeout); | 发送同步请求 | +| int32_t UsbFnCancelRequest(struct UsbFnRequest \*req); | 取消请求 | ## 开发步骤 @@ -218,6 +218,9 @@ root { } } } +``` + +```cpp #include "usb_serial.h" #include "hdf_base.h" @@ -236,10 +239,10 @@ static struct UsbRequest *g_ctrlCmdRequest = NULL; static bool g_acmReleaseFlag = false; static uint8_t *g_acmReadBuffer = NULL; ... -static int SerialCtrlMsg(struct AcmDevice *acm, uint8_t request, +static int32_t SerialCtrlMsg(struct AcmDevice *acm, uint8_t request, uint16_t value, void *buf, uint16_t len) { - int ret; + int32_t ret; uint16_t index = acm->intPipe->interfaceId; struct UsbControlParams controlParams; struct UsbRequestParams params; @@ -299,7 +302,7 @@ static struct UsbPipeInfo *EnumePipe(const struct AcmDevice *acm, uint8_t interfaceIndex, UsbPipeType pipeType, UsbPipeDirection pipeDirection) { uint8_t i; - int ret; + int32_t ret; struct UsbInterfaceInfo *info = NULL; UsbInterfaceHandle *interfaceHandle = NULL; if (pipeType == USB_PIPE_TYPE_CONTROL) @@ -408,11 +411,11 @@ error: return HDF_FAILURE; } ... -static int AcmAllocReadRequests(struct AcmDevice *acm) +static int32_t AcmAllocReadRequests(struct AcmDevice *acm) { - int ret; + int32_t ret; struct UsbRequestParams readParams; - for (int i = 0; i < ACM_NR; i++) { + for (int32_t i = 0; i < ACM_NR; i++) { acm->readReq[i] = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataInPipe->interfaceId), 0, acm->readSize); // 分配待发送的readReq IO Request对象 if (!acm->readReq[i]) { HDF_LOGE("readReq request failed"); @@ -441,9 +444,9 @@ error: return HDF_ERR_MALLOC_FAIL; } -static int AcmAllocNotifyRequest(struct AcmDevice *acm) +static int32_t AcmAllocNotifyRequest(struct AcmDevice *acm) { - int ret; + int32_t ret; struct UsbRequestParams intParams = {}; acm->notifyReq = UsbAllocRequest(InterfaceIdToHandle(acm, acm->intPipe->interfaceId), 0, acm->intSize); // 分配待发送的中断IO Request对象 if (!acm->notifyReq) { @@ -474,7 +477,7 @@ error: static void AcmReleaseInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->iface[i]) { UsbReleaseInterface(acm->iface[i]); acm->iface[i] = NULL; @@ -488,7 +491,7 @@ static void AcmReleaseInterfaces(struct AcmDevice *acm) static int32_t AcmClaimInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { acm->iface[i] = GetUsbInterfaceById((const struct AcmDevice *)acm, acm->interfaceIndex[i]); // 获取UsbInterface接口对象 if (acm->iface[i] == NULL) { HDF_LOGE("%s: interface%d is null", __func__, acm->interfaceIndex[i]); @@ -511,7 +514,7 @@ static int32_t AcmClaimInterfaces(struct AcmDevice *acm) static void AcmCloseInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->devHandle[i]) { UsbCloseInterface(acm->devHandle[i]); acm->devHandle[i] = NULL; @@ -525,7 +528,7 @@ static void AcmCloseInterfaces(struct AcmDevice *acm) static int32_t AcmOpenInterfaces(struct AcmDevice *acm) { - for (int i = 0; i < acm->interfaceCnt; i++) { + for (int32_t i = 0; i < acm->interfaceCnt; i++) { if (acm->iface[i]) { acm->devHandle[i] = UsbOpenInterface(acm->iface[i]); // 打开获取到的UsbInterface接口对象 if (acm->devHandle[i] == NULL) { @@ -606,7 +609,7 @@ static int32_t AcmAllocRequests(struct AcmDevice *acm) return HDF_ERR_MALLOC_FAIL; } - for (int i = 0; i < ACM_NW; i++) { + for (int32_t i = 0; i < ACM_NW; i++) { struct AcmWb *snd = &(acm->wb[i]); snd->request = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataOutPipe->interfaceId), 0, acm->writeSize); //分配待发送的IO Request对象 snd->instance = acm; @@ -789,7 +792,7 @@ HDF_INIT(g_usbSerialDriverEntry); ### Host RAW API驱动开发 -``` +```cpp root { module = "usb_pnp_device"; usb_pnp_config { @@ -836,7 +839,9 @@ root { } } } +``` +```cpp #include "usb_serial_rawapi.h" #include #include "osal_mem.h" @@ -858,11 +863,11 @@ struct OsalMutex g_stopIoLock; static bool g_rawAcmReleaseFlag = false; ...... -static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config) +static int32_t UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config) { UsbRawDevice *dev = NULL; - int activeConfig; - int ret; + int32_t activeConfig; + int32_t ret; if (devHandle == NULL) { HDF_LOGE("%s:%d devHandle is NULL", @@ -893,9 +898,9 @@ static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDe return HDF_SUCCESS; } ... -static int UsbAllocWriteRequests(struct AcmDevice *acm) +static int32_t UsbAllocWriteRequests(struct AcmDevice *acm) { - int i; + int32_t i; for (i = 0; i < ACM_NW; i++) { struct AcmWb *snd = &acm->wb[i]; @@ -965,13 +970,13 @@ error: return HDF_FAILURE; } ... -static int UsbAllocReadRequests(struct AcmDevice *acm) +static int32_t UsbAllocReadRequests(struct AcmDevice *acm) { struct UsbRawFillRequestData reqData; - int size = acm->dataInEp->maxPacketSize; - int ret; + int32_t size = acm->dataInEp->maxPacketSize; + int32_t ret; - for (int i = 0; i < ACM_NR; i++) { + for (int32_t i = 0; i < ACM_NR; i++) { acm->readReq[i] = UsbRawAllocRequest(acm->devHandle, 0, size); if (!acm->readReq[i]) { HDF_LOGE("readReq request failed"); @@ -996,11 +1001,11 @@ static int UsbAllocReadRequests(struct AcmDevice *acm) return HDF_SUCCESS; } ... -static int UsbAllocNotifyRequest(struct AcmDevice *acm) +static int32_t UsbAllocNotifyRequest(struct AcmDevice *acm) { struct UsbRawFillRequestData fillRequestData; - int size = acm->notifyEp->maxPacketSize; - int ret; + int32_t size = acm->notifyEp->maxPacketSize; + int32_t ret; acm->notifyReq = UsbRawAllocRequest(acm->devHandle, 0, size); if (!acm->notifyReq) { @@ -1226,9 +1231,8 @@ HDF_INIT(g_usbSerialRawDriverEntry); USB ACM设备核心代码路径为drivers\peripheral\usb\gadget\function\acm\cdcacm.c。其使用示例如下所示，首先根据描述符创建设备，然后获取接口，打开接口，获取Pipe信息，接收Event事件，接着进行USB通信（读写等），设备卸载时候，关闭接口，停止Event接收，删除设备。 - -``` 1、创建设备 +```cpp static int32_t AcmCreateFuncDevice(struct UsbAcmDevice *acm, struct DeviceResourceIface *iface) { @@ -1251,7 +1255,9 @@ if (useHcs == 0) { } ... } +``` 2、获取接口，打开接口，获取Pipe信息 +```cpp static int32_t AcmParseEachPipe(struct UsbAcmDevice *acm, struct UsbAcmInterface *iface) { ... @@ -1277,8 +1283,11 @@ static int32_t AcmParseEachIface(struct UsbAcmDevice *acm, struct UsbFnDevice *f } return HDF_SUCCESS; } +``` + 3、接收Event事件 -static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int num) +```cpp +static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int32_t num) { ... req = UsbFnCtrlRequestAlloc(acm->ctrlIface.handle, @@ -1292,7 +1301,9 @@ static int32_t AcmDriverInit(struct HdfDeviceObject *device) ret = UsbFnInterfaceStartRecvEvent(acm->ctrlIface.fn, 0xff, UsbAcmEventCallback, acm); ... } +``` 4、进行USB通信（读写等） +```cpp static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type, uint16_t value, void *data, uint32_t length) { @@ -1301,7 +1312,9 @@ static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type, ret = UsbFnRequestSubmitAsync(req); ... } +``` 5、关闭接口，停止Event接收，删除设备 +```cpp static int32_t AcmReleaseFuncDevice(struct UsbAcmDevice *acm) { int32_t ret; -- GitLab