diff --git a/src/include/channels.h b/src/include/channels.h index ef3600893..dd2cd3301 100644 --- a/src/include/channels.h +++ b/src/include/channels.h @@ -32,21 +32,13 @@ */ struct _base_channel_methods { /** - * @brief Channel synchronous put method. - * @param[in] b the byte value to be written in the queue - * @param[in] timeout 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 queue was reset. + * @brief Channel put method with timeout specification. + * @see chIOPut() */ msg_t (*put)(void *instance, uint8_t b, systime_t timeout); /** - * Channel synchronous get method. + * @brief Channel get method with timeout specification. + * @see chIOGet() */ msg_t (*get)(void *instance, systime_t timeout); }; @@ -68,14 +60,73 @@ struct _base_channel_vmt { /** * @brief Base channel class. - * @details This class represents a generic, synchronous, byte-wide, - * I/O channel. + * @details This class represents a generic, byte-wide, I/O channel. */ typedef struct { struct _base_channel_vmt *vmt; /**< Virtual Methods Table. */ struct _base_channel_data d0; /**< Class data. */ } BaseChannel; +/** + * @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. + */ +#define chIOPut(ip, b) ((ip)->vmt.m0->put(ip, b, TIME_INFINITE)) + +/** + * @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] timeout 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, timeout) ((ip)->vmt.m0->put(ip, b, timeout)) + +/** + * @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. + */ +#define chIOGet(ip) ((ip)->vmt.m0->put(ip, TIME_INFINITE)) + +/** + * @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] timeout 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, timeout) ((ip)->vmt.m0->put(ip, timeout)) + #if CH_USE_EVENTS /** * @brief Virtual methods table for base asynchronous channels. @@ -83,12 +134,14 @@ typedef struct { struct _base_asynchronous_channel_methods { /** * Channel asynchronous write method. + * @see chIOWrite() */ - size_t (*write)(void *instance, uint8_t *bp, size_t n); + size_t (*write)(void *instance, uint8_t *buffer, size_t n); /** * Channel asynchronous read method. + * @see chIORead() */ - size_t (*read)(void *instance, uint8_t *bp, size_t n); + size_t (*read)(void *instance, uint8_t *buffer, size_t n); }; /** @@ -115,7 +168,6 @@ struct _base_asynchronous_channel_vmt { struct _base_asynchronous_channel_methods m1; /**< Class methods. */ }; - /** * @extends BaseChannel * @@ -128,6 +180,33 @@ typedef struct { struct _base_channel_data d0; /**< Super class data. */ struct _base_asynchronous_channel_data d1; /**< Class data. */ } BaseAsynchronousChannel; + +/** + * @brief Channel non-blocking write. + * @details The function writes data from a buffer to a channel. The + * transfer is non-blocking and can return zero if the channel is + * not read to accept data. + * + * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived class + * @param[out] bp pointer to the buffer where the data is stored + * @param[in] n the maximum amount of data to be transferred + * @return The number of bytes transferred. + */ +#define chIOWrite(ip, bp, n) ((ip)->vmt.m1->write(ip, bp, n)) + +/** + * @brief Channel non-blocking read. + * @details The function reads data from a channel into a buffer. The + * transfer is non-blocking and can return zero if the channel has + * no data immediately available. + * + * @param[in] ip pointer to a @p BaseChannel or derived class + * @param[out] bp pointer to the buffer where the input data is copied + * @param[in] n the maximum amount of data to be transferred + * @return The number of bytes transferred. + */ +#define chIORead(ip, bp, n) ((ip)->vmt.m1->read(ip, bp, n)) + #endif /* CH_USE_EVENTS */ #endif /* _CHANNELS_H_ */ diff --git a/src/templates/chconf.h b/src/templates/chconf.h index f06a537b2..9909a60d3 100644 --- a/src/templates/chconf.h +++ b/src/templates/chconf.h @@ -246,7 +246,7 @@ * If specified then the full duplex serial driver APIs are included in the * kernel. * @note The default is @p TRUE. - * @note Requires @p CH_USE_QUEUES. + * @note Requires @p CH_USE_QUEUES and @p CH_USE_EVENTS. */ #if !defined(CH_USE_SERIAL_FULLDUPLEX) || defined(__DOXYGEN__) #define CH_USE_SERIAL_FULLDUPLEX TRUE