USBX 设备服务的说明

ux_device_stack_alternate_setting_get

获取接口值的当前备用设置

原型

UINT ux_device_stack_alternate_setting_get(ULONG interface_value);

说明

USB 主机使用此函数获取特定接口值的当前备用设置。 收到 GET_INTERFACE 请求时,控制器驱动程序将调用此函数。

输入参数

  • Interface_value:要查询其当前备用设置的接口值

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_ERROR:(0xFF) 错误的接口值。

示例

ULONG interface_value;
UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_alternate_setting_get(interface_value);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_alternate_setting_set

设置接口值的当前备用设置

原型

UINT ux_device_stack_alternate_setting_set(
    ULONG interface_value, 
    ULONG alternate_setting_value);

说明

USB 主机使用此函数设置特定接口值的当前备用设置。 收到 SET_INTERFACE 请求时,控制器驱动程序将调用此函数。 完成 SET_INTERFACE 后,会将备用设置的值应用于类。

设备堆栈将向拥有此接口的类发出 UX_SLAVE_CLASS_COMMAND_CHANGE,以反映备用设置的更改。

参数

  • Interface_value:要设置其当前备用设置的接口值。
  • alternate_setting_value:新的备用设置值。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_INTERFACE_HANDLE_UNKNOWN:(0x52) 未附加接口。
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 未配置设备。
  • UX_ERROR:(0xFF) 错误的接口值。

示例

ULONG interface_value;

ULONG alternate_setting_value;

/* The following example illustrates this service. */
status = ux_device_stack_alternate_setting_set(interface_value, alternate_setting_value);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_class_register

注册新的 USB 设备类

原型

UINT ux_device_stack_class_register(
    UCHAR *class_name,
    UINT (*class_entry_function)(struct UX_SLAVE_CLASS_COMMAND_STRUCT *),
    ULONG configuration_number, 
    ULONG interface_number,  
    VOID *parameter);

说明

应用程序使用此函数注册新的 USB 设备类。 此注册将启动类容器,而不是启动类的实例。 类应具有活动线程,并且应附加到特定的接口。

某些类需要一个参数或参数列表。 例如,设备存储类需要它正在尝试仿真的存储设备的几何结构。 因此,参数字段依赖于类要求,可以是某个值,或者是指向填充了类值的结构的指针。

注意

class_name 的 C 字符串必须以 NULL 结尾,其长度(不包括 NULL 终止符本身)不能大于 UX_MAX_CLASS_NAME_LENGTH。

参数

  • class_name:类名
  • class_entry_function:类的入口函数。
  • configuration_number:此类附加到的配置编号。
  • interface_number:此类附加到的接口编号。
  • parameter:指向类特定的参数列表的指针。

返回值

  • UX_SUCCESS:(0x00) 类已注册
  • UX_MEMORY_INSUFFICIENT:(0x12) 类表中未保留条目。
  • UX_THREAD_ERROR:(0x16) 无法创建类线程。

示例

UINT status;

/* The following example illustrates this service. */

/* Initialize the device storage class. The class is connected with interface 1 */
status = ux_device_stack_class_register(_ux_system_slave_class_storage_name ux_device_class_storage_entry,
    1, 1, (VOID *)&parameter);

ux_device_stack_class_unregister

注销 USB 设备类

原型

UINT ux_device_stack_class_unregister(
    UCHAR *class_name,
    UINT (*class_entry_function)(struct UX_SLAVE_CLASS_COMMAND_STRUCT*));

说明

应用程序使用此函数注销 USB 设备类。

注意

class_name 的 C 字符串必须以 NULL 结尾,其长度(不包括 NULL 终止符本身)不能大于 UX_MAX_CLASS_NAME_LENGTH。

参数

  • class_name:类名
  • class_entry_function:类的入口函数。

返回值

  • UX_SUCCESS:(0x00) 类已注销。
  • UX_NO_CLASS_MATCH:(0x57) 类未注册。

示例

/* The following example illustrates this service. */

/* Unitialize the device storage class. */
status = ux_device_stack_class_unregister(_ux_system_slave_class_storage_name, ux_device_class_storage_entry);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_configuration_get

获取当前配置

原型

UINT ux_device_stack_configuration_get(VOID);

说明

主机使用此函数获取设备中运行的当前配置。

输入参数

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_configuration_get();

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_configuration_set

设置当前配置

原型

UINT ux_device_stack_configuration_set(ULONG configuration_value);

说明

主机使用此函数设置设备中运行的当前配置。 收到此命令后,USB 设备堆栈将激活已连接到此配置的每个接口的备用设置 0。

输入参数

  • configuration_value:主机选择的配置值。

返回值

  • UX_SUCCESS:(0x00) 已成功设置配置。

示例

ULONG configuration_value;
UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_configuration_set(configuration_value);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_descriptor_send

将描述符发送到主机

原型

UINT ux_device_stack_descriptor_send(
    ULONG descriptor_type, 
    ULONG request_index, 
    ULONG host_length);

说明

设备端使用此函数向主机返回描述符。 此描述符可以是设备描述符、配置描述符或字符串描述符。

参数

  • descriptor_type:描述符的类型。 必须是以下值之一。
    • UX_DEVICE_DESCRIPTOR_ITEM
    • UX_CONFIGURATION_DESCRIPTOR_ITEM
    • UX_STRING_DESCRIPTOR_ITEM
    • UX_DEVICE_QUALIFIER_DESCRIPTOR_ITEM
    • UX_OTHER_SPEED_DESCRIPTOR_ITEM
  • request_index:描述符的索引。
  • host_length:主机所需的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_ERROR:(0xFF) 传输未完成。

示例

ULONG descriptor_type;
ULONG request_index;
ULONG host_length;
UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_descriptor_send(descriptor_type, request_index, host_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_disconnect

断开连接设备堆栈

原型

UINT ux_device_stack_disconnect(VOID);

说明

当设备断开连接时,VBUS 管理器将调用此函数。 设备堆栈将告知所有已注册到此设备的类,然后释放所有设备资源。

输入参数

返回值

  • UX_SUCCESS:(0x00) 设备已断开连接。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_disconnect();

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_endpoint_stall

请求终结点停滞状态

原型

UINT ux_device_stack_endpoint_stall(UX_SLAVE_ENDPOINT*endpoint);

说明

当终结点应向主机返回停滞状态时,USB 设备类将调用此函数。

输入参数

  • endpoint:在其上请求停滞状态的终结点。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_ERROR:(0xFF) 设备处于无效状态。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_endpoint_stall(endpoint);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_host_wakeup

唤醒主机

原型

UINT ux_device_stack_host_wakeup(VOID);

说明

当设备想要唤醒主机时,将调用此函数。 此命令仅在设备处于挂起模式时才有效。 由设备应用程序决定何时要唤醒 USB 主机。 例如,当 USB 调制解调器在电话线路上检测到 RING 信号时,它便可以唤醒主机。

输入参数

返回值

  • UX_SUCCESS:(0x00) 调用成功。
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 调用失败(设备可能不处于挂起模式)。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_host_wakeup();

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_initialize

初始化 USB 设备堆栈

原型

UINT ux_device_stack_initialize(
    UCHAR *device_framework_high_speed,
    ULONG device_framework_length_high_speed,
    UCHAR *device_framework_full_speed,
    ULONG device_framework_length_full_speed,
    UCHAR *string_framework,
    ULONG string_framework_length,
    UCHAR *language_id_framework,
    ULONG language_id_framework_length),
    UINT (*ux_system_slave_change_function)(ULONG)));

说明

应用程序调用此函数来初始化 USB 设备堆栈。 它不会初始化任何类或任何控制器。 应使用单独的函数调用来执行此操作。 此调用的主要目的是为堆栈提供 USB 函数的设备框架。 它支持高速和全速,对于每种速度,它可能提供完全不同的设备框架。 支持字符串框架和多种语言。

参数

  • device_framework_high_speed:指向高速框架的指针。
  • device_framework_length_high_speed:高速框架的长度。
  • device_framework_full_speed:指向全速框架的指针。
  • device_framework_length_full_speed:全速框架的长度。
  • string_framework:指向字符串框架的指针。
  • string_framework_length:字符串框架的长度。
  • language_id_framework:指向字符串语言框架的指针。
  • language_id_framework_length:字符串语言框架的长度。
  • ux_system_slave_change_function:设备状态更改时要调用的函数。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法初始化堆栈。
  • UX_DESCRIPTOR_CORRUPTED:(0x42) 描述符无效。

示例

/* Example of a device framework */

#define DEVICE_FRAMEWORK_LENGTH_FULL_SPEED 50

UCHAR device_framework_full_speed[] = {
    /* Device descriptor */
    0x12, 0x01, 0x10, 0x01, 0x00, 0x00, 0x00, 0x08,
    0xec, 0x08, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x01,

    /* Configuration descriptor */
    0x09, 0x02, 0x20, 0x00, 0x01, 0x01, 0x00, 0xc0,
    0x32,

    /* Interface descriptor */
    0x09, 0x04, 0x00, 0x00, 0x02, 0x08, 0x06, 0x50,
    0x00,

    /* Endpoint descriptor (Bulk Out) */
    0x07, 0x05, 0x01, 0x02, 0x40, 0x00, 0x00,

    /* Endpoint descriptor (Bulk In) */
    0x07, 0x05, 0x82, 0x02, 0x40, 0x00, 0x00
};

#define DEVICE_FRAMEWORK_LENGTH_HIGH_SPEED 60

UCHAR device_framework_high_speed[] = {
    /* Device descriptor */
    0x12, 0x01, 0x00, 0x02, 0x00, 0x00, 0x00, 0x40,
    0x0a, 0x07, 0x25, 0x40, 0x01, 0x00, 0x01, 0x02,
    0x03, 0x01,

    /* Device qualifier descriptor */
    0x0a, 0x06, 0x00, 0x02, 0x00, 0x00, 0x00, 0x40,
    0x01, 0x00,

    /* Configuration descriptor */
    0x09, 0x02, 0x20, 0x00, 0x01, 0x01, 0x00, 0xc0,
    0x32,

    /* Interface descriptor */
    0x09, 0x04, 0x00, 0x00, 0x02, 0x08, 0x06, 0x50,
    0x00,

    /* Endpoint descriptor (Bulk Out) */
    0x07, 0x05, 0x01, 0x02, 0x00, 0x02, 0x00,

    /* Endpoint descriptor (Bulk In) */
    0x07, 0x05, 0x82, 0x02, 0x00, 0x02, 0x00
};

/* String Device Framework:
    Byte 0 and 1: Word containing the language ID: 0x0904 for US
    Byte 2 : Byte containing the index of the descriptor
    Byte 3 : Byte containing the length of the descriptor string */

#define STRING_FRAMEWORK_LENGTH 38 UCHAR string_framework[] = {
    /* Manufacturer string descriptor: Index 1 */
    0x09, 0x04, 0x01, 0x0c,
    0x45, 0x78, 0x70, 0x72,0x65, 0x73, 0x20, 0x4c,
    0x6f, 0x67, 0x69, 0x63,

    /* Product string descriptor: Index 2 */
    0x09, 0x04, 0x02, 0x0c,
    0x4D, 0x4C, 0x36, 0x39, 0x36, 0x35, 0x30, 0x30,
    0x20, 0x53, 0x44, 0x4B,

    /* Serial Number string descriptor: Index 3 */
    0x09, 0x04, 0x03, 0x04,
    0x30, 0x30, 0x30, 0x31
};

/* Multiple languages are supported on the device, to add a language besides English, 
  the Unicode language code must be appended to the language_id_framework array 
  and the length adjusted accordingly. */

#define LANGUAGE_ID_FRAMEWORK_LENGTH 2

UCHAR language_id_framework[] = {
    /* English. */
    0x09, 0x04
};

当控制器更改了其状态时,应用程序可以请求回调。 控制器的两种主要状态为:

  • UX_DEVICE_SUSPENDED
  • UX_DEVICE_RESUMED

如果应用程序不需要暂停/继续信号,则会提供 UX_NULL 函数。

UINT status;

/* The code below is required for installing the device portion of USBX. 
    There is no call back for device status change in this example. */
status = ux_device_stack_initialize(&device_framework_high_speed,
    DEVICE_FRAMEWORK_LENGTH_HIGH_SPEED, &device_framework_full_speed,
    DEVICE_FRAMEWORK_LENGTH_FULL_SPEED, &string_framework,
    STRING_FRAMEWORK_LENGTH, &language_id_framework,
    LANGUAGE_ID_FRAMEWORK_LENGTH, UX_NULL);

/* If status equals UX_SUCCESS, initialization was successful. */

ux_device_stack_interface_delete

删除堆栈接口

原型

UINT ux_device_stack_interface_delete(UX_SLAVE_INTERFACE*interface);

说明

应删除接口时将调用此函数。 在提取设备时、总线重置后,或者有新的备用设置时,将删除接口。

输入参数

  • interface:指向要删除的接口的指针。

返回值

  • UX_SUCCESS (0x00) 此操作成功。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_interface_delete(interface);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_interface_get

获取当前接口值

原型

UINT ux_device_stack_interface_get(UINT interface_value);

说明

当主机查询当前接口时,将调用此函数。 设备将返回当前接口值。

注意

不推荐使用此函数。 此函数适用于旧式软件,新式软件应改用 ux_device_stack_alternate_setting_get 函数

输入参数

  • interface_value:要返回的接口值。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_ERROR:(0xFF) 不存在接口。

示例

ULONG interface_value;

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_interface_get(interface_value);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_interface_set

更改接口的备用设置

原型

UINT ux_device_stack_interface_set(
    UCHAR *device_framework,
    ULONG device_framework_length, 
    ULONG alternate_setting_value);

说明

当主机请求更改接口的备用设置时,将调用此函数。

参数

  • device_framework:此接口的设备框架的地址。
  • device_framework_length:设备框架的长度。
  • alternate_setting_value:此接口要使用的备用设置值。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_ERROR:(0xFF) 不存在接口。

示例

UCHAR * device_framework
ULONG device_framework_length;
ULONG alternate_setting_value;
UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_interface_set(device_framework,
    device_framework_length, alternate_setting_value);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_interface_start

开始搜索类以拥有接口实例

原型

UINT ux_device_stack_interface_start(UX_SLAVE_INTERFACE*interface);

说明

当主机已选择某个接口,并且设备堆栈需要搜索设备类以拥有此接口实例时,将调用此函数。

输入参数

  • interface:指向已创建的接口的指针。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_NO_CLASS_MATCH:(0x57) 此接口不存在任何类。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_device_stack_interface_start(interface);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_transfer_request

请求将数据传输到主机

原型

UINT ux_device_stack_transfer_request(
    UX_SLAVE_TRANSFER *transfer_request,
    ULONG slave_length, 
    ULONG host_length);

说明

当类或堆栈要将数据传输到主机时,将调用此函数。 主机始终轮询设备,但设备可以提前准备数据。

参数

  • transfer_request:指向传输请求的指针。
  • slave_length:设备要返回的长度。
  • host_length:主机已请求的长度。

返回值

  • UX_SUCCESS:(0x00) 此操作成功。
  • UX_TRANSFER_NOT_READY:(0x25) 设备处于无效状态;状态必须是 ATTACHED、CONFIGURED 或 ADDRESSED 。
  • UX_ERROR:(0xFF) 传输错误。

示例

UINT status;

/* The following example illustrates how to transfer more data than an application requests. */
while(total_length) {
    /* How much can we send in this transfer? */
    if (total_length > UX_SLAVE_CLASS_STORAGE_BUFFER_SIZE)
        transfer_length = UX_SLAVE_CLASS_STORAGE_BUFFER_SIZE;
    else
        transfer_length = total_length;

   /* Copy the Storage Buffer into the transfer request memory. */
   ux_utility_memory_copy(transfer_request ->  ux_slave_transfer_request_data_pointer,
       media_memory, transfer_length);

   /* Send the data payload back to the caller. */
   status = ux_device_transfer_request(transfer_request,
       transfer_length, transfer_length);

   /* If status equals UX_SUCCESS, the operation was successful. */

   /* Update the buffer address.  */
    media_memory += transfer_length;

   /* Update the length to remain. */
    total_length -= transfer_length;
}

ux_device_stack_transfer_abort

取消转移请求

原型

UINT ux_device_stack_transfer_abort(
    UX_SLAVE_TRANSFER *transfer_request, 
    ULONG completion_code);

说明

当应用程序需要取消传输请求,或者堆栈需要中止与某个终结点关联的传输请求时,将调用此函数。

参数

  • transfer_request:指向传输请求的指针。
  • completion_code:要向正在等待此传输请求完成的类返回的错误代码。

返回值

  • UX_SUCCESS (0x00) 此操作成功。

示例

UINT status;

/* The following example illustrates how to abort a transfer when a
    bus reset has been detected on the bus. */
status = ux_device_stack_transfer_abort(transfer_request, UX_TRANSFER_BUS_RESET);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_device_stack_uninitialize

取消初始化堆栈

原型

UINT ux_device_stack_uninitialize();

说明

当应用程序需要取消初始化 USBX 设备堆栈时,将调用此函数 – 所有设备堆栈资源均会释放。 应在已通过 ux_device_stack_class_unregister 注销所有类之后调用此函数。

参数

返回值

UX_SUCCESS:(0x00) 此操作成功。