Serial over USB Driver. More...

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

Macros
#define	_serial_usb_driver_data
	`SerialDriver` specific data. More...

#define	_serial_usb_driver_methods _base_asynchronous_channel_methods
	`SerialUSBDriver` specific methods. More...

SERIAL_USB configuration options
#define	SERIAL_USB_BUFFERS_SIZE 256
	Serial over USB buffers size. More...

#define	SERIAL_USB_BUFFERS_NUMBER 2
	Serial over USB number of buffers. More...

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

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

Functions
static void	ibnotify (io_buffers_queue_t *bqp)
	Notification of empty buffer released into the input buffers queue. More...

static void	obnotify (io_buffers_queue_t *bqp)
	Notification of filled buffer inserted into the output buffers queue. More...

void	sduInit (void)
	Serial Driver initialization. More...

void	sduObjectInit (SerialUSBDriver *sdup)
	Initializes a generic full duplex driver object. More...

void	sduStart (SerialUSBDriver sdup, const SerialUSBConfig config)
	Configures and starts the driver. More...

void	sduStop (SerialUSBDriver *sdup)
	Stops the driver. More...

void	sduSuspendHookI (SerialUSBDriver *sdup)
	USB device suspend handler. More...

void	sduWakeupHookI (SerialUSBDriver *sdup)
	USB device wakeup handler. More...

void	sduConfigureHookI (SerialUSBDriver *sdup)
	USB device configured handler. More...

bool	sduRequestsHook (USBDriver *usbp)
	Default requests hook. More...

void	sduSOFHookI (SerialUSBDriver *sdup)
	SOF handler. More...

void	sduDataTransmitted (USBDriver *usbp, usbep_t ep)
	Default data transmitted callback. More...

void	sduDataReceived (USBDriver *usbp, usbep_t ep)
	Default data received callback. More...

void	sduInterruptTransmitted (USBDriver *usbp, usbep_t ep)
	Default data received callback. More...

msg_t	sduControl (USBDriver usbp, unsigned int operation, void arg)
	Control operation on a serial USB port. More...

Enumerations

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

Referenced by sduObjectInit().

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

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

#define _serial_usb_driver_methods _base_asynchronous_channel_methods

SerialUSBDriver specific methods.

Definition at line 140 of file hal_serial_usb.h.

Typedef Documentation

typedef struct SerialUSBDriver SerialUSBDriver

Structure representing a serial over USB driver.

Definition at line 88 of file hal_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 79 of file hal_serial_usb.h.

Function Documentation

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

Referenced by sduObjectInit().

static 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(), SDU_READY, USB_ACTIVE, usbGetDriverStateI, usbGetTransmitStatusI, and usbStartTransmitI().

Referenced by sduObjectInit().

Here is the call graph for this function:

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 211 of file hal_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] sdup pointer 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 223 of file hal_serial_usb.c.

References ibnotify(), ibqObjectInit(), obnotify(), obqObjectInit(), osalEventObjectInit(), SDU_STOP, SERIAL_USB_BUFFERS_NUMBER, 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]	sdup	pointer to a `SerialUSBDriver` object
[in]	config	the 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 244 of file hal_serial_usb.c.

References SerialUSBConfig::bulk_in, SerialUSBConfig::bulk_out, 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:

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 271 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:

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

References bqSuspendI, CHN_DISCONNECTED, and chnAddFlagsI.

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

References bqResumeX, CHN_CONNECTED, and chnAddFlagsI.

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

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

Here is the call graph for this function:

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

References USBDriver::setup, and usbSetupTransfer.

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 399 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:

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 434 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:

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

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

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

Definition at line 523 of file hal_serial_usb.c.

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

Detailed Description

Driver State Machine

Macros

SERIAL_USB configuration options

Typedefs

Data Structures

Functions

Enumerations

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation