USB Device ACM API#

USBD_ACM_SerialConfigureBufAlignOctets()#

Description#

Configures the alignment of the internal buffers.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void  USBD_ACM_SerialConfigureBufAlignOctets (CPU_SIZE_T  buf_align_octets)

Arguments#

buf_align_octets

Buffer alignment, in octets.

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 CDC ACM class is initialized via the USBD_ACM_SerialInit() function.

USBD_ACM_SerialConfigureMemSeg()#

Description#

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

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void  USBD_ACM_SerialConfigureMemSeg (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#

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

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

USBD_ACM_SerialInit()#

Description#

Initializes the CDC ACM serial emulation subclass.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

`void USBD_ACM_SerialInit (CPU_INT08U   subclass_instance_qty,                           RTOS_ERR    *p_err)`

Arguments#

subclass_instance_qty

Quantity of CDC ACM subclass instances.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBD_ACM_SerialAdd()#

Description#

Adds a new instance of the CDC ACM serial emulation subclass.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_INT08U USBD_ACM_SerialAdd (CPU_INT16U    line_state_interval,
                               CPU_INT16U    call_mgmt_capabilities,
                               RTOS_ERR     *p_err)

Arguments#

line_state_interval

Line state notification interval in milliseconds (value must be a power of 2).

call_mgmt_capabilities

Call Management Capabilities bitmap. OR'ed of the following flags:

  • USBD_ACM_SERIAL_CALL_MGMT_DEV Device handles call management itself.

  • USBD_ACM_SERIAL_CALL_MGMT_DATA_CCI_DCI Device can send/receive call management information over a Data Class interface.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_ALLOC

  • RTOS_ERR_SUBCLASS_INSTANCE_ALLOC

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

Returned Value#

CDC ACM serial emulation subclass instance number.

Notes / Warnings#

None.

USBD_ACM_SerialConfigAdd()#

Description#

Adds a CDC ACM subclass class instance into USB device configuration.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_BOOLEAN USBD_ACM_SerialConfigAdd (CPU_INT08U    subclass_nbr,
                                      CPU_INT08U    dev_nbr,
                                      CPU_INT08U    config_nbr,
                                      RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

dev_nbr

Device number.

config_nbr

Configuration index to add new test class interface to.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_IF_ALT_ALLOC

  • RTOS_ERR_ALLOC

  • RTOS_ERR_IF_GRP_ALLOC

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_IF_ALLOC

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • DEF_YES, if the CDC ACM serial subclass instance was added to USB device configuration successfully.

  • DEF_NO, if the instance was not added.

Notes / Warnings#

None.

USBD_ACM_SerialIsConn()#

Description#

Gets the CDC ACM serial emulation subclass connection state.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_BOOLEAN USBD_ACM_SerialIsConn (CPU_INT08U   subclass_nbr)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

Returned Value#

  • DEF_YES, CDC ACM serial emulation is connected.

  • DEF_NO, CDC ACM serial emulation is not connected.

Notes / Warnings#

None.

USBD_ACM_SerialRx()#

Description#

Receives data on the CDC ACM serial emulation subclass.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_INT32U USBD_ACM_SerialRx (CPU_INT08U    subclass_nbr,
                              CPU_INT08U   *p_buf,
                              CPU_INT32U    buf_len,
                              CPU_INT16U    timeout,
                              RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

p_buf

Pointer to the destination buffer to receive data.

buf_len

Number of octets to receive.

timeout

Timeout, in milliseconds.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets received, if no errors are returned.

  • 0, if any errors are returned.

Notes / Warnings#

None.

USBD_ACM_SerialTx()#

Description#

Sends data on the CDC ACM serial emulation subclass.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_INT32U USBD_ACM_SerialTx (CPU_INT08U    subclass_nbr,
                              CPU_INT08U   *p_buf,
                              CPU_INT32U    buf_len,
                              CPU_INT16U    timeout,
                              RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

p_buf

Pointer to the buffer of data that will be transmitted.

buf_len

Number of octets to transmit.

timeout

Timeout in milliseconds.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets transmitted, if no errors are returned.

  • 0, if any errors are returned.

Notes / Warnings#

None.

USBD_ACM_SerialLineCtrlGet()#

Description#

Returns the state of control lines.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

CPU_INT08U USBD_ACM_SerialLineCtrlGet (CPU_INT08U    subclass_nbr,
                                       RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

Bit-field with the state of the control line.

  • USBD_ACM_SERIAL_CTRL_BREAK

  • USBD_ACM_SERIAL_CTRL_RTS

  • USBD_ACM_SERIAL_CTRL_DTR

Notes / Warnings#

None.

USBD_ACM_SerialLineCtrlReg()#

Description#

Sets the line control change notification callback.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineCtrlReg (CPU_INT08U                         subclass_nbr,
                                 USBD_ACM_SERIAL_LINE_CTRL_CHNGD    line_ctrl_chngd,
                                 void                              *p_arg,
                                 RTOS_ERR                          *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

line_ctrl_chngd

Line control change notification callback (see Note #1).

p_arg

Pointer to the callback argument.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

ACM serial emulation subclass device number.

Notes / Warnings#

  1. The callback specified by 'line_ctrl_chngd' argument notifies of changes in the control signals to the application.

The line control notification function uses the following prototype:

void   AppLineCtrlChngd   (CPU_INT08U  subclass_nbr,
                           CPU_INT08U  events,
                           CPU_INT08U  events_chngd,
                           void        *p_arg);

       Argument(s) : subclass_nbr      CDC ACM serial emulation subclass instance number.

                     events            Current line state. The line state is a OR'ed of the following flags:

                                           USBD_ACM_SERIAL_CTRL_BREAK
                                           USBD_ACM_SERIAL_CTRL_RTS
                                           USBD_ACM_SERIAL_CTRL_DTR

                     events_chngd      Line state flags that have changed.

                     p_arg             Pointer to callback argument.

USBD_ACM_SerialLineCodingGet()#

Description#

Gets the current state of the line coding.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineCodingGet (CPU_INT08U                     subclass_nbr,
                                   USBD_ACM_SERIAL_LINE_CODING   *p_line_coding,
                                   RTOS_ERR                      *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

p_line_coding

Pointer to the structure where the current line coding will be stored.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

USBD_ACM_SerialLineCodingSet()#

Description#

Sets a new line coding.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineCodingSet (CPU_INT08U                     subclass_nbr,
                                   USBD_ACM_SERIAL_LINE_CODING   *p_line_coding,
                                   RTOS_ERR                      *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

p_line_coding

Pointer to the structure that contains the new line coding.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

None.

USBD_ACM_SerialLineCodingReg()#

Description#

Sets the line coding change notification callback.

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineCodingReg (CPU_INT08U                           subclass_nbr,
                                   USBD_ACM_SERIAL_LINE_CODING_CHNGD    line_coding_chngd,
                                   void                                *p_arg,
                                   RTOS_ERR                            *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

line_coding_chngd

Line coding change notification callback (see Note #1).

p_arg

Pointer to the callback argument.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. This callback notifies of changes in the line coding to the application.

    The line coding change notification function has the following prototype:

    CPU_BOOLEAN   AppLineCodingChngd   (CPU_INT08U                    subclass_nbr,
                                        USBD_ACM_SERIAL_LINE_CODING   *p_line_coding,
                                        void                          *p_arg);

    Argument(s) : subclass_nbr          CDC ACM serial emulation subclass instance number.

                p_line_coding Pointer to the line coding structure.

                p_arg Pointer to the callback argument.

Return(s) :       DEF_OK, if line coding is supported by the application.

                DEF_FAIL, if line coding is NOT supported by the application.

USBD_ACM_SerialLineStateSet()#

Description#

Sets a line state event(s).

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineStateSet (CPU_INT08U    subclass_nbr,
                                  CPU_INT08U    events,
                                  RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

events

Line state event(s) to set. OR'ed of the following flags:

  • USBD_ACM_SERIAL_STATE_DCD

  • USBD_ACM_SERIAL_STATE_DSR

  • USBD_ACM_SERIAL_STATE_BREAK

  • USBD_ACM_SERIAL_STATE_RING

  • USBD_ACM_SERIAL_STATE_FRAMING

  • USBD_ACM_SERIAL_STATE_PARITY

  • USBD_ACM_SERIAL_STATE_OVERUN

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

USBD_ACM_SerialLineStateClr()#

Description#

Clears a line state event(s).

Files#

usbd_cdc_acm_serial.h/usbd_cdc_acm_serial.c

Prototype#

void USBD_ACM_SerialLineStateClr (CPU_INT08U    subclass_nbr,
                                  CPU_INT08U    events,
                                  RTOS_ERR     *p_err)

Arguments#

subclass_nbr

CDC ACM serial emulation subclass instance number.

events

Line state event(s) set to be cleared. OR'ed of the following flags (see Note #1) :

  • USBD_ACM_SERIAL_STATE_DCD Set DCD signal (Rx carrier).

  • USBD_ACM_SERIAL_STATE_DSR Set DSR signal (Tx carrier).

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. USB PSTN spec ver 1.20 states: "For the irregular signals like break, the incoming ring signal, or the overrun error state, this will reset their values to zero and again will not send another notification until their state changes."

The irregular events are automatically cleared by the ACM serial emulation subclass.