USB Host ACM API#

USBH_ACM_ConfigureMemSeg()#

Description#

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

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

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.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the ACM class is initialized via the USBH_ACM_Init() function.

USBH_ACM_ConfigureOptimizeSpdCfg()#

Description#

Sets the configurations required when optimize speed mode is enabled.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_ConfigureOptimizeSpdCfg(const  USBH_ACM_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#

  1. This function MUST be called before the ACM class is initialized via the USBH_ACM_Init() function.

  2. This function MUST be called when the USBH_CFG_OPTIMIZE_SPD_EN configuration is set to DEF_ENABLED.

USBH_ACM_ConfigureInitAllocCfg()#

Description#

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

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_ConfigureInitAllocCfg  (const  USBH_ACM_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#

  1. This function MUST be called before the ACM class is initialized via the USBH_ACM_Init() function.

  2. This function MUST be called when the USBH_CFG_INIT_ALLOC_EN configuration is set to DEF_ENABLED.

USBH_ACM_Init()#

Description#

Initializes the Communication Device Class (CDC) Abstract Control Model (ACM) subclass driver.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void USBH_ACM_Init (USBH_ACM_APP_FNCTS   *p_acm_app_fncts,                    RTOS_ERR             *p_err)

Arguments#

p_acm_app_fncts

Pointer to the ACM application callback functions. Content MUST be persistent.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_BLK_ALLOC_CALLBACK

Returned Value#

None.

Notes / Warnings#

None.

USBH_ACM_StdReqTimeoutSet()#

Description#

Assigns a new timeout delay for the ACM standard requests.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_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#

None.

USBH_ACM_CapabilitiesGet()#

Description#

Gets the CDC ACM function capabilities.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

CPU_INT08U USBH_ACM_CapabilitiesGet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                                     RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

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_HANDLE

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

Returned Value#

Bitmap that represents the following CDC ACM features:

Notes / Warnings#

  1. This function returns a bitmap representing the features supported by the CDC ACM function. This information comes from the Call Management and Abstract Control Model functional descriptors.

USBH_ACM_EncapsulatedCmdTx()#

Description#

Sends the CDC ACM encapsulated command.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

CPU_INT16U USBH_ACM_EncapsulatedCmdTx (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                                        CPU_INT08U             *p_buf,
                                        CPU_INT16U              buf_len,
                                        CPU_INT32U              timeout,
                                        RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_buf

Pointer to the buffer that contains command.

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_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_TX

  • RTOS_ERR_WOULD_OVF

Returned Value#

Number of bytes transferred.

Notes / Warnings#

  1. For more information on SendEncapsulatedCommand, see 'USB Class Definitions for Communication Devices Specification", version 1.2, Section 6.2.1'.

USBH_ACM_EncapsulatedCmdRx()#

Description#

Receives the CDC ACM encapsulated command.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

CPU_INT16U USBH_ACM_EncapsulatedRespRx (USBH_ACM_FNCT_HANDLE acm_fnct_handle,                                         CPU_INT08U             *p_buf,                                        CPU_INT16U              buf_len,                                        CPU_INT32U              timeout,                                        RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_buf

Pointer to the buffer that will receive data.

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_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_TX

  • RTOS_ERR_WOULD_OVF

Returned Value#

Number of octets received.

Notes / Warnings#

  1. For more information on GetEncapsulatedCommand, see 'USB Class Definitions for Communication Devices Specification", version 1.2, Section 6.2.2'.

USBH_ACM_CommFeatureSet()#

Description#

Configures the CDC ACM communication feature.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void USBH_ACM_CommFeatureSet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                               CPU_INT08U              feature,
                               CPU_INT16U              data,
                               CPU_INT32U              timeout,
                               RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

feature

Feature to configure using the following:

  • USBH_CDC_COMM_FEATURE_ABSTRACT_STATE

  • USBH_CDC_COMM_FEATURE_COUNTRY_SETTING

data

Data of the communication feature request.

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on SetCommFeature request, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.1'.

USBH_ACM_CommFeatureGet()#

Description#

Gets the CDC ACM function line coding.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

CPU_INT16U USBH_ACM_CommFeatureGet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                                     CPU_INT08U              feature,
                                     CPU_INT32U              timeout,
                                     RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

feature

Feature to Get using the following:.

  • USBH_CDC_COMM_FEATURE_ABSTRACT_STATE

  • USBH_CDC_COMM_FEATURE_COUNTRY_SETTING

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

Returned Value#

Data of the Get communication feature request.

Notes / Warnings#

  1. For more information on GetCommFeature request, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.2'.

USBH_ACM_CommFeatureClr()#

Description#

Clears the CDC ACM function communication feature.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void USBH_ACM_CommFeatureClr (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                               CPU_INT08U              feature,
                               CPU_INT32U              timeout,
                               RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

feature

Feature to clear including the following:

  • USBH_CDC_COMM_FEATURE_ABSTRACT_STATE

  • USBH_CDC_COMM_FEATURE_COUNTRY_SETTING

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_TX

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on ClearCommFeature request, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.3'.

USBH_ACM_LineCodingSet()#

Description#

Sets the CDC ACM function line coding.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void USBH_ACM_LineCodingSet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                             USBH_CDC_LINECODING    *p_line_coding,
                             CPU_INT32U              timeout,
                             RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_line_coding

Pointer to the structure that contains line coding to set.

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on SetLineCoding command, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.10'.

USBH_ACM_LineCodingGet()#

Description#

Gets the CDC ACM function line coding.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void USBH_ACM_LineCodingGet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                             USBH_CDC_LINECODING    *p_line_coding,
                             CPU_INT32U              timeout,
                             RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_line_coding

Pointer to the structure that will receive line coding.

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on GetLineCoding command, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.11'.

USBH_ACM_CtrlLineStateSet()#

Description#

Sets the CDC ACM function control line state.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_CtrlLineStateSet (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                                CPU_INT16U              ctrl_signal,
                                CPU_INT32U              timeout,
                                RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

ctrl_signal

Configures the control signal using the following:

  • USBH_CDC_CTRL_LINE_STATE_CARRIER

  • USBH_CDC_CTRL_LINE_STATE_DTE

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_TX

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on SetControlLineState request, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.12'.

USBH_ACM_BrkSend()#

Description#

Sends the break signal to CDC ACM function.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_BrkSend (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                       CPU_INT16U              dur,
                       CPU_INT32U              timeout,
                       RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

dur

Duration of break.

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_NOT_SUPPORTED

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_TX

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. For more information on SendBreak request, see 'Communication Class Subclass Specification for PSTN Devices, version 1.2, Section 6.3.13'.

USBH_ACM_RxAsync()#

Description#

Receives the data from CDC ACM device. This function is asynchronous.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_RxAsync (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                       CPU_INT08U             *p_buf,
                       CPU_INT32U              buf_len,
                       USBH_ACM_ASYNC_FNCT     async_fnct,
                       void                   *p_async_arg,
                       RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_buf

Pointer to the destination buffer to receive data.

buf_len

Buffer length in octets.

async_fnct

Function that will be invoked upon completion of receive operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

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_INVALID_STATE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_URB_ALLOC

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_POOL_FULL

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

None.

USBH_ACM_TxAsync()#

Description#

Transmits the data to CDC ACM device. This function is asynchronous.

Files#

usbh_acm.h/usbh_acm.c

Prototype#

void  USBH_ACM_TxAsync (USBH_ACM_FNCT_HANDLE    acm_fnct_handle,
                       CPU_INT08U             *p_buf,
                       CPU_INT32U              buf_len,
                       USBH_ACM_ASYNC_FNCT     async_fnct,
                       void                   *p_async_arg,
                       RTOS_ERR               *p_err)

Arguments#

acm_fnct_handle

Handle on the CDC ACM function.

p_buf

Pointer to the buffer of data that will be transmitted.

buf_len

Buffer length in octets.

async_fnct

Function that will be invoked upon completion of transmit operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

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_INVALID_STATE

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_URB_ALLOC

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_POOL_FULL

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

None.