ChibiOS/RT
2.6.3
Serial over USB Driver
Collaboration diagram for Serial over USB Driver:

Detailed Description

Serial over USB Driver.

This module implements an USB Communication Device Class (CDC) as a normal serial communication port accessible from the device application.

Precondition:
In order to use the USB over Serial driver the HAL_USE_SERIAL_USB option must be enabled in halconf.h.

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

dot_inline_dotgraph_15.png

Data Structures

struct  cdc_linecoding_t
 Type of Line Coding structure. More...
struct  SerialUSBConfig
 Serial over USB Driver configuration structure. More...
struct  SerialUSBDriverVMT
 SerialDriver virtual methods table. More...
struct  SerialUSBDriver
 Full duplex serial driver class. More...

Functions

void sduInit (void)
 Serial Driver initialization.
void sduObjectInit (SerialUSBDriver *sdup)
 Initializes a generic full duplex driver object.
void sduStart (SerialUSBDriver *sdup, const SerialUSBConfig *config)
 Configures and starts the driver.
void sduStop (SerialUSBDriver *sdup)
 Stops the driver.
void sduConfigureHookI (SerialUSBDriver *sdup)
 USB device configured handler.
bool_t sduRequestsHook (USBDriver *usbp)
 Default requests hook.
void sduDataTransmitted (USBDriver *usbp, usbep_t ep)
 Default data transmitted callback.
void sduDataReceived (USBDriver *usbp, usbep_t ep)
 Default data received callback.
void sduInterruptTransmitted (USBDriver *usbp, usbep_t ep)
 Default data received callback.

CDC specific messages.

#define CDC_SEND_ENCAPSULATED_COMMAND   0x00
#define CDC_GET_ENCAPSULATED_RESPONSE   0x01
#define CDC_SET_COMM_FEATURE   0x02
#define CDC_GET_COMM_FEATURE   0x03
#define CDC_CLEAR_COMM_FEATURE   0x04
#define CDC_SET_AUX_LINE_STATE   0x10
#define CDC_SET_HOOK_STATE   0x11
#define CDC_PULSE_SETUP   0x12
#define CDC_SEND_PULSE   0x13
#define CDC_SET_PULSE_TIME   0x14
#define CDC_RING_AUX_JACK   0x15
#define CDC_SET_LINE_CODING   0x20
#define CDC_GET_LINE_CODING   0x21
#define CDC_SET_CONTROL_LINE_STATE   0x22
#define CDC_SEND_BREAK   0x23
#define CDC_SET_RINGER_PARMS   0x30
#define CDC_GET_RINGER_PARMS   0x31
#define CDC_SET_OPERATION_PARMS   0x32
#define CDC_GET_OPERATION_PARMS   0x33

Line Control bit definitions.

#define LC_STOP_1   0
#define LC_STOP_1P5   1
#define LC_STOP_2   2
#define LC_PARITY_NONE   0
#define LC_PARITY_ODD   1
#define LC_PARITY_EVEN   2
#define LC_PARITY_MARK   3
#define LC_PARITY_SPACE   4

SERIAL_USB configuration options

#define SERIAL_USB_BUFFERS_SIZE   256
 Serial over USB buffers size.

Defines

#define _serial_usb_driver_data
 SerialDriver specific data.
#define _serial_usb_driver_methods   _base_asynchronous_channel_methods
 SerialUSBDriver specific methods.

Typedefs

typedef struct SerialUSBDriver SerialUSBDriver
 Structure representing a serial over USB driver.

Enumerations

enum  sdustate_t { SDU_UNINIT = 0, SDU_STOP = 1, SDU_READY = 2 }
 Driver state machine possible states. More...

Function Documentation

void sduInit ( void  )

Serial Driver initialization.

Note:
This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 186 of file serial_usb.c.

Referenced by halInit().

void sduObjectInit ( SerialUSBDriver sdup)

Initializes a generic full duplex driver object.

The HW dependent part of the initialization has to be performed outside, usually in the hardware initialization code.

Parameters:
[out]sduppointer to a SerialUSBDriver structure
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 198 of file serial_usb.c.

References chEvtInit, chIQInit(), chOQInit(), SDU_STOP, SERIAL_USB_BUFFERS_SIZE, and SerialUSBDriver::vmt.

Here is the call graph for this function:

void sduStart ( SerialUSBDriver sdup,
const SerialUSBConfig config 
)

Configures and starts the driver.

Parameters:
[in]sduppointer to a SerialUSBDriver object
[in]configthe serial over USB driver configuration
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 215 of file serial_usb.c.

References SerialUSBConfig::bulk_in, SerialUSBConfig::bulk_out, chDbgAssert, chDbgCheck, chSysLock, chSysUnlock, USBDriver::in_params, SerialUSBConfig::int_in, USBDriver::out_params, SDU_READY, SDU_STOP, and SerialUSBConfig::usbp.

void sduStop ( SerialUSBDriver sdup)

