Generic Serial Driver. More...

Collaboration diagram for Serial Driver:

Detailed Description

Generic Serial Driver.

This module implements a generic full duplex serial driver. The driver implements a SerialDriver interface and uses I/O Queues for communication between the upper and the lower driver. Event flags are used to notify the application about incoming data, outgoing data and other I/O events.
The module also contains functions that make the implementation of the interrupt service routines much easier.

Precondition: In order to use the SERIAL driver the HAL_USE_SERIAL 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_driver_methods _base_asynchronous_channel_methods
	`SerialDriver` specific methods. More...

#define	_serial_driver_data
	`SerialDriver` specific data. More...

Serial status flags
#define	SD_PARITY_ERROR (eventflags_t)32
	Parity. More...

#define	SD_FRAMING_ERROR (eventflags_t)64
	Framing. More...

#define	SD_OVERRUN_ERROR (eventflags_t)128
	Overflow. More...

#define	SD_NOISE_ERROR (eventflags_t)256
	Line noise. More...

#define	SD_BREAK_DETECTED (eventflags_t)512
	LIN Break. More...

#define	SD_QUEUE_FULL_ERROR (eventflags_t)1024
	Queue full. More...

Serial configuration options
#define	SERIAL_DEFAULT_BITRATE 38400
	Default bit rate. More...

#define	SERIAL_BUFFERS_SIZE 16
	Serial buffers size. More...

Macro Functions
#define	sdPutI(sdp, b) oqPutI(&(sdp)->oqueue, b)
	Direct write to a `SerialDriver`. More...

#define	sdPut(sdp, b) oqPut(&(sdp)->oqueue, b)
	Direct write to a `SerialDriver`. More...

#define	sdPutTimeout(sdp, b, t) oqPutTimeout(&(sdp)->oqueue, b, t)
	Direct write to a `SerialDriver` with timeout specification. More...

#define	sdGetI(sdp) iqGetI(&(sdp)->iqueue)
	Direct read from a `SerialDriver`. More...

#define	sdGet(sdp) iqGet(&(sdp)->iqueue)
	Direct read from a `SerialDriver`. More...

#define	sdGetTimeout(sdp, t) iqGetTimeout(&(sdp)->iqueue, t)
	Direct read from a `SerialDriver` with timeout specification. More...

#define	sdWriteI(sdp, b, n) oqWriteI(&(sdp)->oqueue, b, n)
	Direct blocking write to a `SerialDriver`. More...

#define	sdWrite(sdp, b, n) oqWriteTimeout(&(sdp)->oqueue, b, n, TIME_INFINITE)
	Direct blocking write to a `SerialDriver`. More...

#define	sdWriteTimeout(sdp, b, n, t) oqWriteTimeout(&(sdp)->oqueue, b, n, t)
	Direct blocking write to a `SerialDriver` with timeout specification. More...

#define	sdAsynchronousWrite(sdp, b, n) oqWriteTimeout(&(sdp)->oqueue, b, n, TIME_IMMEDIATE)
	Direct non-blocking write to a `SerialDriver`. More...

#define	sdReadI(sdp, b, n) iqReadI(&(sdp)->iqueue, b, n, TIME_INFINITE)
	Direct blocking read from a `SerialDriver`. More...

#define	sdRead(sdp, b, n) iqReadTimeout(&(sdp)->iqueue, b, n, TIME_INFINITE)
	Direct blocking read from a `SerialDriver`. More...

#define	sdReadTimeout(sdp, b, n, t) iqReadTimeout(&(sdp)->iqueue, b, n, t)
	Direct blocking read from a `SerialDriver` with timeout specification. More...

#define	sdAsynchronousRead(sdp, b, n) iqReadTimeout(&(sdp)->iqueue, b, n, TIME_IMMEDIATE)
	Direct non-blocking read from a `SerialDriver`. More...

PLATFORM configuration options
#define	PLATFORM_SERIAL_USE_USART1 FALSE
	USART1 driver enable switch. More...

Typedefs
typedef struct SerialDriver	SerialDriver
	Structure representing a serial driver. More...

Data Structures
struct	SerialDriverVMT
	`SerialDriver` virtual methods table. More...

struct	SerialDriver
	Full duplex serial driver class. More...

struct	SerialConfig
	PLATFORM Serial Driver configuration structure. More...

Functions
void	sdInit (void)
	Serial Driver initialization. More...

void	sdObjectInit (SerialDriver *sdp, qnotify_t inotify, qnotify_t onotify)
	Initializes a generic full duplex driver object. More...

void	sdStart (SerialDriver sdp, const SerialConfig config)
	Configures and starts the driver. More...

void	sdStop (SerialDriver *sdp)
	Stops the driver. More...

void	sdIncomingDataI (SerialDriver *sdp, uint8_t b)
	Handles incoming data. More...

msg_t	sdRequestDataI (SerialDriver *sdp)
	Handles outgoing data. More...

bool	sdPutWouldBlock (SerialDriver *sdp)
	Direct output check on a `SerialDriver`. More...

bool	sdGetWouldBlock (SerialDriver *sdp)
	Direct input check on a `SerialDriver`. More...

msg_t	sdControl (SerialDriver sdp, unsigned int operation, void arg)
	Control operation on a serial port. More...

void	sd_lld_init (void)
	Low level serial driver initialization. More...

void	sd_lld_start (SerialDriver sdp, const SerialConfig config)
	Low level serial driver configuration and (re)start. More...

void	sd_lld_stop (SerialDriver *sdp)
	Low level serial driver stop. More...

Enumerations

Variables
SerialDriver	SD1
	USART1 serial driver identifier. More...

static const SerialConfig	default_config
	Driver default configuration. More...

Macro Definition Documentation

#define SD_PARITY_ERROR (eventflags_t)32

Parity.

Definition at line 38 of file hal_serial.h.

#define SD_FRAMING_ERROR (eventflags_t)64

Framing.

Definition at line 39 of file hal_serial.h.

#define SD_OVERRUN_ERROR (eventflags_t)128

Overflow.

Definition at line 40 of file hal_serial.h.

#define SD_NOISE_ERROR (eventflags_t)256

Line noise.

Definition at line 41 of file hal_serial.h.

#define SD_BREAK_DETECTED (eventflags_t)512

LIN Break.

Definition at line 42 of file hal_serial.h.

#define SD_QUEUE_FULL_ERROR (eventflags_t)1024

Queue full.

Definition at line 43 of file hal_serial.h.

Referenced by sdIncomingDataI().

#define SERIAL_DEFAULT_BITRATE 38400

Default bit rate.

Configuration parameter, this is the baud rate selected for the default configuration.

Definition at line 60 of file hal_serial.h.

#define SERIAL_BUFFERS_SIZE 16

Serial buffers size.

Configuration parameter, you can change the depth of the queue buffers depending on the requirements of your application.

Note: The default is 16 bytes for both the transmission and receive buffers.; This is a global setting and it can be overridden by low level driver specific settings.

Definition at line 73 of file hal_serial.h.

Referenced by sdObjectInit().

#define _serial_driver_methods _base_asynchronous_channel_methods

SerialDriver specific methods.

Definition at line 104 of file hal_serial.h.

#define sdPutI	(	sdp,
		b
	)	oqPutI(&(sdp)->oqueue, b)

Direct write to a SerialDriver.

Note: This function bypasses the indirect access to the channel and writes directly on the output queue. This is faster but cannot be used to write to different channels implementations.

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 145 of file hal_serial.h.

#define sdPut	(	sdp,
		b
	)	oqPut(&(sdp)->oqueue, b)

Direct write to a SerialDriver.

Note: This function bypasses the indirect access to the channel and writes directly on the output queue. This is faster but cannot be used to write to different channels implementations.

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

Definition at line 155 of file hal_serial.h.

#define sdPutTimeout	(	sdp,
		b,
		t
	)	oqPutTimeout(&(sdp)->oqueue, b, t)

Direct write to a SerialDriver with timeout specification.

Note: This function bypasses the indirect access to the channel and writes directly on the output queue. This is faster but cannot be used to write to different channels implementations.

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

Definition at line 165 of file hal_serial.h.

#define sdGetI ( sdp ) iqGetI(&(sdp)->iqueue)

Direct read from a SerialDriver.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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 175 of file hal_serial.h.

#define sdGet ( sdp ) iqGet(&(sdp)->iqueue)

Direct read from a SerialDriver.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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

Definition at line 185 of file hal_serial.h.

#define sdGetTimeout	(	sdp,
		t
	)	iqGetTimeout(&(sdp)->iqueue, t)

Direct read from a SerialDriver with timeout specification.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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

Definition at line 195 of file hal_serial.h.

#define sdWriteI	(	sdp,
		b,
		n
	)	oqWriteI(&(sdp)->oqueue, b, n)

Direct blocking write to a SerialDriver.

Note: This function bypasses the indirect access to the channel and writes directly to the output queue. This is faster but cannot be used to write from different channels implementations.

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 205 of file hal_serial.h.

#define sdWrite	(	sdp,
		b,
		n
	)	oqWriteTimeout(&(sdp)->oqueue, b, n, TIME_INFINITE)

Direct blocking write to a SerialDriver.

Note: This function bypasses the indirect access to the channel and writes directly to the output queue. This is faster but cannot be used to write from different channels implementations.

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

#define sdWriteTimeout	(	sdp,
		b,
		n,
		t
	)	oqWriteTimeout(&(sdp)->oqueue, b, n, t)

Direct blocking write to a SerialDriver with timeout specification.

Note: This function bypasses the indirect access to the channel and writes directly to the output queue. This is faster but cannot be used to write to different channels implementations.

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

Definition at line 226 of file hal_serial.h.

#define sdAsynchronousWrite	(	sdp,
		b,
		n
	)	oqWriteTimeout(&(sdp)->oqueue, b, n, TIME_IMMEDIATE)

Direct non-blocking write to a SerialDriver.

Note: This function bypasses the indirect access to the channel and writes directly to the output queue. This is faster but cannot be used to write to different channels implementations.

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

Definition at line 237 of file hal_serial.h.

#define sdReadI	(	sdp,
		b,
		n
	)	iqReadI(&(sdp)->iqueue, b, n, TIME_INFINITE)

Direct blocking read from a SerialDriver.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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 248 of file hal_serial.h.

#define sdRead	(	sdp,
		b,
		n
	)	iqReadTimeout(&(sdp)->iqueue, b, n, TIME_INFINITE)

Direct blocking read from a SerialDriver.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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

Definition at line 258 of file hal_serial.h.

#define sdReadTimeout	(	sdp,
		b,
		n,
		t
	)	iqReadTimeout(&(sdp)->iqueue, b, n, t)

Direct blocking read from a SerialDriver with timeout specification.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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

Definition at line 269 of file hal_serial.h.

#define sdAsynchronousRead	(	sdp,
		b,
		n
	)	iqReadTimeout(&(sdp)->iqueue, b, n, TIME_IMMEDIATE)

Direct non-blocking read from a SerialDriver.

Note: This function bypasses the indirect access to the channel and reads directly from the input queue. This is faster but cannot be used to read from different channels implementations.

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

Definition at line 279 of file hal_serial.h.

#define PLATFORM_SERIAL_USE_USART1 FALSE

USART1 driver enable switch.

If set to TRUE the support for USART1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_serial_lld.h.

#define _serial_driver_data

Value:

_base_asynchronous_channel_data                                           \
  /* Driver state.*/                                                        \
  sdstate_t                 state;                                          \
  /* Input queue.*/                                                         \
  input_queue_t             iqueue;                                         \
  /* Output queue.*/                                                        \
  output_queue_t            oqueue;                                         \
  /* Input circular buffer.*/                                               \
  uint8_t                   ib[SERIAL_BUFFERS_SIZE];                        \
  /* Output circular buffer.*/                                              \
  uint8_t                   ob[SERIAL_BUFFERS_SIZE];                        \
  /* End of the mandatory fields.*/

SerialDriver specific data.

Definition at line 79 of file hal_serial_lld.h.

Typedef Documentation

typedef struct SerialDriver SerialDriver

Structure representing a serial driver.

Definition at line 97 of file hal_serial.h.

Enumeration Type Documentation

enum sdstate_t

Driver state machine possible states.

Enumerator
SD_UNINIT	Not initialized.
SD_STOP	Stopped.
SD_READY	Ready.

Definition at line 88 of file hal_serial.h.

Function Documentation

void sdInit ( 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 135 of file hal_serial.c.

References sd_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void sdObjectInit	(	SerialDriver *	sdp,
		qnotify_t	inotify,
		qnotify_t	onotify
	)

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]	sdp	pointer to a `SerialDriver` structure
[in]	inotify	pointer to a callback function that is invoked when some data is read from the Queue. The value can be `NULL`.
[in]	onotify	pointer to a callback function that is invoked when some data is written in the Queue. The value can be `NULL`.

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 158 of file hal_serial.c.

References iqObjectInit(), oqObjectInit(), osalEventObjectInit(), SD_STOP, SERIAL_BUFFERS_SIZE, and SerialDriver::vmt.

Referenced by sd_lld_init().

Here is the call graph for this function:

void sdStart	(	SerialDriver *	sdp,
		const SerialConfig *	config
	)

Configures and starts the driver.

Parameters

[in]	sdp	pointer to a `SerialDriver` object
[in]	config	the architecture-dependent serial driver configuration. If this parameter is set to `NULL` then a default configuration is used.

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

Definition at line 185 of file hal_serial.c.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), sd_lld_start(), SD_READY, and SD_STOP.

Here is the call graph for this function:

void sdStop ( SerialDriver * sdp )

Stops the driver.

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

Parameters

[in] sdp pointer to a SerialDriver object

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

Definition at line 206 of file hal_serial.c.

References iqResetI(), oqResetI(), osalDbgAssert, osalDbgCheck, osalOsRescheduleS(), osalSysLock(), osalSysUnlock(), sd_lld_stop(), SD_READY, and SD_STOP.

Here is the call graph for this function:

void sdIncomingDataI	(	SerialDriver *	sdp,
		uint8_t	b
	)

Handles incoming data.

This function must be called from the input interrupt service routine in order to enqueue incoming data and generate the related events.

Note: The incoming data event is only generated when the input queue becomes non-empty.; In order to gain some performance it is suggested to not use this function directly but copy this code directly into the interrupt service routine.

Parameters

[in]	sdp	pointer to a `SerialDriver` structure
[in]	b	the byte to be written in the driver's Input Queue

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 240 of file hal_serial.c.

References CHN_INPUT_AVAILABLE, chnAddFlagsI, iqIsEmptyI, iqPutI(), osalDbgCheck, osalDbgCheckClassI, and SD_QUEUE_FULL_ERROR.

Here is the call graph for this function:

msg_t sdRequestDataI ( SerialDriver * sdp )

Handles outgoing data.

Must be called from the output interrupt service routine in order to get the next byte to be transmitted.

Note: In order to gain some performance it is suggested to not use this function directly but copy this code directly into the interrupt service routine.

Parameters

[in] sdp pointer to a SerialDriver structure

Returns: The byte value read from the driver's output queue.

Return values

MSG_TIMEOUT if the queue is empty (the lower driver usually disables the interrupt source when this happens).

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 266 of file hal_serial.c.

References CHN_OUTPUT_EMPTY, chnAddFlagsI, oqGetI(), osalDbgCheck, and osalDbgCheckClassI.

Here is the call graph for this function:

bool sdPutWouldBlock ( SerialDriver * sdp )

Direct output check on a SerialDriver.

Note: This function bypasses the indirect access to the channel and checks directly the output queue. This is faster but cannot be used to check different channels implementations.

Parameters

[in] sdp pointer to a SerialDriver structure

Returns: The queue status.

Return values

false	if the next write operation would not block.
true	if the next write operation would block.

Deprecated:

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

Definition at line 293 of file hal_serial.c.

References oqIsFullI, osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

bool sdGetWouldBlock ( SerialDriver * sdp )

Direct input check on a SerialDriver.

Note: This function bypasses the indirect access to the channel and checks directly the input queue. This is faster but cannot be used to check different channels implementations.

Parameters

[in] sdp pointer to a SerialDriver structure

Returns: The queue status.

Return values

false	if the next write operation would not block.
true	if the next write operation would block.

Deprecated:

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

Definition at line 318 of file hal_serial.c.

References iqIsEmptyI, osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

msg_t sdControl	(	SerialDriver *	sdp,
		unsigned int	operation,
		void *	arg
	)

Control operation on a serial port.

Parameters

[in]	sdp	pointer to a `SerialDriver` 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 342 of file hal_serial.c.

void sd_lld_init ( void )

Low level serial driver initialization.

Function Class:Not an API, this function is for internal use only.

Definition at line 70 of file hal_serial_lld.c.

References sdObjectInit().

Referenced by sdInit().

Here is the call graph for this function:

void sd_lld_start	(	SerialDriver *	sdp,
		const SerialConfig *	config
	)

Low level serial driver configuration and (re)start.

Parameters

[in]	sdp	pointer to a `SerialDriver` object
[in]	config	the architecture-dependent serial driver configuration. If this parameter is set to `NULL` then a default configuration is used.

Function Class:Not an API, this function is for internal use only.

Definition at line 87 of file hal_serial_lld.c.

References default_config, and SD_STOP.

Referenced by sdStart().

void sd_lld_stop ( SerialDriver * sdp )

Low level serial driver stop.

De-initializes the USART, stops the associated clock, resets the interrupt vector.

Parameters

[in] sdp pointer to a SerialDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 114 of file hal_serial_lld.c.

References SD_READY.

Referenced by sdStop().

Variable Documentation

SerialDriver SD1

USART1 serial driver identifier.

Definition at line 39 of file hal_serial_lld.c.

const SerialConfig default_config

static

Initial value:

= {
  38400
}

Driver default configuration.

Definition at line 49 of file hal_serial_lld.c.

Referenced by sd_lld_start().

Detailed Description

Driver State Machine

Macros

Serial status flags

Serial configuration options

Macro Functions

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation