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.

Collaboration diagram for Abstract I/O Channel Interface:

Default control operation codes.
#define	CHN_CTL_INVALID 0
	Invalid operation code.
#define	CHN_CTL_NOP 1
	Does nothing.
#define	CHN_CTL_TX_WAIT 2
	Wait for TX completion.

Macro Functions (BaseChannel)
#define	chnPutTimeout(ip, b, time)
	Channel blocking byte write with timeout.
#define	chnGetTimeout(ip, time)
	Channel blocking byte read with timeout.
#define	chnWrite(ip, bp, n)
	Channel blocking write.
#define	chnWriteTimeout(ip, bp, n, time)
	Channel blocking write with timeout.
#define	chnRead(ip, bp, n)
	Channel blocking read.
#define	chnReadTimeout(ip, bp, n, time)
	Channel blocking read with timeout.
#define	chnControl(ip, operation, arg)
	Control operation on a channel.

I/O status flags added to the event listener
#define	CHN_NO_ERROR (eventflags_t)0
	No pending conditions.
#define	CHN_CONNECTED (eventflags_t)1
	Connection happened.
#define	CHN_DISCONNECTED (eventflags_t)2
	Disconnection happened.
#define	CHN_INPUT_AVAILABLE (eventflags_t)4
	Data available in the input queue.
#define	CHN_OUTPUT_EMPTY (eventflags_t)8
	Output queue empty.
#define	CHN_TRANSMISSION_END (eventflags_t)16
	Transmission end.
#define	CHN_PARITY_ERROR (eventflags_t)32
	Parity error.
#define	CHN_FRAMING_ERROR (eventflags_t)64
	Framing error.
#define	CHN_NOISE_ERROR (eventflags_t)128
	Line noise error.
#define	CHN_OVERRUN_ERROR (eventflags_t)256
	Overflow error.
#define	CHN_IDLE_DETECTED (eventflags_t)512
	RX line idle.
#define	CHN_BREAK_DETECTED (eventflags_t)1024
	LIN Break.
#define	CHN_BUFFER_FULL_ERROR (eventflags_t)2048

Macro Functions (BaseAsynchronousChannel)
#define	chnGetEventSource(ip)
	Returns the I/O condition event source.
#define	chnAddFlagsI(ip, flags)
	Adds status flags to the listeners's flags mask.

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

Macros
#define	_base_channel_methods
	`BaseChannel` specific methods.
#define	_base_channel_data _base_sequential_stream_data
	`BaseChannel` specific data.
#define	_base_asynchronous_channel_methods _base_channel_methods \
	`BaseAsynchronousChannel` specific methods.
#define	_base_asynchronous_channel_data
	`BaseAsynchronousChannel` specific data.

Macro Definition Documentation

◆ CHN_CTL_INVALID

#define CHN_CTL_INVALID 0

Invalid operation code.

Definition at line 43 of file hal_channels.h.

Referenced by __buffered_serial_ctl_impl(), __ctl(), _ctl(), and _ctl().

◆ CHN_CTL_NOP

#define CHN_CTL_NOP 1

Does nothing.

Definition at line 44 of file hal_channels.h.

Referenced by __buffered_serial_ctl_impl(), __ctl(), _ctl(), and _ctl().

◆ CHN_CTL_TX_WAIT

#define CHN_CTL_TX_WAIT 2

Wait for TX completion.

Definition at line 45 of file hal_channels.h.

◆ _base_channel_methods

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

◆ _base_channel_data

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

◆ chnPutTimeout

#define chnPutTimeout	(	ip,
		b,
		time )

Value:

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

◆ chnGetTimeout

#define chnGetTimeout	(		ip,
			time )

Value:

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

◆ chnWrite

#define chnWrite	(	ip,
		bp,
		n )

Value:

streamWrite(ip, bp, n)

streamWrite

#define streamWrite(ip, bp, n)

Sequential Stream write.

Definition hal_streams.h:113

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

◆ chnWriteTimeout

#define chnWriteTimeout	(	ip,
		bp,
		n,
		time )

Value:

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

◆ chnRead

#define chnRead	(	ip,
		bp,
		n )

Value:

streamRead(ip, bp, n)

streamRead

#define streamRead(ip, bp, n)

Sequential Stream read.

Definition hal_streams.h:128

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

◆ chnReadTimeout

#define chnReadTimeout	(	ip,
		bp,
		n,
		time )

Value:

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

◆ chnControl

#define chnControl	(	ip,
		operation,
		arg )

Value:

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

◆ CHN_NO_ERROR

#define CHN_NO_ERROR (eventflags_t)0

No pending conditions.

Definition at line 227 of file hal_channels.h.

◆ CHN_CONNECTED

