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#
This function is optional, if it is not called, the default value will be used.
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#
This function is optional, if it is not called, the default value will be used.
This function MUST be called before the
CDC ACM
class is initialized via theUSBD_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#
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#
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#
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.