USB host enumeration functions module

Data Structures
struct	S_interface
	Interface. More...
struct	S_usb_setup_data
	USB Setup Data. More...

Macros
#define	CONTROL_CRC16   0x10
#define	CONTROL_DATA_PID   0x02
#define	CONTROL_DATA_TOGGLE   0x01
#define	CONTROL_GOOD   0x00
#define	CONTROL_NO_DEVICE   0x40
#define	CONTROL_PID   0x04
#define	CONTROL_STALL   0x20
#define	CONTROL_TIMEOUT   0x08
#define	Get_altset_nb(s_interface)   (interface_supported[(s_interface)].altset_nb)
	Number of alternate settings associated with a supported interface. More...
#define	Get_class(s_interface)   (interface_supported[(s_interface)].uclass)
	USB class associated with the supported interface. More...
#define	Get_ep_nbr(s_interface, n_ep)   (Host_get_pipe_endpoint_number(Get_ep_pipe(s_interface, n_ep)))
	Endpoint number associated with the supported interface. More...
#define	Get_ep_pipe(s_interface, n_ep)   (interface_supported[(s_interface)].ep_pipe[(n_ep)])
	Endpoint pipe associated with the supported interface. More...
#define	Get_ep_type(s_interface, n_ep)   (Host_get_pipe_type(Get_ep_pipe(s_interface, n_ep)))
	Endpoint type associated with the supported interface. More...
#define	Get_interface_number(s_interface)   (interface_supported[(s_interface)].interface_nb)
	Number of interfaces associated with a supported interface. More...
#define	Get_maxpower()   (maxpower)
	Maximal power consumption of the connected device (unit is 2 mA) More...
#define	Get_nb_ep(s_interface)   (interface_supported[(s_interface)].nb_ep)
	Number of endpoints associated with a supported interface. More...
#define	Get_nb_supported_interface()   (nb_interface_supported)
	Number of supported interfaces in the connected device. More...
#define	Get_PID()   (device_PID)
	PID of the connected device. More...
#define	Get_pipe_token(ep_addr)   ((Get_desc_ep_dir(ep_addr)) ? TOKEN_IN : TOKEN_OUT)
	Extract token information from endpoint address. More...
#define	Get_protocol(s_interface)   (interface_supported[(s_interface)].protocol)
	USB protocol associated with the supported interface. More...
#define	Get_subclass(s_interface)   (interface_supported[(s_interface)].subclass)
	USB subclass associated with the supported interface. More...
#define	Get_VID()   (device_VID)
	VID of the connected device. More...
#define	host_clear_endpoint_feature(ep)
	Send a "clear endpoint feature" request. More...
#define	host_get_configuration()
	Send a "get configuration" request. More...
#define	host_get_configuration_descriptor(cfg_ix)
	Send a "get device configuration descriptor" request The configuration descriptor received is stored in the data_stage array. More...
#define	host_get_device_descriptor()
	Send a "get device descriptor" request The descriptor received is stored in the data_stage array. More...
#define	host_get_device_descriptor_incomplete()
	Send an incomplete "get device descriptor" request The descriptor received is stored in the data_stage array. More...
#define	host_ms_get_max_lun()
	Send the mass-storage specific request "get max LUN". More...
#define	host_set_address(addr)
	Send a "set address" request. More...
#define	host_set_configuration(cfg_nb)
	Send a "set configuration" request. More...
#define	host_set_feature_remote_wakeup()
	Send a "set feature" "device remote wake-up". More...
#define	host_set_interface(interface_nb, alt_setting)
	Send a "set interface" request to specify an alternate setting for an interface. More...
#define	Is_device_self_powered()   (Tst_bits(bmattributes, SELF_POWERED_MASK))
	true if the connected device is self-powered More...
#define	Is_device_supports_remote_wakeup()   (Tst_bits(bmattributes, REMOTE_WAKEUP_MASK))
	true if the connected device supports remote wake-up More...
#define	Is_ep_in(s_interface, n_ep)   (Host_get_pipe_token(Get_ep_pipe(s_interface, n_ep)) == TOKEN_IN)
	true if the endpoint direction associated with the supported interface is IN More...
#define	OFFSET_DESCRIPTOR_LENGTH   0
	Offsets common to all descriptor types. More...
#define	OFFSET_FIELD_ALT   3
#define	OFFSET_FIELD_BMATTRIBUTES   7
#define	OFFSET_FIELD_CLASS   5
#define	OFFSET_FIELD_CONFIGURATION_NB   5
#define	OFFSET_FIELD_DESCRIPTOR_TYPE   1
#define	OFFSET_FIELD_EP_ADDR   2
	Offsets in endpoint descriptors. More...
#define	OFFSET_FIELD_EP_INTERVAL   6
#define	OFFSET_FIELD_EP_SIZE   4
#define	OFFSET_FIELD_EP_TYPE   3
#define	OFFSET_FIELD_INTERFACE_NB   2
	Offsets in interface descriptors. More...
#define	OFFSET_FIELD_MAXPACKETSIZE   7
	Offsets in device descriptors. More...
#define	OFFSET_FIELD_MAXPOWER   8
#define	OFFSET_FIELD_NB_CONFIGURATION   17
#define	OFFSET_FIELD_NB_INTERFACE   4
#define	OFFSET_FIELD_NB_OF_EP   4
#define	OFFSET_FIELD_PID   10
#define	OFFSET_FIELD_PROTOCOL   7
#define	OFFSET_FIELD_SUB_CLASS   6
#define	OFFSET_FIELD_TOTAL_LENGTH   2
	Offsets in configuration descriptors. More...
#define	OFFSET_FIELD_VID   8
#define	REMOTE_WAKEUP_BIT   5
#define	REMOTE_WAKEUP_MASK   (1 << REMOTE_WAKEUP_BIT)
#define	SELF_POWERED_BIT   6
#define	SELF_POWERED_MASK   (1 << SELF_POWERED_BIT)

Functions
bool	host_check_class (void)
	This function checks if the device class is supported. More...
bool	host_check_VID_PID (void)
	This function checks if the VID and the PID are supported (if the VID & PID belong to the VID_PID table). More...
Status_t	host_transfer_control (void *data_pointer)
	This function is the generic control pipe management function. More...

Variables
volatile uint8_t	bmattributes
	bmAttributes byte of connected device More...
volatile uint16_t	device_PID
	PID of connected device. More...
volatile uint16_t	device_VID
	VID of connected device. More...
volatile S_interface	interface_supported [MAX_INTERFACE_SUPPORTED]
	Supported interfaces. More...
volatile uint8_t	maxpower
	maxpower byte of connected device (unit is 2 mA) More...
volatile uint8_t	nb_interface_supported
	Number of interfaces the host is able to support in the connected device. More...

#define CONTROL_CRC16   0x10

#define CONTROL_DATA_PID   0x02

#define CONTROL_DATA_TOGGLE   0x01

#define CONTROL_GOOD   0x00

Referenced by host_transfer_control(), and usb_host_task().

#define CONTROL_NO_DEVICE   0x40

#define CONTROL_PID   0x04

#define CONTROL_STALL   0x20

Referenced by host_transfer_control().

#define CONTROL_TIMEOUT   0x08

Referenced by host_transfer_control().

#define Get_altset_nb

(

s_interface

)

(interface_supported[(s_interface)].altset_nb)

Number of alternate settings associated with a supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: Number of alternate settings

#define Get_class

(

s_interface

)

(interface_supported[(s_interface)].uclass)

USB class associated with the supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: Class

Referenced by host_mass_storage_task().

#define Get_ep_nbr	(		s_interface,
			n_ep
	)		(Host_get_pipe_endpoint_number(Get_ep_pipe(s_interface, n_ep)))

Endpoint number associated with the supported interface.

Parameters

s_interface	uint8_t: The supported interface number
n_ep	uint8_t: The endpoint number in this interface

Returns

uint8_t: Endpoint number

#define Get_ep_pipe	(		s_interface,
			n_ep
	)		(interface_supported[(s_interface)].ep_pipe[(n_ep)])

Endpoint pipe associated with the supported interface.

Parameters

s_interface	uint8_t: The supported interface number
n_ep	uint8_t: The endpoint number in this interface

Returns

uint8_t: Endpoint pipe

Referenced by host_mass_storage_task().

#define Get_ep_type	(		s_interface,
			n_ep
	)		(Host_get_pipe_type(Get_ep_pipe(s_interface, n_ep)))

Endpoint type associated with the supported interface.

Parameters

s_interface	uint8_t: The supported interface number
n_ep	uint8_t: The endpoint number in this interface

Returns

uint8_t: Endpoint type

#define Get_interface_number

(

s_interface

)

(interface_supported[(s_interface)].interface_nb)

Number of interfaces associated with a supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: Number of interfaces

#define Get_maxpower

(

)

(maxpower)

Maximal power consumption of the connected device (unit is 2 mA)

Returns

uint8_t: Maximal power

#define Get_nb_ep

(

s_interface

)

(interface_supported[(s_interface)].nb_ep)

Number of endpoints associated with a supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: Number of endpoints

#define Get_nb_supported_interface

(

)

(nb_interface_supported)

Number of supported interfaces in the connected device.

Returns

uint8_t: Number of supported interfaces

Referenced by host_mass_storage_task().

#define Get_PID

(

)

(device_PID)

PID of the connected device.

Returns

uint16_t: PID

Referenced by ai_usb_ms_get_product_id().

#define Get_pipe_token

(

ep_addr

)

((Get_desc_ep_dir(ep_addr)) ? TOKEN_IN : TOKEN_OUT)

Extract token information from endpoint address.

Parameters

ep_addr

uint8_t: Endpoint address

Returns

TOKEN_IN/TOKEN_OUT: Pipe token

Referenced by host_check_class().

#define Get_protocol

(

s_interface

)

(interface_supported[(s_interface)].protocol)

USB protocol associated with the supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: protocol

#define Get_subclass

(

s_interface

)

(interface_supported[(s_interface)].subclass)

USB subclass associated with the supported interface.

Parameters

s_interface

uint8_t: The supported interface number

Returns

uint8_t: Subclass

#define Get_VID

(

)

(device_VID)

VID of the connected device.

Returns

uint16_t: VID

Referenced by ai_usb_ms_get_vendor_id().

#define host_clear_endpoint_feature

(

ep

)

Value:

(\
  usb_request.bmRequestType   = 0x02,\
  usb_request.bRequest        = CLEAR_FEATURE,\
  usb_request.wValue          = FEATURE_ENDPOINT_HALT << 8,\
  usb_request.wIndex          = (ep),\
  usb_request.wLength         = 0,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "clear endpoint feature" request.

Parameters

ep	uint8_t: Target endpoint

Returns

Status

Referenced by host_ms_stall_management().

#define host_get_configuration

(

)

Value:

(\
  usb_request.bmRequestType   = 0x80,\
  usb_request.bRequest        = GET_CONFIGURATION,\
  usb_request.wValue          = 0,\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 1,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "get configuration" request.

Returns

Status

#define host_get_configuration_descriptor

(

cfg_ix

)

Value:

(\
  usb_request.bmRequestType   = 0x80,\
  usb_request.bRequest        = GET_DESCRIPTOR,\
  usb_request.wValue          = CONFIGURATION_DESCRIPTOR << 8 | (cfg_ix),\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = SIZEOF_DATA_STAGE,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "get device configuration descriptor" request The configuration descriptor received is stored in the data_stage array.

Parameters

cfg_ix

uint8_t: Index of the configuration descriptor to get

Returns

Status

Referenced by usb_host_task().

#define host_get_device_descriptor

(

)

Value:

(\
  usb_request.bmRequestType   = 0x80,\
  usb_request.bRequest        = GET_DESCRIPTOR,\
  usb_request.wValue          = DEVICE_DESCRIPTOR << 8,\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 18,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "get device descriptor" request The descriptor received is stored in the data_stage array.

Returns

Status

Referenced by usb_host_task().

#define host_get_device_descriptor_incomplete

(

)

Value:

(\
  usb_request.bmRequestType   = 0x80,\
  usb_request.bRequest        = GET_DESCRIPTOR,\
  usb_request.wValue          = DEVICE_DESCRIPTOR << 8,\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 64,\
  usb_request.incomplete_read = true,\
  host_transfer_control(data_stage)\
)

Send an incomplete "get device descriptor" request The descriptor received is stored in the data_stage array.

The received descriptors are limited to the length of the control pipe.

Returns

Status

Referenced by usb_host_task().

#define host_ms_get_max_lun

(

)

Value:

(\
  usb_request.bmRequestType   = 0xA1,\
  usb_request.bRequest        = MS_GET_MAX_LUN,\
  usb_request.wValue          = 0,\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 1,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send the mass-storage specific request "get max LUN".

Returns

Status

Referenced by host_get_lun().

#define host_set_address

(

addr

)

Value:

(\
  usb_request.bmRequestType   = 0x00,\
  usb_request.bRequest        = SET_ADDRESS,\
  usb_request.wValue          = (addr),\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 0,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "set address" request.

Parameters

addr	uint8_t: Address assigned to the device

Returns

Status

Referenced by usb_host_task().

#define host_set_configuration

(

cfg_nb

)

Value:

(\
  usb_request.bmRequestType   = 0x00,\
  usb_request.bRequest        = SET_CONFIGURATION,\
  usb_request.wValue          = (cfg_nb),\
  usb_request.wIndex          = 0,\
  usb_request.wLength         = 0,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "set configuration" request.

Parameters

cfg_nb

uint8_t: Configuration to activate

Returns

Status

Referenced by usb_host_task().

#define host_set_feature_remote_wakeup

(

)

Value:

(\
  usb_request.bmRequestType   = 0x00,\
  usb_request.bRequest        = SET_FEATURE,\
  usb_request.wValue          = 1,\
  usb_request.wIndex          = 1,\
  usb_request.wLength         = 0,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "set feature" "device remote wake-up".

Returns

Status

Referenced by usb_host_task().

#define host_set_interface	(		interface_nb,
			alt_setting
	)

Value:

(\
  usb_request.bmRequestType   = 0x01,\
  usb_request.bRequest        = SET_INTERFACE,\
  usb_request.wValue          = (alt_setting),\
  usb_request.wIndex          = (interface_nb),\
  usb_request.wLength         = 0,\
  usb_request.incomplete_read = false,\
  host_transfer_control(data_stage)\
)

Send a "set interface" request to specify an alternate setting for an interface.

Parameters

interface_nb	uint8_t: Interface
alt_setting	uint8_t: Alternate setting

Returns

Status

#define Is_device_self_powered

(

)

(Tst_bits(bmattributes, SELF_POWERED_MASK))

true if the connected device is self-powered

Returns

bool: Self-powered?

#define Is_device_supports_remote_wakeup

(

)

(Tst_bits(bmattributes, REMOTE_WAKEUP_MASK))

true if the connected device supports remote wake-up

Returns

bool: Remote wake-up supported?

Referenced by usb_host_task().

#define Is_ep_in	(		s_interface,
			n_ep
	)		(Host_get_pipe_token(Get_ep_pipe(s_interface, n_ep)) == TOKEN_IN)

true if the endpoint direction associated with the supported interface is IN

Parameters

s_interface	uint8_t: The supported interface number
n_ep	uint8_t: The endpoint number in this interface

Returns

bool: Endpoint direction IN?

Referenced by host_mass_storage_task().

#define OFFSET_DESCRIPTOR_LENGTH   0

Offsets common to all descriptor types.

Referenced by host_check_class().

#define OFFSET_FIELD_ALT   3

Referenced by host_check_class().

#define OFFSET_FIELD_BMATTRIBUTES   7

Referenced by host_check_class().

#define OFFSET_FIELD_CLASS   5

Referenced by host_check_class().

#define OFFSET_FIELD_CONFIGURATION_NB   5

Referenced by usb_host_task().

#define OFFSET_FIELD_DESCRIPTOR_TYPE   1

Referenced by host_check_class().

#define OFFSET_FIELD_EP_ADDR   2

Offsets in endpoint descriptors.

Referenced by host_check_class().

#define OFFSET_FIELD_EP_INTERVAL   6

Referenced by host_check_class().

#define OFFSET_FIELD_EP_SIZE   4

Referenced by host_check_class().

#define OFFSET_FIELD_EP_TYPE   3

Referenced by host_check_class().

#define OFFSET_FIELD_INTERFACE_NB   2

Offsets in interface descriptors.

Referenced by host_check_class().

#define OFFSET_FIELD_MAXPACKETSIZE   7

Offsets in device descriptors.

Referenced by usb_host_task().

#define OFFSET_FIELD_MAXPOWER   8

Referenced by host_check_class().

#define OFFSET_FIELD_NB_CONFIGURATION   17

#define OFFSET_FIELD_NB_INTERFACE   4

#define OFFSET_FIELD_NB_OF_EP   4

Referenced by host_check_class().

#define OFFSET_FIELD_PID   10

Referenced by host_check_VID_PID().

#define OFFSET_FIELD_PROTOCOL   7

Referenced by host_check_class().

#define OFFSET_FIELD_SUB_CLASS   6

Referenced by host_check_class().

#define OFFSET_FIELD_TOTAL_LENGTH   2

Offsets in configuration descriptors.

Referenced by host_check_class().

#define OFFSET_FIELD_VID   8

Referenced by host_check_VID_PID().

#define REMOTE_WAKEUP_BIT   5

#define REMOTE_WAKEUP_MASK   (1 << REMOTE_WAKEUP_BIT)

#define SELF_POWERED_BIT   6

#define SELF_POWERED_MASK   (1 << SELF_POWERED_BIT)

bool host_check_class

(

void

)

This function checks if the device class is supported.

The function looks in all interfaces declared in the received descriptors if one of them matches an entry of the CLASS/SUB_CLASS/PROTOCOL table. If HOST_AUTO_CFG_ENDPOINT is enabled, a pipe is configured for each endpoint of supported interfaces.

Returns

bool: Status

References S_interface::altset_nb, bmattributes, CONFIGURATION_DESCRIPTOR, cpu_irq_disable, cpu_irq_enable, data_stage, DOUBLE_BANK, ENDPOINT_DESCRIPTOR, S_interface::ep_pipe, Get_desc_ep_nbr, Get_pipe_token, Host_clear_configured, Host_configure_pipe, Host_disable_pipe, Host_enable_pipe, Host_set_configured, Host_unallocate_memory, Host_user_check_class_action, INTERFACE_DESCRIPTOR, S_interface::interface_nb, Is_host_pipe_enabled, MAX_EP_PER_INTERFACE, MAX_INTERFACE_SUPPORTED, MAX_PEP_NB, maxpower, min, S_interface::nb_ep, nb_interface_supported, OFFSET_DESCRIPTOR_LENGTH, OFFSET_FIELD_ALT, OFFSET_FIELD_BMATTRIBUTES, OFFSET_FIELD_CLASS, OFFSET_FIELD_DESCRIPTOR_TYPE, OFFSET_FIELD_EP_ADDR, OFFSET_FIELD_EP_INTERVAL, OFFSET_FIELD_EP_SIZE, OFFSET_FIELD_EP_TYPE, OFFSET_FIELD_INTERFACE_NB, OFFSET_FIELD_MAXPOWER, OFFSET_FIELD_NB_OF_EP, OFFSET_FIELD_PROTOCOL, OFFSET_FIELD_SUB_CLASS, OFFSET_FIELD_TOTAL_LENGTH, P_1, S_interface::protocol, REG_CLASS_CNT, registered_class, SINGLE_BANK, SIZEOF_DATA_STAGE, S_interface::subclass, TYPE_BULK, TYPE_INTERRUPT, S_interface::uclass, and usb_format_usb_to_mcu_data.

Referenced by usb_host_task().

bool host_check_VID_PID

(

void

)

This function checks if the VID and the PID are supported (if the VID & PID belong to the VID_PID table).

Returns

bool: Status

References data_stage, device_PID, device_VID, OFFSET_FIELD_PID, OFFSET_FIELD_VID, REG_VID_PID_CNT, registered_VID_PID, and usb_format_usb_to_mcu_data.

Referenced by usb_host_task().

Status_t host_transfer_control

(

void *

data_pointer

)

This function is the generic control pipe management function.

This function is used to send and receive control requests over control pipe.

Todo:

Fix all time-out errors and disconnections in active wait loop.

Parameters

data_pointer

void *: Pointer to data to transfer

Returns

Status_t: Status

Note

This function uses the usb_request global structure. Hence, this structure should be filled before calling this function.

References S_usb_setup_data::bmRequestType, S_usb_setup_data::bRequest, CONTROL_GOOD, CONTROL_STALL, CONTROL_TIMEOUT, cpu_irq_disable, cpu_irq_enable, cpu_irq_is_enabled, EVT_HOST_SOF, Host_ack_all_errors, Host_ack_control_in_received, Host_ack_control_in_received_free, Host_ack_control_out_ready, Host_ack_control_out_ready_send, Host_ack_setup_ready, Host_ack_sof, Host_ack_stall, Host_byte_count, Host_configure_pipe_token, Host_disable_continuous_in_mode, Host_disable_sof_interrupt, Host_enable_sof_interrupt, Host_error_status, Host_free_control_in, Host_freeze_pipe, Host_get_pipe_size, host_get_timeout(), host_read_p_rxpacket(), Host_reset_pipe, Host_reset_pipe_fifo_access, Host_send_control_out, Host_send_setup, Host_unfreeze_pipe, host_write_p_txpacket(), Host_write_pipe_data, S_usb_setup_data::incomplete_read, Is_host_control_in_received, Is_host_control_out_ready, Is_host_emergency_exit, Is_host_pipe_error, Is_host_setup_ready, Is_host_sof_interrupt_enabled, Is_host_stall, Is_usb_event, Is_usb_low_speed_mode, P_CONTROL, private_sof_counter, TOKEN_IN, TOKEN_OUT, TOKEN_SETUP, Usb_ack_event, usb_format_mcu_to_usb_data, usb_request, S_usb_setup_data::wIndex, S_usb_setup_data::wLength, and S_usb_setup_data::wValue.

volatile uint8_t bmattributes

bmAttributes byte of connected device

Referenced by host_check_class().

volatile uint16_t device_PID

PID of connected device.

Referenced by host_check_VID_PID().

volatile uint16_t device_VID

VID of connected device.

Referenced by host_check_VID_PID().

volatile S_interface interface_supported[MAX_INTERFACE_SUPPORTED]

Supported interfaces.

volatile uint8_t maxpower

maxpower byte of connected device (unit is 2 mA)

Referenced by host_check_class().

volatile uint8_t nb_interface_supported

Number of interfaces the host is able to support in the connected device.

Referenced by host_check_class(), and usb_host_task().