#define CHN_CONNECTED (eventflags_t)1

Connection happened.

Definition at line 229 of file hal_channels.h.

Referenced by sduConfigureHookI(), and sduWakeupHookI().

◆ CHN_DISCONNECTED

#define CHN_DISCONNECTED (eventflags_t)2

Disconnection happened.

Definition at line 231 of file hal_channels.h.

Referenced by sduStop(), and sduSuspendHookI().

◆ CHN_INPUT_AVAILABLE

#define CHN_INPUT_AVAILABLE (eventflags_t)4

Data available in the input queue.

Definition at line 233 of file hal_channels.h.

Referenced by bsIncomingDataI(), sdIncomingDataI(), and sduDataReceived().

◆ CHN_OUTPUT_EMPTY

#define CHN_OUTPUT_EMPTY (eventflags_t)8

Output queue empty.

Definition at line 235 of file hal_channels.h.

Referenced by __bsio_push_data(), bsRequestDataI(), sdRequestDataI(), and sduDataTransmitted().

◆ CHN_TRANSMISSION_END

#define CHN_TRANSMISSION_END (eventflags_t)16

Transmission end.

Definition at line 237 of file hal_channels.h.

◆ CHN_PARITY_ERROR

#define CHN_PARITY_ERROR (eventflags_t)32

Parity error.

Definition at line 239 of file hal_channels.h.

◆ CHN_FRAMING_ERROR

#define CHN_FRAMING_ERROR (eventflags_t)64

Framing error.

Definition at line 241 of file hal_channels.h.

◆ CHN_NOISE_ERROR

#define CHN_NOISE_ERROR (eventflags_t)128

Line noise error.

Definition at line 243 of file hal_channels.h.

◆ CHN_OVERRUN_ERROR

#define CHN_OVERRUN_ERROR (eventflags_t)256

Overflow error.

Definition at line 245 of file hal_channels.h.

◆ CHN_IDLE_DETECTED

#define CHN_IDLE_DETECTED (eventflags_t)512

RX line idle.

Definition at line 247 of file hal_channels.h.

◆ CHN_BREAK_DETECTED

#define CHN_BREAK_DETECTED (eventflags_t)1024

LIN Break.

RX buffer full.

Definition at line 249 of file hal_channels.h.

◆ CHN_BUFFER_FULL_ERROR

#define CHN_BUFFER_FULL_ERROR (eventflags_t)2048

Definition at line 251 of file hal_channels.h.

Referenced by bsIncomingDataI().

◆ _base_asynchronous_channel_methods

#define _base_asynchronous_channel_methods _base_channel_methods \

BaseAsynchronousChannel specific methods.

Definition at line 257 of file hal_channels.h.

◆ _base_asynchronous_channel_data

#define _base_asynchronous_channel_data

Value:

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

BaseAsynchronousChannel specific data.

Definition at line 263 of file hal_channels.h.

◆ chnGetEventSource

#define chnGetEventSource ( ip )

Value:

(&((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 304 of file hal_channels.h.

◆ chnAddFlagsI

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

Referenced by __bsio_default_cb(), __bsio_push_data(), bsIncomingDataI(), bsRequestDataI(), sdIncomingDataI(), sdRequestDataI(), sduConfigureHookI(), sduDataReceived(), sduDataTransmitted(), sduStop(), sduSuspendHookI(), and sduWakeupHookI().

Detailed Description

Default control operation codes.

Macro Functions (BaseChannel)

I/O status flags added to the event listener

Macro Functions (BaseAsynchronousChannel)

Data Structures

Macros

Macro Definition Documentation

◆ CHN_CTL_INVALID

◆ CHN_CTL_NOP

◆ CHN_CTL_TX_WAIT

◆ _base_channel_methods

◆ _base_channel_data

◆ chnPutTimeout

◆ chnGetTimeout

◆ chnWrite

◆ chnWriteTimeout

◆ chnRead

◆ chnReadTimeout

◆ chnControl

◆ CHN_NO_ERROR

◆ CHN_CONNECTED

◆ CHN_DISCONNECTED

◆ CHN_INPUT_AVAILABLE

◆ CHN_OUTPUT_EMPTY

◆ CHN_TRANSMISSION_END

◆ CHN_PARITY_ERROR

◆ CHN_FRAMING_ERROR

◆ CHN_NOISE_ERROR

◆ CHN_OVERRUN_ERROR

◆ CHN_IDLE_DETECTED

◆ CHN_BREAK_DETECTED

◆ CHN_BUFFER_FULL_ERROR

◆ _base_asynchronous_channel_methods

◆ _base_asynchronous_channel_data

◆ chnGetEventSource

◆ chnAddFlagsI