Generic SIO Driver. More...

Collaboration diagram for SIO Driver:

Detailed Description

Generic SIO Driver.

This driver abstracts a generic serial communication channel, usually an UART, this driver is similar to Serial and UART drivers but follows a different concept:

Very close to HW.
No buffering done in SW, the driver relies on the peripheral internal FIFO, if any.
Asynchronous, the API is always non blocking.
Callbacks capable, operations completion and other events are notified using callbacks.
Very short code paths, especially in ISRs.

Precondition: In order to use the SIO driver the HAL_USE_SIO 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	sioGetFlagsX(siop) sio_lld_get_flags(siop)
	Returns the current set of flags and clears it. More...

#define	sioRXIsEmptyX(siop) sio_lld_rx_is_empty(siop)
	Determines the state of the RX FIFO. More...

#define	sioTXIsFullX(siop) sio_lld_tx_is_full(siop)
	Determines the state of the TX FIFO. More...

#define	sioRXGetX(siop) sio_lld_rx_get(siop)
	Returns one frame from the RX FIFO. More...

#define	sioTXPutX(siop, data) sio_lld_tx_put(siop, data)
	Pushes one frame into the TX FIFO. More...

#define	sioReadX(siop, buffer, size) sio_lld_read(siop, buffer, size)
	Reads data from the RX FIFO. More...

#define	sioWriteX(siop, buffer, size) sio_lld_write(siop, buffer, size)
	Writes data into the TX FIFO. More...

#define	sioControlX(siop, operation, arg) sio_lld_control(siop, operation, arg)
	Control operation on a serial port. More...

#define	sio_lld_rx_is_empty(siop) true
	Determines the state of the RX FIFO. More...

#define	sio_lld_tx_is_full(siop) true
	Determines the state of the TX FIFO. More...

#define	sio_lld_rx_get(siop)
	Returns one frame from the RX FIFO. More...

#define	sio_lld_tx_put(siop, data)
	Pushes one frame into the TX FIFO. More...

SIO status flags
#define	SIO_NO_ERROR 0
	No pending conditions. More...

#define	SIO_PARITY_ERROR 4
	Parity error happened. More...

#define	SIO_FRAMING_ERROR 8
	Framing error happened. More...

#define	SIO_OVERRUN_ERROR 16
	Overflow happened. More...

#define	SIO_NOISE_ERROR 32
	Noise on the line. More...

#define	SIO_BREAK_DETECTED 64
	Break detected. More...

PLATFORM configuration options
#define	PLATFORM_SIO_USE_SIO1 FALSE
	SIO driver enable switch. More...

Typedefs
typedef struct hal_sio_driver	SIODriver
	Type of structure representing a SIO driver. More...

typedef struct hal_sio_config	SIOConfig
	Type of structure representing a SIO configuration. More...

typedef uint32_t	sioflags_t
	SIO driver condition flags type. More...

typedef void(*	siocb_t) (SIODriver *siop)
	Generic SIO notification callback type. More...

typedef void(*	sioecb_t) (SIODriver *siop, sioflags_t e)
	Receive error SIO notification callback type. More...

Data Structures
struct	hal_sio_config
	Driver configuration structure. More...

struct	hal_sio_driver
	Structure representing a SIO driver. More...

Functions
void	sioInit (void)
	SIO Driver initialization. More...

void	sioObjectInit (SIODriver *siop)
	Initializes the standard part of a `SIODriver` structure. More...

void	sioStart (SIODriver siop, const SIOConfig config)
	Configures and activates the SIO peripheral. More...

void	sioStop (SIODriver *siop)
	Deactivates the SIO peripheral. More...

void	sio_lld_init (void)
	Low level SIO driver initialization. More...

void	sio_lld_start (SIODriver *siop)
	Configures and activates the SIO peripheral. More...

void	sio_lld_stop (SIODriver *siop)
	Deactivates the SIO peripheral. More...

msg_t	sio_lld_control (SIODriver siop, unsigned int operation, void arg)
	Control operation on a serial port. More...

Enumerations

Variables
SIODriver	SIOD1
	SIO1 driver identifier. More...

Macro Definition Documentation

#define SIO_NO_ERROR 0

No pending conditions.

Definition at line 38 of file hal_sio.h.

#define SIO_PARITY_ERROR 4

Parity error happened.

Definition at line 39 of file hal_sio.h.

#define SIO_FRAMING_ERROR 8

Framing error happened.

Definition at line 40 of file hal_sio.h.

#define SIO_OVERRUN_ERROR 16

Overflow happened.

Definition at line 41 of file hal_sio.h.

#define SIO_NOISE_ERROR 32

Noise on the line.

Definition at line 42 of file hal_sio.h.

#define SIO_BREAK_DETECTED 64

Break detected.

Definition at line 43 of file hal_sio.h.

#define sioGetFlagsX ( siop ) sio_lld_get_flags(siop)

Returns the current set of flags and clears it.

Definition at line 93 of file hal_sio.h.

#define sioRXIsEmptyX ( siop ) sio_lld_rx_is_empty(siop)

Determines the state of the RX FIFO.

Parameters

[in] siop pointer to the SIODriver object

Returns: The RX FIFO state.

Return values

false	if RX FIFO is not empty
true	if RX FIFO is empty

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 105 of file hal_sio.h.

#define sioTXIsFullX ( siop ) sio_lld_tx_is_full(siop)

Determines the state of the TX FIFO.

Parameters

[in] siop pointer to the SIODriver object

Returns: The TX FIFO state.

Return values

false	if TX FIFO is not full
true	if TX FIFO is full

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 117 of file hal_sio.h.

#define sioRXGetX ( siop ) sio_lld_rx_get(siop)

Returns one frame from the RX FIFO.

Note: If the FIFO is empty then the returned value is unpredictable.

Parameters

[in] siop pointer to the SIODriver object

Returns: The frame from RX FIFO.

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 128 of file hal_sio.h.

#define sioTXPutX	(	siop,
		data
	)	sio_lld_tx_put(siop, data)

Pushes one frame into the TX FIFO.

Note: If the FIFO is full then the behavior is unpredictable.

Parameters

[in]	siop	pointer to the `SIODriver` object
[in]	data	frame to be written

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 139 of file hal_sio.h.

#define sioReadX	(	siop,
		buffer,
		size
	)	sio_lld_read(siop, buffer, size)

Reads data from the RX FIFO.

This function is non-blocking, data is read if present and the effective amount is returned.

Note: This function can be called from any context but it is meant to be called from the rxne_cb callback handler.

Parameters

[in]	siop	pointer to the `SIODriver` object
[in]	buffer	buffer for the received data
[in]	size	maximum number of frames to read

Returns: The number of received frames.

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 155 of file hal_sio.h.

#define sioWriteX	(	siop,
		buffer,
		size
	)	sio_lld_write(siop, buffer, size)

Writes data into the TX FIFO.

This function is non-blocking, data is written if there is space in the FIFO and the effective amount is returned.

Note: This function can be called from any context but it is meant to be called from the txnf_cb callback handler.

Parameters

[in]	siop	pointer to the `SIODriver` object
[out]	buffer	buffer containing the data to be transmitted
[in]	size	maximum number of frames to read

Returns: The number of transmitted frames.

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 171 of file hal_sio.h.

#define sioControlX	(	siop,
		operation,
		arg
	)	sio_lld_control(siop, operation, arg)

Control operation on a serial port.

Parameters

[in]	siop	pointer to the `SIODriver` 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:This is an X-Class API, this function can be invoked from any context.

Definition at line 187 of file hal_sio.h.

#define PLATFORM_SIO_USE_SIO1 FALSE

SIO driver enable switch.

If set to TRUE the support for SIO1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_sio_lld.h.

#define sio_lld_rx_is_empty ( siop ) true

Determines the state of the RX FIFO.

Parameters

[in] siop pointer to the SIODriver object

Returns: The RX FIFO state.

Return values

false	if RX FIFO is not empty
true	if RX FIFO is empty

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

Definition at line 144 of file hal_sio_lld.h.

#define sio_lld_tx_is_full ( siop ) true

Determines the state of the TX FIFO.

Parameters

[in] siop pointer to the SIODriver object

Returns: The TX FIFO state.

Return values

false	if TX FIFO is not full
true	if TX FIFO is full

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

Definition at line 156 of file hal_sio_lld.h.

#define sio_lld_rx_get ( siop )

Returns one frame from the RX FIFO.

Note: If the FIFO is empty then the returned value is unpredictable.

Parameters

[in] siop pointer to the SIODriver object

Returns: The frame from RX FIFO.

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

Definition at line 167 of file hal_sio_lld.h.

#define sio_lld_tx_put	(	siop,
		data
	)

Pushes one frame into the TX FIFO.

Note: If the FIFO is full then the behavior is unpredictable.

Parameters

[in]	siop	pointer to the `SIODriver` object
[in]	data	frame to be written

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

Definition at line 178 of file hal_sio_lld.h.

Typedef Documentation

typedef struct hal_sio_driver SIODriver

Type of structure representing a SIO driver.

Definition at line 68 of file hal_sio.h.

typedef struct hal_sio_config SIOConfig

Type of structure representing a SIO configuration.

Definition at line 73 of file hal_sio.h.

typedef uint32_t sioflags_t

SIO driver condition flags type.

Definition at line 63 of file hal_sio_lld.h.

typedef void(* siocb_t) (SIODriver *siop)

Generic SIO notification callback type.

Parameters

[in] siop pointer to the SIODriver object

Definition at line 70 of file hal_sio_lld.h.

typedef void(* sioecb_t) (SIODriver *siop, sioflags_t e)

Receive error SIO notification callback type.

Parameters

[in]	siop	pointer to the `SIODriver` object triggering the callback
[in]	e	receive error mask

Definition at line 79 of file hal_sio_lld.h.

Enumeration Type Documentation

enum siostate_t

Driver state machine possible states.

Enumerator
SIO_UNINIT	Not initialized.
SIO_STOP	Stopped.
SIO_READY	Ready.

Definition at line 78 of file hal_sio.h.

Function Documentation

void sioInit ( void )

SIO 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 56 of file hal_sio.c.

References sio_lld_init().

Here is the call graph for this function:

void sioObjectInit ( SIODriver * siop )

Initializes the standard part of a SIODriver structure.

Parameters

[out] siop pointer to the SIODriver object

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

Definition at line 68 of file hal_sio.c.

References hal_sio_driver::config, SIO_STOP, and hal_sio_driver::state.

Referenced by sio_lld_init().

void sioStart	(	SIODriver *	siop,
		const SIOConfig *	config
	)

Configures and activates the SIO peripheral.

Parameters

[in]	siop	pointer to the `SIODriver` object
[in]	config	pointer to the `SIOConfig` object

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

Definition at line 87 of file hal_sio.c.

References hal_sio_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), sio_lld_start(), SIO_READY, SIO_STOP, and hal_sio_driver::state.

Here is the call graph for this function:

void sioStop ( SIODriver * siop )

Deactivates the SIO peripheral.

Parameters

[in] siop pointer to the SIODriver object

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

Definition at line 108 of file hal_sio.c.

References hal_sio_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), sio_lld_stop(), SIO_READY, SIO_STOP, and hal_sio_driver::state.

Here is the call graph for this function:

void sio_lld_init ( void )

Low level SIO driver initialization.

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

Definition at line 65 of file hal_sio_lld.c.

References sioObjectInit().

Referenced by sioInit().

Here is the call graph for this function:

void sio_lld_start ( SIODriver * siop )

Configures and activates the SIO peripheral.

Parameters

[in] siop pointer to the SIODriver object

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

Definition at line 80 of file hal_sio_lld.c.

References SIO_STOP, and hal_sio_driver::state.

Referenced by sioStart().

void sio_lld_stop ( SIODriver * siop )

Deactivates the SIO peripheral.

Parameters

[in] siop pointer to the SIODriver object

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

Definition at line 101 of file hal_sio_lld.c.

References SIO_READY, and hal_sio_driver::state.

Referenced by sioStop().

msg_t sio_lld_control	(	SIODriver *	siop,
		unsigned int	operation,
		void *	arg
	)

Control operation on a serial port.

Parameters

[in]	siop	pointer to the `SIODriver` 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:Not an API, this function is for internal use only.

Definition at line 129 of file hal_sio_lld.c.

Variable Documentation

SIODriver SIOD1

SIO1 driver identifier.

Definition at line 41 of file hal_sio_lld.c.

Detailed Description

Driver State Machine

Macros

SIO status flags

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation