Collaboration diagram for Abstract I/O Channel Interface:

Detailed Description

This module defines an abstract interface for I/O channels by extending the BaseSequentialStream interface.
Note that no code is present, I/O channels are just abstract interface like structures, you should look at the systems as to a set of abstract C++ classes (even if written in C). Specific device drivers can use/extend the interface and implement them.
This system has the advantage to make the access to channels independent from the implementation logic.

Macros
#define	_base_channel_methods
	`BaseChannel` specific methods. More...

#define	_base_channel_data _base_sequential_stream_data
	`BaseChannel` specific data. More...

#define	_base_asynchronous_channel_methods _base_channel_methods \
	`BaseAsynchronousChannel` specific methods. More...

#define	_base_asynchronous_channel_data
	`BaseAsynchronousChannel` specific data. More...

Default control operation codes.
#define	CHN_CTL_INVALID 0 /** @brief Invalid operation code. */

#define	CHN_CTL_NOP 1 /** @brief Does nothing. */

#define	CHN_CTL_TX_WAIT 2 /** @brief Wait for TX completion. */

Macro Functions (BaseChannel)
#define	chnPutTimeout(ip, b, time) ((ip)->vmt->putt(ip, b, time))
	Channel blocking byte write with timeout. More...

#define	chnGetTimeout(ip, time) ((ip)->vmt->gett(ip, time))
	Channel blocking byte read with timeout. More...

#define	chnWrite(ip, bp, n) streamWrite(ip, bp, n)
	Channel blocking write. More...

#define	chnWriteTimeout(ip, bp, n, time) ((ip)->vmt->writet(ip, bp, n, time))
	Channel blocking write with timeout. More...

#define	chnRead(ip, bp, n) streamRead(ip, bp, n)
	Channel blocking read. More...

#define	chnReadTimeout(ip, bp, n, time) ((ip)->vmt->readt(ip, bp, n, time))
	Channel blocking read with timeout. More...

#define	chnControl(ip, operation, arg) ((ip)->vmt->ctl(ip, operation, arg))
	Control operation on a channel. More...

I/O status flags added to the event listener
#define	CHN_NO_ERROR (eventflags_t)0
	No pending conditions. More...

#define	CHN_CONNECTED (eventflags_t)1
	Connection happened. More...

#define	CHN_DISCONNECTED (eventflags_t)2
	Disconnection happened. More...

#define	CHN_INPUT_AVAILABLE (eventflags_t)4
	Data available in the input queue. More...

#define	CHN_OUTPUT_EMPTY (eventflags_t)8
	Output queue empty. More...

#define	CHN_TRANSMISSION_END (eventflags_t)16
	Transmission end. More...

Macro Functions (BaseAsynchronousChannel)
#define	chnGetEventSource(ip) (&((ip)->event))
	Returns the I/O condition event source. More...

#define	chnAddFlagsI(ip, flags)
	Adds status flags to the listeners's flags mask. More...

Data Structures
struct	BaseChannelVMT
	`BaseChannel` virtual methods table. More...

struct	BaseChannel
	Base channel class. More...

struct	BaseAsynchronousChannelVMT
	`BaseAsynchronousChannel` virtual methods table. More...

struct	BaseAsynchronousChannel
	Base asynchronous channel class. More...

Macro Definition Documentation

#define _base_channel_methods

Value:

_base_sequential_stream_methods                                           \
  /* Channel put method with timeout specification.*/                       \
  msg_t (*putt)(void *instance, uint8_t b, sysinterval_t time);             \
  /* Channel get method with timeout specification.*/                       \
  msg_t (*gett)(void *instance, sysinterval_t time);                        \
  /* Channel write method with timeout specification.*/                     \
  size_t (*writet)(void *instance, const uint8_t *bp,                       \
                   size_t n, sysinterval_t time);                           \
  /* Channel read method with timeout specification.*/                      \
  size_t (*readt)(void *instance, uint8_t *bp, size_t n,                    \
                  sysinterval_t time);                                      \
  /* Channel control method.*/                                              \
  msg_t (*ctl)(void *instance, unsigned int operation, void *arg);

BaseChannel specific methods.

Definition at line 51 of file hal_channels.h.

#define _base_channel_data _base_sequential_stream_data

BaseChannel specific data.

Note: It is empty because BaseChannel is only an interface without implementation.

Definition at line 71 of file hal_channels.h.

#define chnPutTimeout	(	ip,
		b,
		time
	)	((ip)->vmt->putt(ip, b, time))

Channel blocking byte write with timeout.

This function writes a byte value to a channel. If the channel is not ready to accept data then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[in]	b	the byte value to be written to the channel
[in]	time	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

STM_OK	if the operation succeeded.
STM_TIMEOUT	if the specified time expired.
STM_RESET	if the channel associated queue (if any) was reset.

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

Definition at line 119 of file hal_channels.h.

#define chnGetTimeout	(	ip,
		time
	)	((ip)->vmt->gett(ip, time))

Channel blocking byte read with timeout.

This function reads a byte value from a channel. If the data is not available then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[in]	time	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: A byte value from the queue.

Return values

STM_TIMEOUT	if the specified time expired.
STM_RESET	if the channel associated queue (if any) has been reset.

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

Definition at line 139 of file hal_channels.h.

#define chnWrite	(	ip,
		bp,
		n
	)	streamWrite(ip, bp, n)

Channel blocking write.

The function writes data from a buffer to a channel. If the channel is not ready to accept data then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[out]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred

Returns: The number of bytes transferred.

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

Definition at line 154 of file hal_channels.h.

#define chnWriteTimeout	(	ip,
		bp,
		n,
		time
	)	((ip)->vmt->writet(ip, bp, n, time))

Channel blocking write with timeout.

The function writes data from a buffer to a channel. If the channel is not ready to accept data then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[out]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred
[in]	time	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The number of bytes transferred.

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

Definition at line 173 of file hal_channels.h.

#define chnRead	(	ip,
		bp,
		n
	)	streamRead(ip, bp, n)

Channel blocking read.

The function reads data from a channel into a buffer. If the data is not available then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[in]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred

Returns: The number of bytes transferred.

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

Definition at line 188 of file hal_channels.h.

#define chnReadTimeout	(	ip,
		bp,
		n,
		time
	)	((ip)->vmt->readt(ip, bp, n, time))

Channel blocking read with timeout.

The function reads data from a channel into a buffer. If the data is not available then the calling thread is suspended.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[in]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred
[in]	time	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The number of bytes transferred.

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

Definition at line 207 of file hal_channels.h.

#define chnControl	(	ip,
		operation,
		arg
	)	((ip)->vmt->ctl(ip, operation, arg))

Control operation on a channel.

Parameters

[in]	ip	pointer to a `BaseChannel` or derived class
[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 223 of file hal_channels.h.

#define CHN_NO_ERROR (eventflags_t)0

No pending conditions.

Definition at line 231 of file hal_channels.h.

#define CHN_CONNECTED (eventflags_t)1

Connection happened.

Definition at line 233 of file hal_channels.h.

Referenced by sduConfigureHookI(), and sduWakeupHookI().

#define CHN_DISCONNECTED (eventflags_t)2

Disconnection happened.

Definition at line 235 of file hal_channels.h.

Referenced by sduStop(), and sduSuspendHookI().

#define CHN_INPUT_AVAILABLE (eventflags_t)4

Data available in the input queue.

Definition at line 237 of file hal_channels.h.

Referenced by sdIncomingDataI(), and sduDataReceived().

#define CHN_OUTPUT_EMPTY (eventflags_t)8

Output queue empty.

Definition at line 239 of file hal_channels.h.

Referenced by sdRequestDataI(), and sduDataTransmitted().

#define CHN_TRANSMISSION_END (eventflags_t)16

Transmission end.

Definition at line 241 of file hal_channels.h.

#define _base_asynchronous_channel_methods _base_channel_methods \

BaseAsynchronousChannel specific methods.

Definition at line 247 of file hal_channels.h.

#define _base_asynchronous_channel_data

Value:

_base_channel_data                                                        \
  /* I/O condition event source.*/                                          \
  event_source_t        event;

BaseAsynchronousChannel specific data.

Definition at line 253 of file hal_channels.h.

#define chnGetEventSource ( ip ) (&((ip)->event))

Returns the I/O condition event source.

The event source is broadcasted when an I/O condition happens.

Parameters

[in] ip pointer to a BaseAsynchronousChannel or derived class

Returns: A pointer to an EventSource object.

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

Definition at line 294 of file hal_channels.h.

#define chnAddFlagsI	(	ip,
		flags
	)

Value:

{                                           \
  osalEventBroadcastFlagsI(&(ip)->event, flags);                            \
}

Adds status flags to the listeners's flags mask.

This function is usually called from the I/O ISRs in order to notify I/O conditions such as data events, errors, signal changes etc.

Parameters

[in]	ip	pointer to a `BaseAsynchronousChannel` or derived class
[in]	flags	condition flags to be added to the listener flags mask

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 308 of file hal_channels.h.

Referenced by sdIncomingDataI(), sdRequestDataI(), sduConfigureHookI(), sduDataReceived(), sduDataTransmitted(), sduStop(), sduSuspendHookI(), and sduWakeupHookI().

Detailed Description

Macros

Default control operation codes.

Macro Functions (BaseChannel)

I/O status flags added to the event listener

Macro Functions (BaseAsynchronousChannel)

Data Structures

Macro Definition Documentation