USB Composite

group USB_Composite

USB composite device consists of multiple configurations, and each configuration consists of multiple interfaces. This module provides fundamental components for implementing USB composite devices, which include multiple USB classes such as USB audio and HID.

How to Initialize the USB Device and Configuration

Example

T_USB_DEVICE_DESC demo_usb_dev_desc =
{
    ...init...
};

T_USB_CONFIG_DESC demo_usb_cfg_desc =
{
    ...init...
};

usb_composite_dev_init(&demo_usb_dev_desc);
usb_composite_dev_cfg_add(&demo_usb_cfg_desc);

//if string index of demo_usb_dev_desc/demo_usb_cfg_desc is not zero
usb_composite_dev_string_add(language, string index, string);

How to Implement USB Interfaces

The core interface information is defined in T_USB_INTERFACE. It is mainly used to initialize T_USB_INTERFACE to implement an interface.

Example

#include "usb_spec20.h"
T_USB_INTERFACE_DESC std_if_desc_hs =
{
    ...init...
};

(Class interface descriptor type) class_if_desc_hs =
{
    ...init...
};

T_USB_ENDPOINT_DESC std_endpoint_desc_hs =
{
    ...init...
};

(Class endpoint descriptor type)  class_endpoint_desc_hs =
{
    ...init...
};

T_USB_INTERFACE_DESC std_if_desc_fs =
{
    ...init...
};

(Class interface descriptor type) class_if_desc_fs =
{
    ...init...
};

T_USB_ENDPOINT_DESC std_endpoint_desc_fs =
{
    ...init...
};

(Class endpoint descriptor type)  class_endpoint_desc_fs =
{
    ...init...
};

T_USB_DESC_HDR* demo_if_descs_hs[] =
{
    (T_USB_DESC_HDR*)&std_if_desc_hs,
    (T_USB_DESC_HDR*)&class_if_desc_hs,
    (T_USB_DESC_HDR*)&std_endpoint_desc_hs,
    (T_USB_DESC_HDR*)&class_endpoint_desc_hs,
    NULL,
};

T_USB_DESC_HDR* demo_if_descs_fs[] =
{
    (T_USB_DESC_HDR*)&std_if_desc_fs,
    (T_USB_DESC_HDR*)&class_if_desc_fs,
    (T_USB_DESC_HDR*)&std_endpoint_desc_fs,
    (T_USB_DESC_HDR*)&class_endpoint_desc_fs,
    NULL,
};

int demo_if_ctrl_request_proc(T_USB_INTERFACE *interface, T_USB_DEVICE_REQUEST *ctrl_request, T_HAL_USB_REQUEST_BLOCK *ctrl_urb)
{
    //Process class-specific control requests
}

int demo_if_alt_get(T_USB_INTERFACE *interface, T_HAL_USB_REQUEST_BLOCK *ctrl_urb)
{
    //Process GET_ALT request
}

int demo_if_alt_set(T_USB_INTERFACE *interface, T_HAL_USB_REQUEST_BLOCK *ctrl_urb, uint8_t alt)
{
    //Process SET_ALT request
}

int demo_if_create(T_USB_INTERFACE *interface)
{
    //Initialize interface-related resources, such as endpoints
}

int demo_if_release(T_USB_INTERFACE *interface)
{
    //Deinit interface-related resources initialized in \ref demo_if_create
}

int demo_if_suspend(T_USB_INTERFACE *interface)
{
    //Process USB suspend
}

int demo_if_resume(T_USB_INTERFACE *interface)
{
    //Process USB resume
}

T_USB_INTERFACE usb_if =
{
    .if_num = 0,
    .descs_fs = demo_if_descs_fs,
    .descs_hs = demo_if_descs_hs,
    .ctrl_request_proc = demo_if_ctrl_request_proc,
    .alt_get = demo_if_alt_get,
    .alt_set = demo_if_alt_set,
    .suspend = demo_if_suspend,
    .resume = demo_if_resume,
    .create = demo_if_create,
    .release = demo_if_release,
};
usb_composite_dev_interface_add(&usb_if, cfg val);

Definitions

Typedefs

typedef struct _usb_ep T_USB_EP

The USB endpoint structure, which is an item of the eps list in T_USB_INTERFACE.

Param p_next:

Point to next endpoint of eps list in T_USB_INTERFACE.

Param addr:

The endpoint address.

Param desc:

The endpoint descriptor.

Param ep_handle:

The endpoint handle.

typedef struct _usb_interface T_USB_INTERFACE

Core structure to realize interface.

Param if_num:

The interface number. NOTE: the value may be changed in usb_composite_dev_interface_add.

Param descs_fs:

The interface descriptors of full speed.

Param descs_hs:

The interface descriptors of high speed.

Param eps:

The endpoint list belongs to the interface.

Param speed_enum_done:

The callback to process USB enumeration done.

Param ctrl_request_proc:

The callback to process class-specific requests.

Param alt_get:

The callback to process GET_ALT request.

Param alt_set:

The callback to process SET_ALT request.

Param create:

The callback to initialize the interface, and it will be called in usb_composite_dev_interface_add. Also, if_num in the input parameter of the interface may be changed, the interface MUST update bInterfaceNumber in the interface descriptor to the actual interface number.

Param release:

The callback to release interface-related resources.

Param priv:

Private data.

Functions

uint8_t usb_composite_dev_ep0_mps_get(void)

Get the maximum packet size of Endpoint 0.

返回:

The maximum packet size of Endpoint 0.

int usb_composite_dev_string_add(uint16_t language, uint8_t id, const char *s)

Add strings to USB composite device.

Example

Please refer to How to Initialize the USB Device and Configuration.

参数:

• language – The language of the target string.

• id – The ID of target string, which is the value of string index in the corresponding descriptor.

• s – The string.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_string_remove(uint16_t language, uint8_t id, const char *s)

Remove strings from USB composite device.

参数:

• language – The language of the target string.

• id – The ID of target string, which is the value of string index in the corresponding descriptor.

• s – The string.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_cfg_add(T_USB_CONFIG_DESC *cfg_desc)

Add a configuration to USB composite device.

Example

Please refer to How to Initialize the USB Device and Configuration.

参数:

cfg_desc – The configuration descriptor.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_cfg_remove(T_USB_CONFIG_DESC *cfg_desc)

Remove a configuration from USB composite device.

Example

Please refer to How to Initialize the USB Device and Configuration.

参数:

cfg_desc – The configuration descriptor.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_interface_add(T_USB_INTERFACE *interface, uint8_t cfg_val)

Add an interface to the target configuration.

Example

Please refer to How to Implement USB Interfaces

参数:

• interface – Refer to How to Implement USB Interfaces.

• cfg_val – The configuration value that the interface belongs to.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_interface_remove(T_USB_INTERFACE *interface, uint8_t cfg_val)

Remove an interface from the target configuration.

参数:

• interface – Refer to How to Implement USB Interfaces.

• cfg_val – The configuration value that the interface belongs to.

返回:

Refer to ‘rtl_errno.h’.

T_HAL_USB_SPEED usb_composite_dev_enum_speed_get(void)

Get enumeration speed, which is the actual operating speed after speed enumeration.

返回:

Refer to T_HAL_USB_SPEED.

int usb_composite_dev_remote_wakeup(bool force)

Remote wakeup.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_init(T_USB_DEVICE_DESC *dev_desc)

Initialize USB composite device.

Example

Please refer to How to Initialize the USB Device and Configuration.

参数:

dev_desc – The device descriptor.

返回:

Refer to ‘rtl_errno.h’.

int usb_composite_dev_deinit(void)

Deinit USB composite device.

struct _usb_ep

The USB endpoint structure, which is an item of the eps list in T_USB_INTERFACE.

Param p_next:

Point to next endpoint of eps list in T_USB_INTERFACE.

Param addr:

The endpoint address.

Param desc:

The endpoint descriptor.

Param ep_handle:

The endpoint handle.

Public Members

struct _usb_ep *p_next

uint8_t addr

T_USB_ENDPOINT_DESC *desc

void *ep_handle

void *priv

struct _usb_interface

Core structure to realize interface.

Param if_num:

The interface number. NOTE: the value may be changed in usb_composite_dev_interface_add.

Param descs_fs:

The interface descriptors of full speed.

Param descs_hs:

The interface descriptors of high speed.

Param eps:

The endpoint list belongs to the interface.

Param speed_enum_done:

The callback to process USB enumeration done.

Param ctrl_request_proc:

The callback to process class-specific requests.

Param alt_get:

The callback to process GET_ALT request.

Param alt_set:

The callback to process SET_ALT request.

Param create:

The callback to initialize the interface, and it will be called in usb_composite_dev_interface_add. Also, if_num in the input parameter of the interface may be changed, the interface MUST update bInterfaceNumber in the interface descriptor to the actual interface number.

Param release:

The callback to release interface-related resources.

Param priv:

Private data.

Public Members

uint8_t if_num

struct usb_descriptor_header **descs_fs

struct usb_descriptor_header **descs_hs

T_OS_QUEUE eps

int (*ctrl_request_proc)(struct _usb_interface *interface, T_USB_DEVICE_REQUEST *ctrl_request, T_HAL_USB_REQUEST_BLOCK *ctrl_urb)

int (*alt_get)(struct _usb_interface *interface, T_HAL_USB_REQUEST_BLOCK *ctrl_urb)

int (*alt_set)(struct _usb_interface *interface, T_HAL_USB_REQUEST_BLOCK *ctrl_urb, uint8_t alt)

int (*suspend)(struct _usb_interface *interface)

int (*resume)(struct _usb_interface *interface)

int (*create)(struct _usb_interface *interface)

int (*release)(struct _usb_interface *interface)

void *priv