Stops the driver.

Any thread waiting on the driver's queues will be awakened with the message Q_RESET.

Parameters:
[in]sduppointer to a SerialUSBDriver object
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 241 of file serial_usb.c.

References chDbgAssert, chDbgCheck, chIQResetI(), CHN_DISCONNECTED, chnAddFlagsI, chOQResetI(), chSchRescheduleS(), chSysLock, chSysUnlock, USBDriver::in_params, USBDriver::out_params, SDU_READY, and SDU_STOP.

Here is the call graph for this function:

void sduConfigureHookI ( SerialUSBDriver sdup)

USB device configured handler.

Parameters:
[in]sduppointer to a SerialUSBDriver object
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 274 of file serial_usb.c.

References chIQResetI(), CHN_CONNECTED, chnAddFlagsI, chOQResetI(), USBDriver::epc, USBEndpointConfig::out_maxsize, usbPrepareQueuedReceive(), and usbStartReceiveI().

Here is the call graph for this function:

bool_t sduRequestsHook ( USBDriver usbp)

Default requests hook.

Applications wanting to use the Serial over USB driver can use this function as requests hook in the USB configuration. The following requests are emulated:

  • CDC_GET_LINE_CODING.
  • CDC_SET_LINE_CODING.
  • CDC_SET_CONTROL_LINE_STATE.
Parameters:
[in]usbppointer to the USBDriver object
Returns:
The hook status.
Return values:
TRUEMessage handled internally.
FALSEMessage not handled.

Definition at line 302 of file serial_usb.c.

References FALSE, USBDriver::setup, TRUE, and usbSetupTransfer.

void sduDataTransmitted ( USBDriver usbp,
usbep_t  ep 
)

Default data transmitted callback.

The application must use this function as callback for the IN data endpoint.

Parameters:
[in]usbppointer to the USBDriver object
[in]ependpoint number

Definition at line 331 of file serial_usb.c.

References CHN_OUTPUT_EMPTY, chnAddFlagsI, chOQGetFullI, chSysLockFromIsr, chSysUnlockFromIsr, USBDriver::epc, USBEndpointConfig::in_maxsize, USBDriver::in_params, USBEndpointConfig::in_state, USBInEndpointState::txsize, usbPrepareQueuedTransmit(), and usbStartTransmitI().

Here is the call graph for this function:

void sduDataReceived ( USBDriver usbp,
usbep_t  ep 
)

Default data received callback.

The application must use this function as callback for the OUT data endpoint.

Parameters:
[in]usbppointer to the USBDriver object
[in]ependpoint number

Definition at line 377 of file serial_usb.c.

References chIQGetEmptyI, CHN_INPUT_AVAILABLE, chnAddFlagsI, chSysLockFromIsr, chSysUnlockFromIsr, USBDriver::epc, USBEndpointConfig::out_maxsize, USBDriver::out_params, usbPrepareQueuedReceive(), and usbStartReceiveI().

Here is the call graph for this function:

void sduInterruptTransmitted ( USBDriver usbp,
usbep_t  ep 
)

Default data received callback.

The application must use this function as callback for the IN interrupt endpoint.

Parameters:
[in]usbppointer to the USBDriver object
[in]ependpoint number

Definition at line 413 of file serial_usb.c.


Define Documentation

#define SERIAL_USB_BUFFERS_SIZE   256

Serial over USB buffers size.

Configuration parameter, the buffer size must be a multiple of the USB data endpoint maximum packet size.

Note:
The default is 256 bytes for both the transmission and receive buffers.

Definition at line 101 of file serial_usb.h.

Referenced by sduObjectInit().

#define _serial_usb_driver_data
Value:
_base_asynchronous_channel_data                                           \
  /* Driver state.*/                                                        \
  sdustate_t                state;                                          \
  /* Input queue.*/                                                         \
  InputQueue                iqueue;                                         \
  /* Output queue.*/                                                        \
  OutputQueue               oqueue;                                         \
  /* Input buffer.*/                                                        \
  uint8_t                   ib[SERIAL_USB_BUFFERS_SIZE];                    \
  /* Output buffer.*/                                                       \
  uint8_t                   ob[SERIAL_USB_BUFFERS_SIZE];                    \
  /* End of the mandatory fields.*/                                         \
  /* Current configuration data.*/                                          \
  const SerialUSBConfig     *config;

SerialDriver specific data.

Definition at line 169 of file serial_usb.h.

#define _serial_usb_driver_methods   _base_asynchronous_channel_methods

SerialUSBDriver specific methods.

Definition at line 188 of file serial_usb.h.


Typedef Documentation

Structure representing a serial over USB driver.

Definition at line 140 of file serial_usb.h.


Enumeration Type Documentation

enum sdustate_t

Driver state machine possible states.

Enumerator:
SDU_UNINIT 

Not initialized.

SDU_STOP 

Stopped.

SDU_READY 

Ready.

Definition at line 131 of file serial_usb.h.