Serial over USB Driver

Serial over USB Driver. More...

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).

Collaboration diagram for Serial over USB Driver:

SERIAL_USB configuration options
#define	SERIAL_USB_BUFFERS_SIZE   256
	Serial over USB buffers size.
#define	SERIAL_USB_BUFFERS_NUMBER   2
	Serial over USB number of buffers.

Data Structures
struct	SerialUSBConfig
	Serial over USB Driver configuration structure. More...
struct	SerialUSBDriverVMT
	SerialDriver virtual methods table. More...
struct	SerialUSBDriver
	Full duplex serial driver class. More...

Macros
#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...

Functions
static bool	sdu_start_receive (SerialUSBDriver *sdup)
static size_t	_write (void *ip, const uint8_t *bp, size_t n)
static size_t	_read (void *ip, uint8_t *bp, size_t n)
static msg_t	_put (void *ip, uint8_t b)
static msg_t	_get (void *ip)
static msg_t	_putt (void *ip, uint8_t b, sysinterval_t timeout)
static msg_t	_gett (void *ip, sysinterval_t timeout)
static size_t	_writet (void *ip, const uint8_t *bp, size_t n, sysinterval_t timeout)
static size_t	_readt (void *ip, uint8_t *bp, size_t n, sysinterval_t timeout)
static msg_t	_ctl (void *ip, unsigned int operation, void *arg)
static void	ibnotify (io_buffers_queue_t *bqp)
	Notification of empty buffer released into the input buffers queue.
static void	obnotify (io_buffers_queue_t *bqp)
	Notification of filled buffer inserted into the output buffers queue.
void	sduInit (void)
	Serial Driver initialization.
void	sduObjectInit (SerialUSBDriver *sdup)
	Initializes a generic full duplex driver object.
msg_t	sduStart (SerialUSBDriver *sdup, const SerialUSBConfig *config)
	Configures and starts the driver.
void	sduStop (SerialUSBDriver *sdup)
	Stops the driver.
void	sduSuspendHookI (SerialUSBDriver *sdup)
	USB device suspend handler.
void	sduWakeupHookI (SerialUSBDriver *sdup)
	USB device wakeup handler.
void	sduConfigureHookI (SerialUSBDriver *sdup)
	USB device configured handler.
bool	sduRequestsHook (USBDriver *usbp)
	Default requests hook.
void	sduSOFHookI (SerialUSBDriver *sdup)
	SOF handler.
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.
msg_t	sduControl (USBDriver *usbp, unsigned int operation, void *arg)
	Control operation on a serial USB port.

Variables
static cdc_linecoding_t	linecoding
static const struct SerialUSBDriverVMT	vmt

Macro Definition Documentation

SERIAL_USB_BUFFERS_SIZE

#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 52 of file hal_serial_usb.h.

Referenced by sdu_start_receive(), and sduObjectInit().

SERIAL_USB_BUFFERS_NUMBER

#define SERIAL_USB_BUFFERS_NUMBER   2

Serial over USB number of buffers.

Note

The default is 2 buffers.

Definition at line 60 of file hal_serial_usb.h.

Referenced by sduObjectInit().

_serial_usb_driver_data

#define _serial_usb_driver_data

Value:

  _base_asynchronous_channel_data                                           \
  /* Driver state.*/                                                        \
  sdustate_t                state;                                          \
  /* Input buffers queue.*/                                                 \
  input_buffers_queue_t     ibqueue;                                        \
  /* Output queue.*/                                                        \
  output_buffers_queue_t    obqueue;                                        \
  /* Input buffer.*/                                                        \
  uint8_t                   ib[BQ_BUFFER_SIZE(SERIAL_USB_BUFFERS_NUMBER,    \
                                              SERIAL_USB_BUFFERS_SIZE)];    \
  /* Output buffer.*/                                                       \
  uint8_t                   ob[BQ_BUFFER_SIZE(SERIAL_USB_BUFFERS_NUMBER,    \
                                              SERIAL_USB_BUFFERS_SIZE)];    \
  /* End of the mandatory fields.*/                                         \
  /* Current configuration data.*/                                          \
  const SerialUSBConfig     *config;

SerialDriver specific data.

Definition at line 119 of file hal_serial_usb.h.

_serial_usb_driver_methods

#define _serial_usb_driver_methods    _base_asynchronous_channel_methods

SerialUSBDriver specific methods.

Definition at line 140 of file hal_serial_usb.h.

Typedef Documentation

SerialUSBDriver

typedef struct SerialUSBDriver SerialUSBDriver

Structure representing a serial over USB driver.

Definition at line 88 of file hal_serial_usb.h.

Enumeration Type Documentation

sdustate_t

enum sdustate_t

Driver state machine possible states.

Enumerator
SDU_UNINIT	Not initialized.
SDU_STOP	Stopped.
SDU_READY	Ready.

Definition at line 79 of file hal_serial_usb.h.

Function Documentation

sdu_start_receive()

bool sdu_start_receive ( SerialUSBDriver * sdup )

static

Definition at line 53 of file hal_serial_usb.c.

References ibqGetEmptyBufferI(), SDU_READY, SERIAL_USB_BUFFERS_SIZE, USB_ACTIVE, usbGetDriverStateI, usbGetReceiveStatusI, and usbStartReceiveI().

Referenced by ibnotify(), sduConfigureHookI(), and sduDataReceived().

Here is the call graph for this function:

_write()

size_t _write ( void * ip, const uint8_t * bp, size_t n )

static

Definition at line 85 of file hal_serial_usb.c.

References obqWriteTimeout(), and TIME_INFINITE.

Here is the call graph for this function:

_read()

size_t _read ( void * ip, uint8_t * bp, size_t n )

static

Definition at line 91 of file hal_serial_usb.c.

References ibqReadTimeout(), and TIME_INFINITE.

Here is the call graph for this function:

_put()

msg_t _put ( void * ip, uint8_t b )

static

Definition at line 97 of file hal_serial_usb.c.

References obqPutTimeout(), and TIME_INFINITE.

Here is the call graph for this function:

_get()

msg_t _get ( void * ip )

static

Definition at line 102 of file hal_serial_usb.c.

References ibqGetTimeout(), and TIME_INFINITE.

Here is the call graph for this function:

_putt()

msg_t _putt ( void * ip, uint8_t b, sysinterval_t timeout )

static

Definition at line 107 of file hal_serial_usb.c.

References obqPutTimeout().

Here is the call graph for this function:

_gett()

msg_t _gett ( void * ip, sysinterval_t timeout )

static

Definition at line 112 of file hal_serial_usb.c.

References ibqGetTimeout().

Here is the call graph for this function:

_writet()

size_t _writet ( void * ip, const uint8_t * bp, size_t n, sysinterval_t timeout )

static

Definition at line 117 of file hal_serial_usb.c.

References obqWriteTimeout().

Here is the call graph for this function:

_readt()

size_t _readt ( void * ip, uint8_t * bp, size_t n, sysinterval_t timeout )

static

Definition at line 123 of file hal_serial_usb.c.

References ibqReadTimeout().

Here is the call graph for this function:

_ctl()

msg_t _ctl ( void * ip, unsigned int operation, void * arg )

static

Definition at line 129 of file hal_serial_usb.c.

References CHN_CTL_INVALID, CHN_CTL_NOP, MSG_OK, osalDbgAssert, and osalDbgCheck.

Referenced by sduControl().

ibnotify()

void ibnotify ( io_buffers_queue_t * bqp )

static

Notification of empty buffer released into the input buffers queue.

Parameters

[in]

bqp

the buffers queue pointer.

Definition at line 168 of file hal_serial_usb.c.

References bqGetLinkX, and sdu_start_receive().

Referenced by sduObjectInit().

Here is the call graph for this function:

obnotify()

void obnotify ( io_buffers_queue_t * bqp )

static

Notification of filled buffer inserted into the output buffers queue.

Parameters

[in]

bqp

the buffers queue pointer.

Definition at line 178 of file hal_serial_usb.c.

References bqGetLinkX, obqGetFullBufferI(), osalDbgAssert, SDU_READY, USB_ACTIVE, usbGetDriverStateI, usbGetTransmitStatusI, and usbStartTransmitI().

Referenced by sduObjectInit().

Here is the call graph for this function:

sduInit()

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:

Object or module nitializer function.

Definition at line 210 of file hal_serial_usb.c.

Referenced by halInit().

sduObjectInit()

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]

sdup

pointer to a SerialUSBDriver structure

Function Class:

Object or module nitializer function.

Definition at line 222 of file hal_serial_usb.c.

References ibnotify(), ibqObjectInit(), obnotify(), obqObjectInit(), osalEventObjectInit(), SDU_STOP, SERIAL_USB_BUFFERS_NUMBER, SERIAL_USB_BUFFERS_SIZE, SerialUSBDriver::vmt, and vmt.

Here is the call graph for this function:

sduStart()

msg_t sduStart	(	SerialUSBDriver *	sdup,
		const SerialUSBConfig *	config )

Configures and starts the driver.

Parameters

[in]	sdup	pointer to a SerialUSBDriver object
[in]	config	the serial over USB driver configuration

Returns

The operation status.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 244 of file hal_serial_usb.c.

References SerialUSBConfig::bulk_in, SerialUSBConfig::bulk_out, HAL_RET_SUCCESS, USBDriver::in_params, SerialUSBConfig::int_in, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), USBDriver::out_params, SDU_READY, SDU_STOP, and SerialUSBConfig::usbp.

Here is the call graph for this function:

sduStop()

void sduStop

(

SerialUSBDriver *

sdup

)

Stops the driver.

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

Parameters

[in]

sdup

pointer 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 275 of file hal_serial_usb.c.

References CHN_DISCONNECTED, chnAddFlagsI, ibqResetI(), USBDriver::in_params, obqResetI(), osalDbgAssert, osalDbgCheck, osalOsRescheduleS(), osalSysLock(), osalSysUnlock(), USBDriver::out_params, SDU_READY, and SDU_STOP.

Here is the call graph for this function:

sduSuspendHookI()

void sduSuspendHookI

(

SerialUSBDriver *

sdup

)

USB device suspend handler.

Generates a CHN_DISCONNECT event and puts queues in non-blocking mode, this way the application cannot get stuck in the middle of an I/O operations.

Note

If this function is not called from an ISR then an explicit call to osalOsRescheduleS() in necessary afterward.

Parameters

[in]

sdup

pointer 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 315 of file hal_serial_usb.c.

References bqIsSuspendedX, bqSuspendI, CHN_DISCONNECTED, and chnAddFlagsI.

sduWakeupHookI()

void sduWakeupHookI

(

SerialUSBDriver *

sdup

)

USB device wakeup handler.

Generates a CHN_CONNECT event and resumes normal queues operations.

Note

If this function is not called from an ISR then an explicit call to osalOsRescheduleS() in necessary afterward.

Parameters

[in]

sdup

pointer 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 338 of file hal_serial_usb.c.

References bqResumeX, CHN_CONNECTED, and chnAddFlagsI.

sduConfigureHookI()

void sduConfigureHookI

(

SerialUSBDriver *

sdup

)

USB device configured handler.

Parameters

[in]

sdup

pointer 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 352 of file hal_serial_usb.c.

References bqResumeX, CHN_CONNECTED, chnAddFlagsI, ibqResetI(), obqResetI(), and sdu_start_receive().

Here is the call graph for this function:

sduRequestsHook()

bool 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]

usbp

pointer to the USBDriver object

Returns

The hook status.

Return values

true	Message handled internally.
false	Message not handled.

Definition at line 377 of file hal_serial_usb.c.

References CDC_GET_LINE_CODING, CDC_SET_CONTROL_LINE_STATE, CDC_SET_LINE_CODING, linecoding, USBDriver::setup, USB_RTYPE_TYPE_CLASS, USB_RTYPE_TYPE_MASK, and usbSetupTransfer.

sduSOFHookI()

void sduSOFHookI

(

SerialUSBDriver *

sdup

)

SOF handler.

The SOF interrupt is used for automatic flushing of incomplete buffers pending in the output queue.

Parameters

[in]

sdup

pointer 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 407 of file hal_serial_usb.c.

References obqGetFullBufferI(), obqTryFlushI(), osalDbgAssert, SDU_READY, USB_ACTIVE, usbGetDriverStateI, usbGetTransmitStatusI, and usbStartTransmitI().

Here is the call graph for this function:

sduDataTransmitted()

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]	usbp	pointer to the USBDriver object
[in]	ep	IN endpoint number

Definition at line 442 of file hal_serial_usb.c.

References CHN_OUTPUT_EMPTY, chnAddFlagsI, USBDriver::epc, USBEndpointConfig::in_maxsize, USBDriver::in_params, USBEndpointConfig::in_state, obqGetFullBufferI(), obqReleaseEmptyBufferI(), osalSysLockFromISR(), osalSysUnlockFromISR(), USBDriver::setup, USBInEndpointState::txsize, and usbStartTransmitI().

Here is the call graph for this function:

sduDataReceived()

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]	usbp	pointer to the USBDriver object
[in]	ep	OUT endpoint number

Definition at line 494 of file hal_serial_usb.c.

References CHN_INPUT_AVAILABLE, chnAddFlagsI, ibqPostFullBufferI(), osalSysLockFromISR(), osalSysUnlockFromISR(), USBDriver::out_params, sdu_start_receive(), and usbGetReceiveTransactionSizeX.

Here is the call graph for this function:

sduInterruptTransmitted()

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]	usbp	pointer to the USBDriver object
[in]	ep	endpoint number

Definition at line 531 of file hal_serial_usb.c.

sduControl()

msg_t sduControl	(	USBDriver *	usbp,
		unsigned int	operation,
		void *	arg )

Control operation on a serial USB port.

Parameters

[in]	usbp	pointer to a USBDriver object
[in]	operation	control operation code
[in,out]	arg	operation argument

Returns

The control operation status.

Return values

MSG_OK	in case of success.
MSG_TIMEOUT	in case of operation timeout.
MSG_RESET	in case of operation reset.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 551 of file hal_serial_usb.c.

References _ctl().

Here is the call graph for this function:

Variable Documentation

linecoding

cdc_linecoding_t linecoding

static

Initial value:

= {
  {0x00, 0x96, 0x00, 0x00},             
  LC_STOP_1, LC_PARITY_NONE, 8
}

Definition at line 44 of file hal_serial_usb.c.

Referenced by sduRequestsHook().

vmt

const struct SerialUSBDriverVMT vmt

static

Initial value:

= {
  (size_t)0,
  _write, _read, _put, _get,
  _putt, _gett, _writet, _readt,
  _ctl
}

Definition at line 156 of file hal_serial_usb.c.