USB Device Interface (UDI) for Communication Class Device (CDC)

USB Device Interface (UDI) for Communication Class Device (CDC) provides an interface for the configuration and management of USB CDC serial device.

The outline of this documentation is as follows:

• API Overview
• Quick Start Guide for USB Device Communication Class Device Module (UDI CDC)
• Configuration File Examples

For more details for Atmel® Software Framework (ASF) USB Device Stack and USB Device CDC, refer to following application notes:

• AVR4900: ASF - USB Device Stack
• AVR4907: ASF - USB Device CDC Application
• AVR4920: ASF - USB Device Stack - Compliance and Performance Figures
• AVR4921: ASF - USB Device Stack Differences between ASF V1 and V2

API Overview

Data Structures
struct	udi_cdc_comm_desc_t
	Communication Class interface descriptor. More...
struct	udi_cdc_data_desc_t
	Data Class interface descriptor. More...

Macros
#define	UDI_CDC_COMM_DESC(port)
	Content of CDC COMM interface descriptor for all speeds. More...
#define	UDI_CDC_COMM_EP_SIZE   64
	CDC communication endpoints size for all speeds. More...
#define	UDI_CDC_DATA_DESC_COMMON
	Content of CDC DATA interface descriptors. More...
#define	UDI_CDC_DATA_DESC_FS(port)
	Content of CDC DATA interface descriptors for FS. More...
#define	UDI_CDC_DATA_DESC_HS(port)
	Content of CDC DATA interface descriptors for HS. More...
#define	UDI_CDC_DATA_EPS_FS_SIZE   64
	CDC data endpoints size for FS speed (8B, 16B, 32B, 64B). More...
#define	UDI_CDC_DATA_EPS_HS_SIZE   512
	CDC data endpoints size for HS speed (512B only). More...
#define	UDI_CDC_IAD_DESC(port)
	Content of CDC IAD interface descriptor for all speeds. More...

Content of Interface Descriptors
Up to seven CDC interfaces can be implemented on a USB device.
#define	UDI_CDC_IAD_STRING_ID_0   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_0   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_0   0
	No string associated to DATA interface. More...
#define	UDI_CDC_IAD_DESC_0   UDI_CDC_IAD_DESC(0)
	IAD descriptor for port 0. More...
#define	UDI_CDC_COMM_DESC_0   UDI_CDC_COMM_DESC(0)
	COMM descriptors for port 0. More...
#define	UDI_CDC_DATA_DESC_0_FS   UDI_CDC_DATA_DESC_FS(0)
	DATA descriptor for port 0 of a full speed device. More...
#define	UDI_CDC_DATA_DESC_0_HS   UDI_CDC_DATA_DESC_HS(0)
	DATA descriptor for port 0 of a high speed device. More...
#define	UDI_CDC_IAD_STRING_ID_1   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_1   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_1   0
#define	UDI_CDC_IAD_DESC_1   UDI_CDC_IAD_DESC(1)
#define	UDI_CDC_COMM_DESC_1   UDI_CDC_COMM_DESC(1)
#define	UDI_CDC_DATA_DESC_1_FS   UDI_CDC_DATA_DESC_FS(1)
#define	UDI_CDC_DATA_DESC_1_HS   UDI_CDC_DATA_DESC_HS(1)
#define	UDI_CDC_IAD_STRING_ID_2   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_2   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_2   0
#define	UDI_CDC_IAD_DESC_2   UDI_CDC_IAD_DESC(2)
#define	UDI_CDC_COMM_DESC_2   UDI_CDC_COMM_DESC(2)
#define	UDI_CDC_DATA_DESC_2_FS   UDI_CDC_DATA_DESC_FS(2)
#define	UDI_CDC_DATA_DESC_2_HS   UDI_CDC_DATA_DESC_HS(2)
#define	UDI_CDC_IAD_STRING_ID_3   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_3   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_3   0
#define	UDI_CDC_IAD_DESC_3   UDI_CDC_IAD_DESC(3)
#define	UDI_CDC_COMM_DESC_3   UDI_CDC_COMM_DESC(3)
#define	UDI_CDC_DATA_DESC_3_FS   UDI_CDC_DATA_DESC_FS(3)
#define	UDI_CDC_DATA_DESC_3_HS   UDI_CDC_DATA_DESC_HS(3)
#define	UDI_CDC_IAD_STRING_ID_4   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_4   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_4   0
#define	UDI_CDC_IAD_DESC_4   UDI_CDC_IAD_DESC(4)
#define	UDI_CDC_COMM_DESC_4   UDI_CDC_COMM_DESC(4)
#define	UDI_CDC_DATA_DESC_4_FS   UDI_CDC_DATA_DESC_FS(4)
#define	UDI_CDC_DATA_DESC_4_HS   UDI_CDC_DATA_DESC_HS(4)
#define	UDI_CDC_IAD_STRING_ID_5   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_5   0
	No string associated to COMM interface. More...
#define	UDI_CDC_DATA_STRING_ID_5   0
#define	UDI_CDC_IAD_DESC_5   UDI_CDC_IAD_DESC(5)
#define	UDI_CDC_COMM_DESC_5   UDI_CDC_COMM_DESC(5)
#define	UDI_CDC_DATA_DESC_5_FS   UDI_CDC_DATA_DESC_FS(5)
#define	UDI_CDC_DATA_DESC_5_HS   UDI_CDC_DATA_DESC_HS(5)
#define	UDI_CDC_IAD_STRING_ID_6   0
	By default no string associated to these interfaces. More...
#define	UDI_CDC_COMM_STRING_ID_6   0
#define	UDI_CDC_DATA_STRING_ID_6   0
#define	UDI_CDC_IAD_DESC_6   UDI_CDC_IAD_DESC(6)
#define	UDI_CDC_COMM_DESC_6   UDI_CDC_COMM_DESC(6)
#define	UDI_CDC_DATA_DESC_6_FS   UDI_CDC_DATA_DESC_FS(6)
#define	UDI_CDC_DATA_DESC_6_HS   UDI_CDC_DATA_DESC_HS(6)

Interface for Application with Single CDC Interface Support
void	udi_cdc_ctrl_signal_dcd (bool b_set)
	Notify a state change of Data Carrier Detect (DCD) signal. More...
void	udi_cdc_ctrl_signal_dsr (bool b_set)
	Notify a state change of Data Set Ready (DSR) signal. More...
void	udi_cdc_signal_framing_error (void)
	Notify a framing error. More...
void	udi_cdc_signal_parity_error (void)
	Notify a parity error. More...
void	udi_cdc_signal_overrun (void)
	Notify a overrun. More...
iram_size_t	udi_cdc_get_nb_received_data (void)
	Gets the number of byte received. More...
bool	udi_cdc_is_rx_ready (void)
	This function checks if a character has been received on the CDC line. More...
int	udi_cdc_getc (void)
	Waits and gets a value on CDC line. More...
iram_size_t	udi_cdc_read_buf (void *buf, iram_size_t size)
	Reads a RAM buffer on CDC line. More...
iram_size_t	udi_cdc_get_free_tx_buffer (void)
	Gets the number of free byte in TX buffer. More...
bool	udi_cdc_is_tx_ready (void)
	This function checks if a new character sent is possible. More...
int	udi_cdc_putc (int value)
	Puts a byte on CDC line. More...
iram_size_t	udi_cdc_write_buf (const void *buf, iram_size_t size)
	Writes a RAM buffer on CDC line. More...

Interface for Application with Multi CDC Interfaces Support
void	udi_cdc_multi_ctrl_signal_dcd (uint8_t port, bool b_set)
	Notify a state change of DCD signal. More...
void	udi_cdc_multi_ctrl_signal_dsr (uint8_t port, bool b_set)
	Notify a state change of DSR signal. More...
void	udi_cdc_multi_signal_framing_error (uint8_t port)
	Notify a framing error. More...
void	udi_cdc_multi_signal_parity_error (uint8_t port)
	Notify a parity error. More...
void	udi_cdc_multi_signal_overrun (uint8_t port)
	Notify a overrun. More...
iram_size_t	udi_cdc_multi_get_nb_received_data (uint8_t port)
	Gets the number of byte received. More...
bool	udi_cdc_multi_is_rx_ready (uint8_t port)
	This function checks if a character has been received on the CDC line. More...
int	udi_cdc_multi_getc (uint8_t port)
	Waits and gets a value on CDC line. More...
iram_size_t	udi_cdc_multi_read_buf (uint8_t port, void *buf, iram_size_t size)
	Reads a RAM buffer on CDC line. More...
iram_size_t	udi_cdc_multi_get_free_tx_buffer (uint8_t port)
	Gets the number of free byte in TX buffer. More...
bool	udi_cdc_multi_is_tx_ready (uint8_t port)
	This function checks if a new character sent is possible. More...
int	udi_cdc_multi_putc (uint8_t port, int value)
	Puts a byte on CDC line, and the type int is used to support printf redirection from compiler LIB. More...
iram_size_t	udi_cdc_multi_write_buf (uint8_t port, const void *buf, iram_size_t size)
	Writes a RAM buffer on CDC line. More...

#define UDI_CDC_COMM_DESC

(

port

)

Content of CDC COMM interface descriptor for all speeds.

#define UDI_CDC_COMM_DESC_0   UDI_CDC_COMM_DESC(0)

COMM descriptors for port 0.

#define UDI_CDC_COMM_DESC_1   UDI_CDC_COMM_DESC(1)

#define UDI_CDC_COMM_DESC_2   UDI_CDC_COMM_DESC(2)

#define UDI_CDC_COMM_DESC_3   UDI_CDC_COMM_DESC(3)

#define UDI_CDC_COMM_DESC_4   UDI_CDC_COMM_DESC(4)

#define UDI_CDC_COMM_DESC_5   UDI_CDC_COMM_DESC(5)

#define UDI_CDC_COMM_DESC_6   UDI_CDC_COMM_DESC(6)

#define UDI_CDC_COMM_EP_SIZE   64

CDC communication endpoints size for all speeds.

#define UDI_CDC_COMM_STRING_ID_0   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_1   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_2   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_3   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_4   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_5   0

No string associated to COMM interface.

#define UDI_CDC_COMM_STRING_ID_6   0

#define UDI_CDC_DATA_DESC_0_FS   UDI_CDC_DATA_DESC_FS(0)

DATA descriptor for port 0 of a full speed device.

#define UDI_CDC_DATA_DESC_0_HS   UDI_CDC_DATA_DESC_HS(0)

DATA descriptor for port 0 of a high speed device.

#define UDI_CDC_DATA_DESC_1_FS   UDI_CDC_DATA_DESC_FS(1)

#define UDI_CDC_DATA_DESC_1_HS   UDI_CDC_DATA_DESC_HS(1)

#define UDI_CDC_DATA_DESC_2_FS   UDI_CDC_DATA_DESC_FS(2)

#define UDI_CDC_DATA_DESC_2_HS   UDI_CDC_DATA_DESC_HS(2)

#define UDI_CDC_DATA_DESC_3_FS   UDI_CDC_DATA_DESC_FS(3)

#define UDI_CDC_DATA_DESC_3_HS   UDI_CDC_DATA_DESC_HS(3)

#define UDI_CDC_DATA_DESC_4_FS   UDI_CDC_DATA_DESC_FS(4)

#define UDI_CDC_DATA_DESC_4_HS   UDI_CDC_DATA_DESC_HS(4)

#define UDI_CDC_DATA_DESC_5_FS   UDI_CDC_DATA_DESC_FS(5)

#define UDI_CDC_DATA_DESC_5_HS   UDI_CDC_DATA_DESC_HS(5)

#define UDI_CDC_DATA_DESC_6_FS   UDI_CDC_DATA_DESC_FS(6)

#define UDI_CDC_DATA_DESC_6_HS   UDI_CDC_DATA_DESC_HS(6)

#define UDI_CDC_DATA_DESC_COMMON

Value:

.iface.bLength                = sizeof(usb_iface_desc_t),\
   .iface.bDescriptorType        = USB_DT_INTERFACE,\
   .iface.bAlternateSetting      = 0,\
   .iface.bNumEndpoints          = 2,\
   .iface.bInterfaceClass        = CDC_CLASS_DATA,\
   .iface.bInterfaceSubClass     = 0,\
   .iface.bInterfaceProtocol     = 0,\
   .ep_in.bLength                = sizeof(usb_ep_desc_t),\
   .ep_in.bDescriptorType        = USB_DT_ENDPOINT,\
   .ep_in.bmAttributes           = USB_EP_TYPE_BULK,\
   .ep_in.bInterval              = 0,\
   .ep_out.bLength               = sizeof(usb_ep_desc_t),\
   .ep_out.bDescriptorType       = USB_DT_ENDPOINT,\
   .ep_out.bmAttributes          = USB_EP_TYPE_BULK,\
   .ep_out.bInterval             = 0,

Content of CDC DATA interface descriptors.

#define UDI_CDC_DATA_DESC_FS

(

port

)

Value:

{ \
   UDI_CDC_DATA_DESC_COMMON \
   .ep_in.wMaxPacketSize         = LE16(UDI_CDC_DATA_EPS_FS_SIZE),\
   .ep_out.wMaxPacketSize        = LE16(UDI_CDC_DATA_EPS_FS_SIZE),\
   .ep_in.bEndpointAddress       = UDI_CDC_DATA_EP_IN_##port,\
   .ep_out.bEndpointAddress      = UDI_CDC_DATA_EP_OUT_##port,\
   .iface.bInterfaceNumber       = UDI_CDC_DATA_IFACE_NUMBER_##port,\
   .iface.iInterface             = UDI_CDC_DATA_STRING_ID_##port,\
   }

Content of CDC DATA interface descriptors for FS.

#define UDI_CDC_DATA_DESC_HS

(

port

)

Value:

{ \
   UDI_CDC_DATA_DESC_COMMON \
   .ep_in.wMaxPacketSize         = LE16(UDI_CDC_DATA_EPS_HS_SIZE),\
   .ep_out.wMaxPacketSize        = LE16(UDI_CDC_DATA_EPS_HS_SIZE),\
   .ep_in.bEndpointAddress       = UDI_CDC_DATA_EP_IN_##port,\
   .ep_out.bEndpointAddress      = UDI_CDC_DATA_EP_OUT_##port,\
   .iface.bInterfaceNumber       = UDI_CDC_DATA_IFACE_NUMBER_##port,\
   .iface.iInterface             = UDI_CDC_DATA_STRING_ID_##port,\
   }

Content of CDC DATA interface descriptors for HS.

#define UDI_CDC_DATA_EPS_FS_SIZE   64

CDC data endpoints size for FS speed (8B, 16B, 32B, 64B).

#define UDI_CDC_DATA_EPS_HS_SIZE   512

CDC data endpoints size for HS speed (512B only).

#define UDI_CDC_DATA_STRING_ID_0   0

No string associated to DATA interface.

#define UDI_CDC_DATA_STRING_ID_1   0

#define UDI_CDC_DATA_STRING_ID_2   0

#define UDI_CDC_DATA_STRING_ID_3   0

#define UDI_CDC_DATA_STRING_ID_4   0

#define UDI_CDC_DATA_STRING_ID_5   0

#define UDI_CDC_DATA_STRING_ID_6   0

#define UDI_CDC_IAD_DESC

(

port

)

Value:

{ \
   .bLength                      = sizeof(usb_iad_desc_t),\
   .bDescriptorType              = USB_DT_IAD,\
   .bInterfaceCount              = 2,\
   .bFunctionClass               = CDC_CLASS_COMM,\
   .bFunctionSubClass            = CDC_SUBCLASS_ACM,\
   .bFunctionProtocol            = CDC_PROTOCOL_V25TER,\
   .bFirstInterface              = UDI_CDC_COMM_IFACE_NUMBER_##port,\
   .iFunction                    = UDI_CDC_IAD_STRING_ID_##port,\
   }

Content of CDC IAD interface descriptor for all speeds.

#define UDI_CDC_IAD_DESC_0   UDI_CDC_IAD_DESC(0)

IAD descriptor for port 0.

#define UDI_CDC_IAD_DESC_1   UDI_CDC_IAD_DESC(1)

#define UDI_CDC_IAD_DESC_2   UDI_CDC_IAD_DESC(2)

#define UDI_CDC_IAD_DESC_3   UDI_CDC_IAD_DESC(3)

#define UDI_CDC_IAD_DESC_4   UDI_CDC_IAD_DESC(4)

#define UDI_CDC_IAD_DESC_5   UDI_CDC_IAD_DESC(5)

#define UDI_CDC_IAD_DESC_6   UDI_CDC_IAD_DESC(6)

#define UDI_CDC_IAD_STRING_ID_0   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_1   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_2   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_3   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_4   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_5   0

By default no string associated to these interfaces.

No string associated to IAD interface.

#define UDI_CDC_IAD_STRING_ID_6   0

By default no string associated to these interfaces.

No string associated to IAD interface.

void udi_cdc_ctrl_signal_dcd

(

bool

b_set

)

Notify a state change of Data Carrier Detect (DCD) signal.

Parameters

[in]

b_set

DCD is enabled if true, else disabled

void udi_cdc_ctrl_signal_dsr

(

bool

b_set

)

Notify a state change of Data Set Ready (DSR) signal.

Parameters

[in]

b_set

DSR is enabled if true, else disabled

iram_size_t udi_cdc_get_free_tx_buffer

(

void

)

Gets the number of free byte in TX buffer.

Returns

The number of free byte in TX buffer.

iram_size_t udi_cdc_get_nb_received_data

(

void

)

Gets the number of byte received.

Returns

The number of data available.

int udi_cdc_getc

(

void

)

Waits and gets a value on CDC line.

Returns

Value read on CDC line.

bool udi_cdc_is_rx_ready

(

void

)

This function checks if a character has been received on the CDC line.

Returns

1 if a byte is ready to be read.

bool udi_cdc_is_tx_ready

(

void

)

This function checks if a new character sent is possible.

The type int is used to support scanf redirection from compiler .lib file.

Returns

1 if a new character can be sent.

void udi_cdc_multi_ctrl_signal_dcd	(	uint8_t	port,
		bool	b_set
	)

Notify a state change of DCD signal.

Parameters

[in]	port	Communication port number to manage
[in]	b_set	DCD is enabled if true, else disabled

void udi_cdc_multi_ctrl_signal_dsr	(	uint8_t	port,
		bool	b_set
	)

Notify a state change of DSR signal.

Parameters

[in]	port	Communication port number to manage
[in]	b_set	DSR is enabled if true, else disabled

iram_size_t udi_cdc_multi_get_free_tx_buffer

(

uint8_t

port

)

Gets the number of free byte in TX buffer.

Parameters

[in]

port

Communication port number to manage

Returns

The number of free byte in TX buffer.

iram_size_t udi_cdc_multi_get_nb_received_data

(

uint8_t

port

)

Gets the number of byte received.

Parameters

[in]

port

Communication port number to manage

Returns

The number of data available.

int udi_cdc_multi_getc

(

uint8_t

port

)

Waits and gets a value on CDC line.

Parameters

[in]

port

Communication port number to manage

Returns

Value read on CDC line.

bool udi_cdc_multi_is_rx_ready

(

uint8_t

port

)

This function checks if a character has been received on the CDC line.

Parameters

[in]

port

Communication port number to manage

Returns

1 if a byte is ready to be read.

bool udi_cdc_multi_is_tx_ready

(

uint8_t

port

)

This function checks if a new character sent is possible.

The type int is used to support scanf redirection from compiler LIB.

Parameters

[in]

port

Communication port number to manage

Returns

1 if a new character can be sent.

int udi_cdc_multi_putc	(	uint8_t	port,
		int	value
	)

Puts a byte on CDC line, and the type int is used to support printf redirection from compiler LIB.

Parameters

[in]	port	Communication port number to manage
[in]	value	Value to put

Returns

1 if function was successfully done, otherwise 0.

iram_size_t udi_cdc_multi_read_buf	(	uint8_t	port,
		void *	buf,
		iram_size_t	size
	)

Reads a RAM buffer on CDC line.

Parameters

[in]	port	Communication port number to manage
[out]	buf	Values read
[in]	size	Number of values read

Returns

The number of data remaining.

void udi_cdc_multi_signal_framing_error

(

uint8_t

port

)

Notify a framing error.

Parameters

[in]

port

Communication port number to manage

void udi_cdc_multi_signal_overrun

(

uint8_t

port

)

Notify a overrun.

Parameters

[in]

port

Communication port number to manage

void udi_cdc_multi_signal_parity_error

(

uint8_t

port

)

Notify a parity error.

Parameters

[in]

port

Communication port number to manage

iram_size_t udi_cdc_multi_write_buf	(	uint8_t	port,
		const void *	buf,
		iram_size_t	size
	)

Writes a RAM buffer on CDC line.

Parameters

[in]	port	Communication port number to manage
[in]	buf	Values to write
[in]	size	Number of value to write

Returns

The number of data remaining.

int udi_cdc_putc

(

int

value

)

Puts a byte on CDC line.

The type int is used to support printf redirection from compiler LIB.

Parameters

[in]

value

Value to put

Returns

1 if function was successfully done, otherwise 0.

iram_size_t udi_cdc_read_buf	(	void *	buf,
		iram_size_t	size
	)

Reads a RAM buffer on CDC line.

Parameters

[out]	buf	Values read
[in]	size	Number of value read

Returns

The number of data remaining.

void udi_cdc_signal_framing_error

(

void

)

Notify a framing error.

void udi_cdc_signal_overrun

(

void

)

Notify a overrun.

void udi_cdc_signal_parity_error

(

void

)

Notify a parity error.

iram_size_t udi_cdc_write_buf	(	const void *	buf,
		iram_size_t	size
	)

Writes a RAM buffer on CDC line.

Parameters

[in]	buf	Values to write
[in]	size	Number of value to write

Returns

The number of data remaining.