diff options
Diffstat (limited to 'os/kernel/include/channels.h')
| -rw-r--r-- | os/kernel/include/channels.h | 176 |
1 files changed, 90 insertions, 86 deletions
diff --git a/os/kernel/include/channels.h b/os/kernel/include/channels.h index 2aa8cb0f6..7e275af96 100644 --- a/os/kernel/include/channels.h +++ b/os/kernel/include/channels.h @@ -20,6 +20,8 @@ /**
* @file channels.h
* @brief I/O channels.
+ * @details This header defines abstract interfaces useful to access generic
+ * I/O resources in a standardized way.
*
* @addtogroup io_channels
* @{
@@ -29,7 +31,7 @@ #define _CHANNELS_H_
/**
- * @brief @p BaseChannel specific methods.
+ * @brief @p BaseChannel specific methods.
*/
#define _base_channel_methods \
_base_sequental_stream_methods \
@@ -48,15 +50,15 @@ size_t (*readt)(void *instance, uint8_t *bp, size_t n, systime_t time);
/**
- * @brief @p BaseChannel specific data.
- * @note It is empty because @p BaseChannel is only an interface without
- * implementation.
+ * @brief @p BaseChannel specific data.
+ * @note It is empty because @p BaseChannel is only an interface without
+ * implementation.
*/
#define _base_channel_data \
_base_sequental_stream_data
/**
- * @brief @p BaseChannel virtual methods table.
+ * @brief @p BaseChannel virtual methods table.
*/
struct BaseChannelVMT { \
_base_channel_methods \
@@ -65,149 +67,149 @@ struct BaseChannelVMT { \ /**
* @extends BaseSequentialStream
*
- * @brief Base channel class.
+ * @brief Base channel class.
* @details This class represents a generic, byte-wide, I/O channel. This class
* introduces generic I/O primitives with timeout specification.
*/
typedef struct {
- /**
- * Virtual Methods Table.
- */
+ /** @brief Virtual Methods Table.*/
const struct BaseChannelVMT *vmt;
_base_channel_data
} BaseChannel;
/**
- * @brief Channel output check.
+ * @brief Channel output check.
* @details This function verifies if a subsequent put/write operation would
* block.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @return The output queue status:
- * @retval FALSE if the output queue has space and would not block a write
- * operation.
- * @retval TRUE if the output queue is full and would block a write operation.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @return The output queue status:
+ * @retval FALSE if the output queue has space and would not block a
+ * write operation.
+ * @retval TRUE if the output queue is full and would block a write
+ * operation.
*/
#define chIOPutWouldBlock(ip) ((ip)->vmt->putwouldblock(ip))
/**
- * @brief Channel input check.
+ * @brief Channel input check.
* @details This function verifies if a subsequent get/read operation would
* block.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @return The input queue status:
- * @retval FALSE if the input queue contains data and would not block a read
- * operation.
- * @retval TRUE if the input queue is empty and would block a read operation.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @return The input queue status:
+ * @retval FALSE if the input queue contains data and would not block a
+ * read operation.
+ * @retval TRUE if the input queue is empty and would block a read
+ * operation.
*/
#define chIOGetWouldBlock(ip) ((ip)->vmt->getwouldblock(ip))
/**
- * @brief Channel blocking byte write.
+ * @brief Channel blocking byte write.
* @details This function writes a byte value to a channel. If the channel
* is not ready to accept data then the calling thread is suspended.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @param[in] b the byte value to be written to the channel
- * @return The operation status:
- * @retval Q_OK if the operation succeeded.
- * @retval Q_RESET if the channel associated queue (if any) was reset.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @param[in] b the byte value to be written to the channel
+ * @return The operation status:
+ * @retval Q_OK if the operation succeeded.
+ * @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOPut(ip, b) ((ip)->vmt->put(ip, b, TIME_INFINITE))
/**
- * @brief Channel blocking byte write with timeout.
+ * @brief Channel blocking byte write with timeout.
* @details This function writes a byte value to a channel. If the channel
* is not ready to accept data then the calling thread is suspended.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @param[in] b the byte value to be written to the channel
- * @param[in] time the number of ticks before the operation timeouts,
- * the following special values are allowed:
- * - @a TIME_IMMEDIATE immediate timeout.
- * - @a TIME_INFINITE no timeout.
- * .
- * @return The operation status:
- * @retval Q_OK if the operation succeeded.
- * @retval Q_TIMEOUT if the specified time expired.
- * @retval Q_RESET if the channel associated queue (if any) was reset.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @param[in] b the byte value to be written to the channel
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return The operation status:
+ * @retval Q_OK if the operation succeeded.
+ * @retval Q_TIMEOUT if the specified time expired.
+ * @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOPutTimeout(ip, b, time) ((ip)->vmt->put(ip, b, time))
/**
- * @brief Channel blocking byte read.
+ * @brief Channel blocking byte read.
* @details This function reads a byte value from a channel. If the data
* is not available then the calling thread is suspended.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @return A byte value from the queue or:
- * @retval Q_RESET if the channel associated queue (if any) was reset.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @return A byte value from the queue or:
+ * @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOGet(ip) ((ip)->vmt->get(ip, TIME_INFINITE))
/**
- * @brief Channel blocking byte read with timeout.
+ * @brief Channel blocking byte read with timeout.
* @details This function reads a byte value from a channel. If the data
* is not available then the calling thread is suspended.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @param[in] time the number of ticks before the operation timeouts,
- * the following special values are allowed:
- * - @a TIME_IMMEDIATE immediate timeout.
- * - @a TIME_INFINITE no timeout.
- * .
- * @return A byte value from the queue or:
- * @retval Q_TIMEOUT if the specified time expired.
- * @retval Q_RESET if the channel associated queue (if any) was reset.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return A byte value from the queue or:
+ * @retval Q_TIMEOUT if the specified time expired.
+ * @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOGetTimeout(ip, time) ((ip)->vmt->get(ip, time))
/**
- * @brief Channel blocking write with timeout.
+ * @brief Channel blocking write with timeout.
* @details 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.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @param[out] bp pointer to the data buffer
- * @param[in] n the maximum amount of data to be transferred
- * @param[in] time the number of ticks before the operation timeouts,
- * the following special values are allowed:
- * - @a TIME_IMMEDIATE immediate timeout.
- * - @a TIME_INFINITE no timeout.
- * .
- * @return The number of bytes transferred.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @param[out] bp pointer to the data buffer
+ * @param[in] n the maximum amount of data to be transferred
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return The number of bytes transferred.
*/
#define chIOWriteTimeout(ip, bp, n, time) \
((ip)->vmt->write(ip, bp, n, time))
/**
- * @brief Channel blocking read with timeout.
+ * @brief Channel blocking read with timeout.
* @details The function reads data from a channel into a buffer. If the data
* is not available then the calling thread is suspended.
*
- * @param[in] ip pointer to a @p BaseChannel or derived class
- * @param[in] bp pointer to the data buffer
- * @param[in] n the maximum amount of data to be transferred
- * @param[in] time the number of ticks before the operation timeouts,
- * the following special values are allowed:
- * - @a TIME_IMMEDIATE immediate timeout.
- * - @a TIME_INFINITE no timeout.
- * .
- * @return The number of bytes transferred.
+ * @param[in] ip pointer to a @p BaseChannel or derived class
+ * @param[in] bp pointer to the data buffer
+ * @param[in] n the maximum amount of data to be transferred
+ * @param[in] time the number of ticks before the operation timeouts,
+ * the following special values are allowed:
+ * - @a TIME_IMMEDIATE immediate timeout.
+ * - @a TIME_INFINITE no timeout.
+ * .
+ * @return The number of bytes transferred.
*/
#define chIOReadTimeout(ip, bp, n, time) \
((ip)->vmt->read(ip, bp, n, time))
#if CH_USE_EVENTS
/**
- * @brief @p BaseAsynchronousChannel specific methods.
+ * @brief @p BaseAsynchronousChannel specific methods.
*/
#define _base_asynchronous_channel_methods \
_base_channel_methods
/**
- * @brief @p BaseAsynchronousChannel specific data.
+ * @brief @p BaseAsynchronousChannel specific data.
*/
#define _base_asynchronous_channel_data \
_base_channel_data \
@@ -217,7 +219,7 @@ typedef struct { EventSource oevent;
/**
- * @brief @p BaseAsynchronousChannel virtual methods table.
+ * @brief @p BaseAsynchronousChannel virtual methods table.
*/
struct BaseAsynchronousChannelVMT {
_base_asynchronous_channel_methods
@@ -226,35 +228,37 @@ struct BaseAsynchronousChannelVMT { /**
* @extends BaseChannel
*
- * @brief Base asynchronous channel class.
+ * @brief Base asynchronous channel class.
* @details This class extends @p BaseChannel by adding event sources fields
* for asynchronous I/O for use in an event-driven environment.
*/
typedef struct {
- /**
- * Virtual Methods Table.
- */
+ /** @brief Virtual Methods Table.*/
const struct BaseAsynchronousChannelVMT *vmt;
_base_asynchronous_channel_data
} BaseAsynchronousChannel;
/**
- * @brief Returns the write event source.
+ * @brief Returns the write event source.
* @details The write event source is broadcasted when the channel is ready
* for write operations. This usually happens when the internal
* output queue becomes empty.
- * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived class
- * @return A pointer to an @p EventSource object.
+ *
+ * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived
+ * class
+ * @return A pointer to an @p EventSource object.
*/
#define chIOGetWriteEventSource(ip) (&((ip)->vmt->oevent))
/**
- * @brief Returns the read event source.
+ * @brief Returns the read event source.
* @details 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.
- * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived class
- * @return A pointer to an @p EventSource object.
+ *
+ * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived
+ * class
+ * @return A pointer to an @p EventSource object.
*/
#define chIOGetReadEventSource(ip) (&((ip)->vmt->ievent))
|