I/O Channels
[I/O Support]

Collaboration diagram for I/O Channels:

---

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.

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...
Defines
#define	_base_channel_methods
	BaseChannel specific methods.
#define	_base_channel_data   _base_sequental_stream_data
	BaseChannel specific data.
#define	chIOPutWouldBlock(ip)   ((ip)->vmt->putwouldblock(ip))
	Channel output check.
#define	chIOGetWouldBlock(ip)   ((ip)->vmt->getwouldblock(ip))
	Channel input check.
#define	chIOPut(ip, b)   ((ip)->vmt->put(ip, b, TIME_INFINITE))
	Channel blocking byte write.
#define	chIOPutTimeout(ip, b, time)   ((ip)->vmt->put(ip, b, time))
	Channel blocking byte write with timeout.
#define	chIOGet(ip)   ((ip)->vmt->get(ip, TIME_INFINITE))
	Channel blocking byte read.
#define	chIOGetTimeout(ip, time)   ((ip)->vmt->get(ip, time))
	Channel blocking byte read with timeout.
#define	chIOWriteTimeout(ip, bp, n, time)   ((ip)->vmt->writet(ip, bp, n, time))
	Channel blocking write with timeout.
#define	chIOReadTimeout(ip, bp, n, time)   ((ip)->vmt->readt(ip, bp, n, time))
	Channel blocking read with timeout.
#define	_base_asynchronous_channel_methods   _base_channel_methods
	BaseAsynchronousChannel specific methods.
#define	_base_asynchronous_channel_data
	BaseAsynchronousChannel specific data.
#define	chIOGetWriteEventSource(ip)   (&((ip)->vmt->oevent))
	Returns the write event source.
#define	chIOGetReadEventSource(ip)   (&((ip)->vmt->ievent))
	Returns the read event source.

---

Define Documentation

#define _base_channel_methods

Value:

_base_sequental_stream_methods                                            \
  /* Channel output check.*/                                                \
  bool_t (*putwouldblock)(void *instance);                                  \
  /* Channel input check.*/                                                 \
  bool_t (*getwouldblock)(void *instance);                                  \
  /* Channel put method with timeout specification.*/                       \
  msg_t (*put)(void *instance, uint8_t b, systime_t time);                  \
  /* Channel get method with timeout specification.*/                       \
  msg_t (*get)(void *instance, systime_t time);                             \
  /* Channel write method with timeout specification.*/                     \
  size_t (*writet)(void *instance, const uint8_t *bp,                       \
                  size_t n, systime_t time);                                \
  /* Channel read method with timeout specification.*/                      \
  size_t (*readt)(void *instance, uint8_t *bp, size_t n, systime_t time);

BaseChannel specific methods.

Definition at line 51 of file chioch.h.

#define _base_channel_data   _base_sequental_stream_data

BaseChannel specific data.

Note:

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

Definition at line 72 of file chioch.h.

#define chIOPutWouldBlock

(

ip

)

((ip)->vmt->putwouldblock(ip))

Channel output check.

This function verifies if a subsequent put/write operation would block.

Parameters:

[in]

ip

pointer to a BaseChannel or derived class

Returns:

The output queue status:

Return values:

	FALSE	if the output queue has space and would not block a write operation.
	TRUE	if the output queue is full and would block a write operation.

Definition at line 107 of file chioch.h.

#define chIOGetWouldBlock

(

ip

)

((ip)->vmt->getwouldblock(ip))

Channel input check.

This function verifies if a subsequent get/read operation would block.

Parameters:

[in]

ip

pointer to a BaseChannel or derived class

Returns:

The input queue status:

Return values:

	FALSE	if the input queue contains data and would not block a read operation.
	TRUE	if the input queue is empty and would block a read operation.

Definition at line 121 of file chioch.h.

#define chIOPut	(	ip,
		b		)	((ip)->vmt->put(ip, b, TIME_INFINITE))

Channel blocking byte write.

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

Returns:

The operation status:

Return values:

	Q_OK	if the operation succeeded.
	Q_RESET	if the channel associated queue (if any) was reset.

Definition at line 134 of file chioch.h.

#define chIOPutTimeout	(	ip,
		b,
		time		)	((ip)->vmt->put(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:

	Q_OK	if the operation succeeded.
	Q_TIMEOUT	if the specified time expired.
	Q_RESET	if the channel associated queue (if any) was reset.

Definition at line 153 of file chioch.h.

#define chIOGet

(

ip

)

((ip)->vmt->get(ip, TIME_INFINITE))

Channel blocking byte read.

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

Returns:

A byte value from the queue or:

Return values:

Q_RESET

if the channel associated queue (if any) was reset.

Definition at line 164 of file chioch.h.

#define chIOGetTimeout	(	ip,
		time		)	((ip)->vmt->get(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 or:

Return values:

	Q_TIMEOUT	if the specified time expired.
	Q_RESET	if the channel associated queue (if any) was reset.

Definition at line 181 of file chioch.h.

#define chIOWriteTimeout	(	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.

Definition at line 198 of file chioch.h.

#define chIOReadTimeout	(	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.

Definition at line 216 of file chioch.h.

#define _base_asynchronous_channel_methods   _base_channel_methods

BaseAsynchronousChannel specific methods.

Definition at line 223 of file chioch.h.

#define _base_asynchronous_channel_data

Value:

_base_channel_data                                                        \
  /* Data Available EventSource.*/                                          \
  EventSource           ievent;                                             \
  /* Data Transmitted EventSource.*/                                        \
  EventSource           oevent;

BaseAsynchronousChannel specific data.

Definition at line 229 of file chioch.h.

#define chIOGetWriteEventSource

(

ip

)

(&((ip)->vmt->oevent))

Returns the write event source.

The write event source is broadcasted when the channel is ready for write operations. This usually happens when the internal output queue becomes empty.

Parameters:

[in]

ip

pointer to a BaseAsynchronousChannel or derived class

Returns:

A pointer to an EventSource object.

Definition at line 266 of file chioch.h.

#define chIOGetReadEventSource

(

ip

)

(&((ip)->vmt->ievent))

Returns the read event source.

The read event source is broadcasted when the channel is ready for read operations. This usually happens when the internal input queue becomes non-empty.

Parameters:

[in]

ip

pointer to a BaseAsynchronousChannel or derived class

Returns:

A pointer to an EventSource object.

Definition at line 278 of file chioch.h.