USB Host Core API#

USBH_ConfigureBufAlignOctets()
USBH_ConfigureMaxDescLen()
USBH_ConfigureEventFncts()
USBH_ConfigureOptimizeSpdCfg()
USBH_ConfigureInitAllocCfg()
USBH_ConfigureHubTaskStk()
USBH_ConfigureAsyncTaskStk()
USBH_ConfigureMemSeg()
USBH_Init()
USBH_PreferredStrLangID_Set()
USBH_StdReqTimeoutSet()
USBH_AsyncTaskPrioSet()
USBH_UnInit()
USBH_HC_Add()
USBH_HC_HandleGetFromName()
USBH_HC_Start()
USBH_HC_Stop()
USBH_HC_Suspend()
USBH_HC_Resume()
USBH_HC_FrameNbrGet()
USBH_DevSpdGet()
USBH_DevAddrGet()
USBH_DevHostNbrGet()
USBH_DevHC_NbrGet()
USBH_DevSpecNbrGet()
USBH_DevClassGet()
USBH_DevSubclassGet()
USBH_DevProtocolGet()
USBH_DevVendorID_Get()
USBH_DevProductID_Get()
USBH_DevRelNbrGet()
USBH_DevManufacturerStrGet()
USBH_DevProductStrGet()
USBH_DevSerNbrStrGet()
USBH_DevConfigQtyGet()
USBH_DevConfigSet()
USBH_DevConfigGet()
USBH_DevPortNbrGet()
USBH_DevHubHandleGet()
USBH_DevHS_HubNearestHandleGet()
USBH_DevDescRd()
USBH_ConfigAttribGet()
USBH_ConfigFnctQtyGet()
USBH_ConfigMaxPwrGet()
USBH_ConfigStrGet()
USBH_FnctIF_QtyGet()
USBH_FnctClassGet()
USBH_FnctSubclassGet()
USBH_FnctProtocolGet()
USBH_FnctStrGet()
USBH_IF_NbrGet()
USBH_IF_AltNbrGet()
USBH_IF_AltIxCurGet()
USBH_IF_EP_QtyGet()
USBH_IF_ClassGet()
USBH_IF_SubclassGet()
USBH_IF_ProtocolGet()
USBH_IF_StrGet()
USBH_IF_DescExtraGet()
USBH_IF_EP_AddrNextGet()
USBH_IF_AltSet()
USBH_EP_AttribGet()
USBH_EP_MaxPktSizeGet()
USBH_EP_IntervalGet()
USBH_EP_CtrlXfer()

USBH_ConfigureBufAlignOctets()#

Description#

Configures the alignment of the internal buffers.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureBufAlignOctets (CPU_SIZE_T  buf_align_octets)

Arguments#

buf_align_octets

Buffer alignment, in octets.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.

USBH_ConfigureMaxDescLen()#

Description#

Configures the length of the buffer used to retrieve the USB descriptors from the devices.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureMaxDescLen (CPU_INT16U  max_desc_len)

Arguments#

max_desc_len

Length of the descriptor buffer.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.

USBH_ConfigureEventFncts()#

Description#

Sets the structure of callback that will be used by the USB host module to notify the application of certain events.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureEventFncts(const  USBH_EVENT_FNCTS  *p_event_fncts)

Arguments#

p_event_fncts

Pointer to a structure containing the event functions to call. Content MUST be persistent.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.

USBH_ConfigureOptimizeSpdCfg()#

Description#

Sets the configurations required when optimize speed mode is enabled.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureOptimizeSpdCfg(const  USBH_CFG_OPTIMIZE_SPD  *p_optimize_spd_cfg)

Arguments#

p_optimize_spd_cfg

Pointer to the structure containing the configurations for the optimize speed mode.

Returned Value#

None.

Notes / Warnings#

This function MUST be called before the USB Host module is initialized via the USBH_Init() function.
This function MUST be called when the USBH_CFG_OPTIMIZE_SPD_EN configuration is set to DEF_ENABLED.

USBH_ConfigureInitAllocCfg()#

Description#

Sets the configurations required when allocation at initialization mode is enabled.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureInitAllocCfg(const  USBH_CFG_INIT_ALLOC  *p_init_alloc_cfg)

Arguments#

p_init_alloc_cfg

Pointer to the structure containing the configurations for the allocation at initialization mode.

Returned Value#

None.

Notes / Warnings#

This function MUST be called before the USB Host module is initialized via the USBH_Init() function.
This function MUST be called when the USBH_CFG_INIT_ALLOC_EN configuration is set to DEF_ENABLED.

USBH_ConfigureHubTaskStk()#

Description#

Configures the USB host hub task's stack.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureHubTaskStk (CPU_INT32U   stk_size_elements,
                                void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from KAL's memory segment.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.
In order to change the priority of the USB host hub task, use the function USBH_HUB_TaskPrioSet() available in file usbh_core_hub.h.

USBH_ConfigureAsyncTaskStk()#

Description#

Configures the USB host asynchronous task's stack.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureAsyncTaskStk (CPU_INT32U   stk_size_elements,
                                  void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from Common's memory segment.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.
In order to change the priority of the USB host hub task, use the function USBH_AsyncTaskPrioSet() .

USBH_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data and buffers.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_ConfigureMemSeg (MEM_SEG  *p_mem_seg,
                            MEM_SEG  *p_mem_seg_buf)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. Can be the same segment used for p_mem_seg_buf. DEF_NULL means general purpose heap segment.

p_mem_seg_buf

Pointer to memory segment to use when allocating data buffers. Can be the same segment used for p_mem_seg. DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

This function is optional, if it is not called, the default value will be used.
This function MUST be called before the USB Host module is initialized via the USBH_Init() function.

USBH_Init()#

Description#

Initializes USB Host stack.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_Init (CPU_INT08U   host_qty,
                 RTOS_ERR    *p_err)

Arguments#

host_qty

Quantity of USB host.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_SEG_OVF
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

USBH_Init() must be called:
(a) Only once from a product's application.
(b) After product's OS has been initialized.

USBH_PreferredStrLangID_Set()#

Description#

Sets the preferred language ID to use when retrieving strings from the device.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_PreferredStrLangID_Set(CPU_INT16U   preferred_str_lang_id,
                                  RTOS_ERR    *p_err)

Arguments#

preferred_str_lang_id

ID of the preferred language. See file usbh_core_langid.h for a list of language IDs.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

This function cannot be called before the USB Host module has been initialized via the USBH_Init() function.

USBH_StdReqTimeoutSet()#

Description#

Assigns a new timeout delay for the USB standard requests.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_StdReqTimeoutSet(CPU_INT32U   std_req_timeout_ms,
                            RTOS_ERR    *p_err)

Arguments#

std_req_timeout_ms

New timeout, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

This function cannot be called before the USB Host module has been initialized via the USBH_Init() function.

USBH_AsyncTaskPrioSet()#

Description#

Assigns a new priority to the USB host async task.

Files#

usbh_core.h/usbh_core.c

Prototype#

void  USBH_AsyncTaskPrioSet(CPU_INT08U   prio,
                            RTOS_ERR    *p_err)

Arguments#

prio

New priority of the the async task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

This function cannot be called before the USB Host module has been initialized via the USBH_Init() function.

USBH_UnInit()#

Description#

Un-initializes the USB Host stack.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_UnInit (RTOS_ERR    *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_POOL_UNLIMITED
RTOS_ERR_SEG_OVF
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

USBH_UnInit() must be called after all the HCs have been stopped.
Once the USB host has been uninitialized, all the used memory segments can be cleared and re-used for other purposes.

USBH_HC_Add()#

Description#

Adds the host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

USBH_HC_HANDLE USBH_HC_Add (const  CPU_CHAR         *name,
                            const  USBH_HC_CFG_EXT  *p_hc_cfg_ext,
                                   RTOS_ERR         *p_err)

Arguments#

name

USB controller name.

p_hc_cfg_ext

Pointer to the extended USB host controller configuration. Can be null when USBH_CFG_OPTIMIZE_SPD_EN and USBH_CFG_INIT_ALLOC_EN are set to DEF_DISABLED.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_NOT_AVAIL
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_POOL_EMPTY
RTOS_ERR_ALLOC
RTOS_ERR_NOT_FOUND
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF

Returned Value#

Host Controller handle, if host controller successfully added. USBH_HC_HANDLE_INVALID, if host controller was not added.

Notes / Warnings#

None.

USBH_HC_HandleGetFromName()#

Description#

Gets Host Controller handle from USB controller name.

Files#

usbh_core.h/usbh_core.c

Prototype#

USBH_HC_HANDLE  USBH_HC_HandleGetFromName (const  CPU_CHAR  *name)

Arguments#

name

USB controller name.

Returned Value#

Host Controller handle, if host controller successfully retrieved. USBH_HC_HANDLE_INVALID, if host controller was not retrieved.

Notes / Warnings#

None.

USBH_HC_Start()#

Description#

Starts the given host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_HC_Start (USBH_HC_HANDLE   hc_handle,
                    RTOS_ERR        *p_err)

Arguments#

hc_handle

Host controller handle.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_FAIL
RTOS_ERR_IO
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBH_HC_Stop()#

Description#

Stops the given host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_HC_Stop (USBH_HC_HANDLE     hc_handle,
                   USBH_HC_OPER_CMPL  callback_fnct,
                   void               *p_arg,
                   RTOS_ERR           *p_err)

Arguments#

hc_handle

Handle to host controller.

callback_fnct

Function that will be called after operation is completed. Can be null.

p_arg

Pointer to the argument that will be passed to the callback function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ALLOC
RTOS_ERR_WOULD_OVF
RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

None.

USBH_HC_Suspend()#

Description#

Suspends the host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_HC_Suspend (USBH_HC_HANDLE      hc_handle,
                       USBH_HC_OPER_CMPL   callback_fnct,
                       void               *p_arg,
                       RTOS_ERR           *p_err)

Arguments#

hc_handle

Handle to host controller.

callback_fnct

Pointer to the function that will be called after the operation is completed.

p_arg

Pointer to the argument that will be passed to the callback function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ALLOC
RTOS_ERR_WOULD_OVF
RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

None.

USBH_HC_Resume()#

Description#

Resumes the host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

void USBH_HC_Resume (USBH_HC_HANDLE      hc_handle,
                     USBH_HC_OPER_CMPL   callback_fnct,
                      void               *p_arg,
                      RTOS_ERR           *p_err)

Arguments#

hc_handle

Handle to host controller.

callback_fnct

Function that will be called after the operation is completed.

p_arg

Pointer to the argument that will be passed to the callback function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ALLOC
RTOS_ERR_WOULD_OVF
RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

None.

USBH_HC_FrameNbrGet()#

Description#

Retrieves the current frame number for the given host controller.

Files#

usbh_core.h/usbh_core.c

Prototype#

CPU_INT16U USBH_HC_FrameNbrGet (USBH_HC_HANDLE   hc_handle,
                                   RTOS_ERR        *p_err)

Arguments#

hc_handle

Handle to host controller.

p_err

Pointer to the variable that will receive this return error code from this function :

RTOS_ERR_NONE

Returned Value#

Current frame number processed by Host Controller, if successful.
0, if unsuccessful.

Notes / Warnings#

None.

USBH_DevSpdGet()#

Description#

Gets the device speed.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

USBH_DEV_SPD USBH_DevSpdGet (USBH_DEV_HANDLE    dev_handle,
                              RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device speed, if successful. USBH_DEV_SPD_NONE, if unsuccessful.

Notes / Warnings#

None.

USBH_DevAddrGet()#

Description#

Gets the device address.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevAddrGet (USBH_DEV_HANDLE   dev_handle,
                             RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device address, if successful.
USBH_DEV_ADDR_INVALID, if unsuccessful.

Notes / Warnings#

None.

USBH_DevHostNbrGet()#

Description#

Gets the host number to which the device is connected.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevHostNbrGet (USBH_DEV_HANDLE   dev_handle,
                                RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE

Returned Value#

Host number, if successful.
0, if unsuccessful.

Notes / Warnings#

None.

USBH_DevHC_NbrGet()#

Description#

Gets the host controller number to which the device is connected.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevHC_NbrGet (USBH_DEV_HANDLE   dev_handle,
                               RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE

Returned Value#

Host controller number, if successful.
USBH_HC_NBR_NONE, if unsuccessful.

Notes / Warnings#

None.

USBH_DevSpecNbrGet()#

Description#

Gets the device specification number.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device specification number, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the 'bcdUSB' field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevClassGet()#

Description#

Gets the device class code.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevClassGet (USBH_DEV_HANDLE   dev_handle,                              RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device class code.

Notes / Warnings#

The value returned by this function corresponds to the bDeviceClass field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevSubclassGet()#

Description#

Gets the device subclass code.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device subclass code.

Notes / Warnings#

The value returned by this function corresponds to the bDeviceSubClass field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevProtocolGet()#

Description#

Gets the device protocol code.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE    dev_handle,                                    RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device protocol code.

Notes / Warnings#

The value returned by this function corresponds to the bDeviceProtocol field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1' .

USBH_DevVendorID_Get()#

Description#

Gets the device vendor ID.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device protocol code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the idVendor field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevProductID_Get()#

Description#

Gets the device product ID.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device protocol code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the idProduct field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevRelNbrGet()#

Description#

Gets the device release number.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device release number, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the bcdDevice field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevManufacturerStrGet()#

Description#

Gets the device manufacturer string.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevManufacturerStrGet (USBH_DEV_HANDLE   dev_handle,
                                        CPU_CHAR         *p_str_buf,
                                        CPU_INT08U        str_buf_len,
                                        RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_str_buf

Buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_DESC
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_NOT_FOUND
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

String length in octets, if successful. 0, if unsuccessful.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the 'iManufacturer' field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.
The string retrieved by this function is in unicode format.
This function can determine if a device manufacturer string is present by passing a str_buf_len of 0. In this case, p_err will be set to RTOS_ERR_NOT_FOUND if no string is available.

USBH_DevProductStrGet()#

Description#

Gets the device product string.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevProductStrGet (USBH_DEV_HANDLE   dev_handle,
                                   CPU_CHAR         *p_str_buf,
                                   CPU_INT08U        str_buf_len,
                                   RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_str_buf

Buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_DESC
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_NOT_FOUND
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

String length in octets, if successful. 0, if unsuccessful.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the iProduct field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.
The string retrieved by this function is in unicode format.
This function can be used to determine if a device product string is present or not by passing a str_buf_len of 0. In this case, p_err will be set to RTOS_ERR_NOT_FOUND if no string is available.

USBH_DevSerNbrStrGet()#

Description#

Gets the device serial number string.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevSerNbrStrGet (USBH_DEV_HANDLE   dev_handle,
                                  CPU_CHAR         *p_str_buf,
                                  CPU_INT08U        str_buf_len,
                                  RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_str_buf

Buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_DESC
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_NOT_FOUND
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

String length in octets, if successful. 0, if unsuccessful.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the iSerialNumber field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.
The string retrieved by this function is in unicode format.
This function can be used to determine if a device serial number string is present or not by passing a str_buf_len of 0. In this case, p_err will be set to RTOS_ERR_NOT_FOUNDif no string is available.

USBH_DevConfigQtyGet()#

Description#

Gets the quantity of configuration contained in the device.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevConfigQtyGet (USBH_DEV_HANDLE   dev_handle,
                                  RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Number of configuration, if successful. 0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the bNumConfigurations field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_DevConfigSet()#

Description#

Sets the given device configuration.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

void USBH_DevConfigSet (USBH_DEV_HANDLE   dev_handle,
                         CPU_INT08U        cfg_nbr,
                         RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

cfg_nbr

Configuration number to set.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_ALLOC
RTOS_ERR_NOT_SUPPORTED
RTOS_ERR_INVALID_ARG
RTOS_ERR_WOULD_OVF
RTOS_ERR_NOT_AVAIL
RTOS_ERR_INVALID_STATE

Returned Value#

none.

Notes / Warnings#

Set configuration is not supported on hub devices.
Two consecutive calls to this function will result in a failure of the second call, since the device handle passed as argument will necessarily be invalid.

USBH_DevConfigGet()#

Description#

Gets the currently selected configuration.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevConfigGet (USBH_DEV_HANDLE   dev_handle,
                               RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device current configuration number.

Notes / Warnings#

None.

USBH_DevPortNbrGet()#

Description#

Gets the device hub port number.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT08U USBH_DevPortNbrGet (USBH_DEV_HANDLE   dev_handle,
                                RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device current configuration number.

Notes / Warnings#

None.

USBH_DevHubHandleGet()#

Description#

Gets handle on device's hub.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

USBH_DEV_HANDLE USBH_DevHubHandleGet (USBH_DEV_HANDLE   dev_handle,
                                       RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on device.

p_err

Pointer to the variable that will receive the return error code from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Device's hub handle, if successful. USBH_DEV_HANDLE_RH, if nearest hub is root hub. USBH_DEV_HANDLE_INVALID, if an error occured.

Notes / Warnings#

None.

USBH_DevHS_HubNearestHandleGet()#

Description#

Gets the handle of device's nearest hub working at high-speed.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

USBH_DEV_HANDLE USBH_DevHS_HubNearestHandleGet (USBH_DEV_HANDLE   dev_handle,
                                                 CPU_INT08U       *p_port_nbr,
                                                 RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

p_port_nbr

Pointer to the variable that will receive the port number of the high-speed hub (if not null).

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_DEV_SPD
RTOS_ERR_INVALID_STATE

Returned Value#

Device's nearest high-speed hub handle, if successful. USBH_DEV_HANDLE_RH, if the nearest high-speed hub is the root hub. USBH_DEV_HANDLE_INVALID, if an error occurred.

Notes / Warnings#

None.

USBH_DevDescRd()#

Description#

Reads the descriptor from the device.

Files#

usbh_core_dev.h/usbh_core_dev.c

Prototype#

CPU_INT16U USBH_DevDescRd (USBH_DEV_HANDLE dev_handle,
                            CPU_INT08U   recipient,
                            CPU_INT08U   type,
                            CPU_INT08U   desc_type,
                            CPU_INT08U   desc_ix,
                            CPU_INT16U   desc_len_req,
                            CPU_INT08U  *p_desc_buf,
                            CPU_INT16U   desc_buf_len,
                            RTOS_ERR    *p_err)

Arguments#

dev_handle

Handle on the device.

recipient

Recipient of the Get descriptor request.

USBH_REQ_RECIPIENT_DEV
USBH_REQ_RECIPIENT_IF
USBH_REQ_RECIPIENT_EP

type

Request type.

USBH_REQ_TYPE_STD
USBH_REQ_TYPE_CLASS
USBH_REQ_TYPE_VENDOR

desc_type

Descriptor type.

USBH_DESC_TYPE_DEV
USBH_DESC_TYPE_CONFIG
USBH_DESC_TYPE_STR
USBH_DESC_TYPE_DEV_QUALIFIER
USBH_DESC_TYPE_OTHER_SPD_CONFIG
USBH_DESC_TYPE_IF_PWR
USBH_DESC_TYPE_OTG

desc_ix

wIndex value that should be used in the setup request.

desc_len_req

wLength value to use in the setup request.

p_desc_buf

Pointer to the buffer that will receive the descriptor.

desc_buf_len

Length in octets of the descriptor buffer.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

Descriptor length in octets.

Notes / Warnings#

The GET_DESCRIPTOR request is described in 'Universal Serial Bus Specification Revision 2.0, section 9.4.3'.

USBH_ConfigAttribGet()#

Description#

Gets the configuration's attributes.

Files#

usbh_core_config.h/usbh_core_config.c

Prototype#

CPU_INT08U  USBH_ConfigAttribGet (USBH_DEV_HANDLE    dev_handle,
                                   RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Configuration's attributes.

Notes / Warnings#

The value returned by this function corresponds to the bmAttributes field of the configuration descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.3'.

USBH_ConfigFnctQtyGet()#

Description#

Gets the quantity of function contained in device's current configuration.

Files#

usbh_core_config.h/usbh_core_config.c

Prototype#

CPU_INT08U  USBH_ConfigFnctQtyGet (USBH_DEV_HANDLE    dev_handle,
                                  RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Quantity of function.

Notes / Warnings#

None.

USBH_ConfigMaxPwrGet()#

Description#

Gets the configuration's maximum power consumption.

Files#

usbh_core_config.h/usbh_core_config.c

Prototype#

  CPU_INT08U  USBH_ConfigMaxPwrGet (USBH_DEV_HANDLE    dev_handle,
                                     RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Configuration's maximum power consumption.

Notes / Warnings#

The value returned by this function corresponds to the bMaxPower field of the configuration descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.3'.

USBH_ConfigStrGet()#

Description#

Gets the configuration's string.

Files#

usbh_core_config.h/usbh_core_config.c

Prototype#

CPU_INT08U  USBH_ConfigStrGet (USBH_DEV_HANDLE    dev_handle,
                                CPU_CHAR          *p_str_buf,
                                CPU_INT08U         str_buf_len,
                                RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

p_str_buf

Buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_INVALID_DESC
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_NOT_FOUND
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

String length in octets.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the iConfiguration field of the configuration descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.3'.
The string retrieved by this function is in unicode format.
This function can be used to determine if a configuration string is present by passing a str_buf_len of 0. In this case, p_err will be set to RTOS_ERR_NOT_FOUND if no string is available.

USBH_FnctIF_QtyGet()#

Description#

Gets the quantity of interface contained in given function.

Files#

usbh_core_fnct.h/usbh_core_fnct.c

Prototype#

CPU_INT08U USBH_FnctIF_QtyGet (USBH_DEV_HANDLE     dev_handle,
                                USBH_FNCT_HANDLE    fnct_handle,
                                RTOS_ERR           *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Quantity of interface, if successful.
0, if unsuccessful.

Notes / Warnings#

None.

USBH_FnctClassGet()#

Description#

Get the function's class code.

Files#

usbh_core_fnct.h/usbh_core_fnct.c

Prototype#

CPU_INT08U USBH_FnctClassGet (USBH_DEV_HANDLE    dev_handle,
                               USBH_FNCT_HANDLE   fnct_handle,
                               RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Class code, if successful. 0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the class code.
(a) If the function has only one interface, it corresponds to the bInterfaceClass field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.
(b) If the function has more than one interface, it corresponds to the bFunctionClass field of the Interface Association Descriptor (IAD). For more information, see 'USB ECN: Interface Association Descriptor'.
(c) If the class code is defined at device level, it corresponds to the bDeviceClass field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_FnctSubclassGet()#

Description#

Get the function's subclass code.

Files#

usbh_core_fnct.h/usbh_core_fnct.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Subclass code, if successful. 0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the subclass code.
(a) If the function has only one interface, it corresponds to the bInterfaceSubClass field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.
(b) If the function has more than one interface, it corresponds to the bFunctionSubClass field of the Interface Association Descriptor (IAD). For more information, see 'USB ECN: Interface Association Descriptor'.
(c) If the class code is defined at device level, it corresponds to the bDeviceSubClass field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_FnctProtocolGet()#

Description#

Get the function's protocol code.

Files#

usbh_core_fnct.h/usbh_core_fnct.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_STATE

Returned Value#

Protocol code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the protocol code.
(a) If the function has only one interface, it corresponds to the bInterfaceProtocol field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.
(b) If the function has more than one interface, it corresponds to the bFunctionProtocol field of the Interface Association Descriptor (IAD). See For more information, see 'USB ECN: Interface Association Descriptor'.
(c) If the class code is defined at device level, it corresponds to the bDeviceProtocol field of the device descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.1'.

USBH_FnctStrGet()#

Description#

Gets the given function's string descriptor.

Files#

usbh_core_fnct.h/usbh_core_fnct.c

Prototype#

CPU_INT08U USBH_FnctStrGet (USBH_DEV_HANDLE     dev_handle,
                             USBH_FNCT_HANDLE    fnct_handle,
                             CPU_CHAR           *p_str_buf,
                             CPU_INT08U          str_buf_len,
                             RTOS_ERR           *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

p_str_buf

Pointer to the buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_NOT_FOUND

Returned Value#

String descriptor length in octets.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the iConfiguration field of the configuration descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.3'.
The string retrieved by this function is in unicode format.
This function can determine if a function string is present or not by passing a str_buf_len of 0. In this case, p_err will be set to RTOS_ERR_NOT_FOUND if no string is available.

USBH_IF_NbrGet()#

Description#

Gets the interface number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_NbrGet (USBH_DEV_HANDLE    dev_handle,
                            USBH_FNCT_HANDLE   fnct_handle,
                            CPU_INT08U         if_ix,
                            RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Interface number.

Notes / Warnings#

The value returned by this function corresponds to the 'bInterfaceNumber' field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.

USBH_IF_AltNbrGet()#

Description#

Gets the interface alternate number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_AltNbrGet (USBH_DEV_HANDLE     dev_handle,
                               USBH_FNCT_HANDLE    fnct_handle,
                               CPU_INT08U          if_ix,
                               RTOS_ERR           *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Interface alternate number.

Notes / Warnings#

The value returned by this function corresponds to the bAlternateSetting field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.

USBH_IF_AltIxCurGet()#

Description#

Gets the interface's currently selected alternate number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_AltIxCurGet (USBH_DEV_HANDLE    dev_handle,
                                 USBH_FNCT_HANDLE   fnct_handle,
                                 CPU_INT08U         if_ix,
                                 RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
TOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Currently selected interface alternate number.

Notes / Warnings#

None.

USBH_IF_EP_QtyGet()#

Description#

Gets the quantity of endpoint contained in interface.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_EP_QtyGet (USBH_DEV_HANDLE     dev_handle,
                               USBH_FNCT_HANDLE    fnct_handle,
                               CPU_INT08U          if_ix,
                               RTOS_ERR           *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Quantity of endpoint, if successful.
0, if unsuccessful.

Notes / Warnings#

None.

USBH_IF_ClassGet()#

Description#

Gets the interface class code number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE   dev_handle,
                                    RTOS_ERR         *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Interface class code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the bInterfaceClass field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.

USBH_IF_SubclassGet()#

Description#

Gets the interface subclass code number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE    dev_handle,
                                    RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Interface subclass code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the bInterfaceSubClass field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.

USBH_IF_ProtocolGet()#

Description#

Gets the interface protocol code number.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

typedef CPU_INT32U USBH_DevSpdGet (USBH_DEV_HANDLE    dev_handle,
                                    RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Interface protocol code, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the bInterfaceProtcol field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.

USBH_IF_StrGet()#

Description#

Gets the interfaces's string.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_StrGet (USBH_DEV_HANDLE    dev_handle,
                            USBH_FNCT_HANDLE   fnct_handle,
                            CPU_INT08U         if_ix,
                            CPU_CHAR          *p_str_buf,
                            CPU_INT08U         str_buf_len,
                            RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_str_buf

Buffer that will receive the string descriptor.

str_buf_len

String buffer length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_NOT_FOUND

Returned Value#

String length in octets.

Notes / Warnings#

The string returned by this function is retrieved via the GetDescriptor(String) standard request using the 'iInterface' field of the interface descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.5'.
The string retrieved by this function is in unicode format.
This function can be used to determine if an interface string is present or not by passing a str_buf_len of 0. In that case p_err will be set to RTOS_ERR_NOT_FOUND if no string is available.

USBH_IF_DescExtraGet()#

Description#

Gets the interfaces's extra descriptor(s).

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U *USBH_IF_DescExtraGet (USBH_FNCT_HANDLE   fnct_handle,
                                   CPU_INT08U         if_ix,
                                   CPU_INT16U        *p_desc_extra_len,
                                   RTOS_ERR          *p_err)

Arguments#

fnct_handle

Handle on the function.

if_ix

Index of the interface.

p_desc_extra_len

Pointer to the variable that will receive total extra descriptors length in octets.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_NULL_PTR
RTOS_ERR_INVALID_STATE

Returned Value#

Pointer to the buffer that contains interface's extra descriptor(s).

Notes / Warnings#

First descriptor returned by this function will always be the interface descriptor itself.

USBH_IF_EP_AddrNextGet()#

Description#

Retrieves the address of the next endpoint available on interface.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

CPU_INT08U USBH_IF_EP_AddrNextGet (USBH_DEV_HANDLE     dev_handle,
                                    USBH_FNCT_HANDLE    fnct_handle,
                                    CPU_INT08U          if_ix,
                                    CPU_INT08U          ep_addr_prev,
                                    RTOS_ERR           *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

ep_addr_prev

Previous endpoint address, or 0 u to obtain first endpoint address.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Next interface's available endpoint's address, if successful.
0 u, if an error occurred or if the last endpoint was reached.

Notes / Warnings#

None.

USBH_IF_AltSet()#

Description#

Sets the alternate interface and attempt to open related endpoints.

Files#

usbh_core_if.h/usbh_core_if.c

Prototype#

void USBH_IF_AltSet (USBH_DEV_HANDLE       dev_handle,
                      USBH_FNCT_HANDLE      fnct_handle,
                      CPU_INT08U            if_ix,
                      CPU_INT08U            if_alt_ix,
                      USBH_IF_ALT_SET_CMPL  callback_fnct,
                      void                 *p_arg,
                      RTOS_ERR             *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Index of the interface.

if_alt_ix

Index of the alternate interface.

callback_fnct

Function to call when operation is completed.

p_arg

Pointer to the argument that will be passed to the callback function.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_ALLOC
RTOS_ERR_INVALID_ARG
RTOS_ERR_WOULD_OVF
RTOS_ERR_NOT_AVAIL
RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

None.

USBH_EP_AttribGet()#

Description#

Gets the endpoint attributes.

Files#

usbh_core_ep.h/usbh_core_ep.c

Prototype#

CPU_INT08U USBH_EP_AttribGet (USBH_DEV_HANDLE    dev_handle,
                               USBH_FNCT_HANDLE   fnct_handle,
                               CPU_INT08U         if_ix,
                               CPU_INT08U         ep_addr,
                               RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

fnct_handle

Handle on the function.

if_ix

Interface index.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Endpoint attributes, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the 'bmAttributes' field of the endpoint descriptor. See 'Universal Serial Bus specification, revision 2.0, section 9.6.6' for more information.

USBH_EP_MaxPktSizeGet()#

Description#

Gets the endpoint maximum packet size.

Files#

usbh_core_ep.h/usbh_core_ep.c

Prototype#

CPU_INT16U USBH_EP_MaxPktSizeGet (USBH_DEV_HANDLE    dev_handle,
                                   USBH_FNCT_HANDLE   fnct_handle,
                                   CPU_INT08U         if_ix,
                                   CPU_INT08U         ep_addr,
                                   RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on device.

fnct_handle

Handle on function.

if_ix

Interface index.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Endpoint maximum packet size, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the 'wMaxPacketSize' field of the endpoint descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.6'.

USBH_EP_IntervalGet()#

Description#

Gets the endpoint interval.

Files#

usbh_core_ep.h/usbh_core_ep.c

Prototype#

CPU_INT08U USBH_EP_IntervalGet (USBH_DEV_HANDLE    dev_handle,
                                 USBH_FNCT_HANDLE   fnct_handle,
                                 CPU_INT08U         if_ix,
                                 CPU_INT08U         ep_addr,
                                 RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on device.

fnct_handle

Handle on function.

if_ix

Interface index.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

Endpoint interval, if successful.
0, if unsuccessful.

Notes / Warnings#

The value returned by this function corresponds to the 'bInterval' field of the endpoint descriptor. For more information, see 'Universal Serial Bus specification, revision 2.0, section 9.6.6' .

USBH_EP_CtrlXfer()#

Description#

Perform the synchronous control transfer on endpoint.

Files#

usbh_core_ep.h/usbh_core_ep.c

Prototype#

CPU_INT16U USBH_EP_CtrlXfer (USBH_DEV_HANDLE    dev_handle,
                              CPU_INT08U         req,
                              CPU_INT08U         req_type,
                              CPU_INT16U         val,
                              CPU_INT16U         ix,
                              CPU_INT08U        *p_buf,
                              CPU_INT16U         len,
                              CPU_INT16U         buf_len,
                              CPU_INT32U         timeout,
                              RTOS_ERR          *p_err)

Arguments#

dev_handle

Handle on the device.

req

bRequest value of the setup packet.

req_type

bmRequestType value of the setup packet.

val

wValue value of the setup packet.

ix

wIndex value of the setup packet.

p_buf

Pointer to the data buffer for the data phase.

len

wLength value of the setup packet that specifies the number of data bytes in data stage.

buf_len

Buffer length in octets.

timeout

Timeout, in milliseconds.

p_err

Pointer to the variable that will receive one of these return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ABORT
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_IS_OWNER
RTOS_ERR_INVALID_STATE
RTOS_ERR_URB_ALLOC
RTOS_ERR_INVALID_HANDLE
RTOS_ERR_SEG_OVF
RTOS_ERR_EP_INVALID
RTOS_ERR_TIMEOUT
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_TX
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF

Returned Value#

Number of octets transfered in data stage (if any).

Notes / Warnings#

None.