ChibiOS/RT Architecture - Reference Manual - Guides |
ChibiOS/RT queues are mostly used in serial-like device drivers. The device drivers are usually designed to have a lower side (lower driver, it is usually an interrupt service routine) and an upper side (upper driver, accessed by the application threads).
There are several kind of queues:
In order to use the I/O queues the CH_USE_QUEUES
option must be enabled in chconf.h
.
I/O queues are usually used as an implementation layer for the I/O channels interface, also see I/O Channels.
Data Structures | |
struct | GenericQueue |
Generic I/O queue structure. More... | |
Defines | |
#define | Q_OK RDY_OK |
Returned by the queue functions if the operation is successful. | |
#define | Q_TIMEOUT RDY_TIMEOUT |
Returned by the queue functions if a timeout occurs. | |
#define | Q_RESET RDY_RESET |
Returned by the queue functions if the queue is reset. | |
#define | Q_EMPTY -3 |
Returned by the queue functions if the queue is empty. | |
#define | Q_FULL -4 |
Returned by the queue functions if the queue is full. | |
#define | chQSize(q) ((q)->q_top - (q)->q_buffer) |
Returns the queue's buffer size. | |
#define | chQSpace(q) chSemGetCounterI(&(q)->q_sem) |
Queue space. | |
#define | chIQIsEmpty(q) ((bool_t)(chQSpace(q) <= 0)) |
Evaluates to TRUE if the specified Input Queue is empty. | |
#define | chIQIsFull(q) ((bool_t)(chQSpace(q) >= chQSize(q))) |
Evaluates to TRUE if the specified Input Queue is full. | |
#define | chIQGet(iqp) chIQGetTimeout(iqp, TIME_INFINITE) |
Input queue read. | |
#define | _INPUTQUEUE_DATA(name, buffer, size, inotify) |
Data part of a static input queue initializer. | |
#define | INPUTQUEUE_DECL(name, buffer, size, inotify) InputQueue name = _INPUTQUEUE_DATA(name, buffer, size, inotify) |
Static input queue initializer. | |
#define | chOQIsEmpty(q) ((bool_t)(chQSpace(q) >= chQSize(q))) |
Evaluates to TRUE if the specified Output Queue is empty. | |
#define | chOQIsFull(q) ((bool_t)(chQSpace(q) <= 0)) |
Evaluates to TRUE if the specified Output Queue is full. | |
#define | chOQPut(oqp, b) chOQPutTimeout(oqp, b, TIME_INFINITE) |
Output queue write. | |
#define | _OUTPUTQUEUE_DATA(name, buffer, size, onotify) |
Data part of a static output queue initializer. | |
#define | OUTPUTQUEUE_DECL(name, buffer, size, onotify) InputQueue name = _OUTPUTQUEUE_DATA(name, buffer, size, onotify) |
Static output queue initializer. | |
Typedefs | |
typedef void(* | qnotify_t )(void) |
Queue notification callback type. | |
typedef GenericQueue | InputQueue |
Input queue structure. | |
typedef GenericQueue | OutputQueue |
Output queue structure. | |
Functions | |
void | chIQInit (InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) |
Initializes an input queue. | |
void | chIQResetI (InputQueue *iqp) |
Resets an input queue. | |
msg_t | chIQPutI (InputQueue *iqp, uint8_t b) |
Input queue write. | |
msg_t | chIQGetTimeout (InputQueue *iqp, systime_t time) |
Input queue read with timeout. | |
size_t | chIQReadTimeout (InputQueue *iqp, uint8_t *bp, size_t n, systime_t time) |
Input queue read with timeout. | |
void | chOQInit (OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) |
Initializes an output queue. | |
void | chOQResetI (OutputQueue *oqp) |
Resets an output queue. | |
msg_t | chOQPutTimeout (OutputQueue *oqp, uint8_t b, systime_t time) |
Output queue write with timeout. | |
msg_t | chOQGetI (OutputQueue *oqp) |
Output queue read. | |
size_t | chOQWriteTimeout (OutputQueue *oqp, const uint8_t *bp, size_t n, systime_t time) |
Output queue write with timeout. |
#define Q_OK RDY_OK |
Returned by the queue functions if the operation is successful.
Definition at line 51 of file chqueues.h.
Referenced by sdIncomingDataI(), and sdRequestDataI().
#define Q_TIMEOUT RDY_TIMEOUT |
Returned by the queue functions if a timeout occurs.
Definition at line 53 of file chqueues.h.
#define Q_RESET RDY_RESET |
Returned by the queue functions if the queue is reset.
Definition at line 55 of file chqueues.h.
#define Q_EMPTY -3 |
Returned by the queue functions if the queue is empty.
Definition at line 57 of file chqueues.h.
#define Q_FULL -4 |
Returned by the queue functions if the queue is full.
Definition at line 59 of file chqueues.h.
#define chQSize | ( | q | ) | ((q)->q_top - (q)->q_buffer) |
Returns the queue's buffer size.
Definition at line 83 of file chqueues.h.
#define chQSpace | ( | q | ) | chSemGetCounterI(&(q)->q_sem) |
Queue space.
Returns the used space if used on an Input Queue and the empty space if used on an Output Queue.
Definition at line 92 of file chqueues.h.
#define chIQIsEmpty | ( | q | ) | ((bool_t)(chQSpace(q) <= 0)) |
Evaluates to TRUE
if the specified Input Queue is empty.
Definition at line 108 of file chqueues.h.
Referenced by chIQReadTimeout(), and sdIncomingDataI().
#define chIQIsFull | ( | q | ) | ((bool_t)(chQSpace(q) >= chQSize(q))) |
Evaluates to TRUE
if the specified Input Queue is full.
Definition at line 111 of file chqueues.h.
Referenced by chIQPutI().
#define chIQGet | ( | iqp | ) | chIQGetTimeout(iqp, TIME_INFINITE) |
Input queue read.
This function reads a byte value from an input queue. If the queue is empty then the calling thread is suspended until a byte arrives in the queue.
[in] | iqp | pointer to an InputQueue structure |
Q_RESET | if the queue was reset. |
Definition at line 123 of file chqueues.h.
#define _INPUTQUEUE_DATA | ( | name, | ||
buffer, | ||||
size, | ||||
inotify | ||||
) |
{ \ (uint8_t *)(buffer), \ (uint8_t *)(buffer) + size, \ (uint8_t *)(buffer), \ (uint8_t *)(buffer), \ _SEMAPHORE_DATA(name.q_sem, 0), \ inotify \ }
Data part of a static input queue initializer.
This macro should be used when statically initializing an input queue that is part of a bigger structure.
[in] | name | the name of the input queue variable |
[in] | buffer | pointer to the queue buffer area |
[in] | size | size of the queue buffer area |
[in] | inotify | input notification callback pointer |
Definition at line 135 of file chqueues.h.
#define INPUTQUEUE_DECL | ( | name, | ||
buffer, | ||||
size, | ||||
inotify | ||||
) | InputQueue name = _INPUTQUEUE_DATA(name, buffer, size, inotify) |
Static input queue initializer.
Statically initialized input queues require no explicit initialization using chIQInit()
.
[in] | name | the name of the input queue variable |
[in] | buffer | pointer to the queue buffer area |
[in] | size | size of the queue buffer area |
[in] | inotify | input notification callback pointer |
Definition at line 154 of file chqueues.h.
#define chOQIsEmpty | ( | q | ) | ((bool_t)(chQSpace(q) >= chQSize(q))) |
Evaluates to TRUE
if the specified Output Queue is empty.
Definition at line 173 of file chqueues.h.
Referenced by chOQGetI().
#define chOQIsFull | ( | q | ) | ((bool_t)(chQSpace(q) <= 0)) |
Evaluates to TRUE
if the specified Output Queue is full.
Definition at line 178 of file chqueues.h.
Referenced by chOQWriteTimeout().
#define chOQPut | ( | oqp, | ||
b | ||||
) | chOQPutTimeout(oqp, b, TIME_INFINITE) |
Output queue write.
This function writes a byte value to an output queue. If the queue is full then the calling thread is suspended until there is space in the queue.
[in] | oqp | pointer to an OutputQueue structure |
[in] | b | the byte value to be written in the queue |
Q_OK | if the operation succeeded. | |
Q_RESET | if the queue was reset. |
Definition at line 192 of file chqueues.h.
#define _OUTPUTQUEUE_DATA | ( | name, | ||
buffer, | ||||
size, | ||||
onotify | ||||
) |
{ \ (uint8_t *)(buffer), \ (uint8_t *)(buffer) + size, \ (uint8_t *)(buffer), \ (uint8_t *)(buffer), \ _SEMAPHORE_DATA(name.q_sem, size), \ onotify \ }
Data part of a static output queue initializer.
This macro should be used when statically initializing an output queue that is part of a bigger structure.
[in] | name | the name of the output queue variable. |
[in] | buffer | pointer to the queue buffer area |
[in] | size | size of the queue buffer area |
[in] | onotify | output notification callback pointer |
Definition at line 204 of file chqueues.h.
#define OUTPUTQUEUE_DECL | ( | name, | ||
buffer, | ||||
size, | ||||
onotify | ||||
) | InputQueue name = _OUTPUTQUEUE_DATA(name, buffer, size, onotify) |
Static output queue initializer.
Statically initialized output queues require no explicit initialization using chOQInit()
.
[in] | name | the name of the output queue variable |
[in] | buffer | pointer to the queue buffer area |
[in] | size | size of the queue buffer area |
[in] | onotify | output notification callback pointer |
Definition at line 223 of file chqueues.h.
typedef void(* qnotify_t)(void) |
Queue notification callback type.
Definition at line 48 of file chqueues.h.
typedef GenericQueue InputQueue |
Input queue structure.
This structure represents a generic asymmetrical input queue. Writing in the queue is non-blocking and can be performed from interrupt handlers or from within a kernel lock zone (see I-Locked and S-Locked states in System States). Reading the queue can be a blocking operation and is supposed to be performed by a system thread.
Definition at line 105 of file chqueues.h.
typedef GenericQueue OutputQueue |
Output queue structure.
This structure represents a generic asymmetrical output queue. Reading from the queue is non-blocking and can be performed from interrupt handlers or from within a kernel lock zone (see I-Locked and S-Locked states in System States). Writing the queue can be a blocking operation and is supposed to be performed by a system thread.
Definition at line 168 of file chqueues.h.
void chIQInit | ( | InputQueue * | iqp, | |
uint8_t * | bp, | |||
size_t | size, | |||
qnotify_t | infy | |||
) |
Initializes an input queue.
A Semaphore is internally initialized and works as a counter of the bytes contained in the queue.
[out] | iqp | pointer to an InputQueue structure |
[in] | bp | pointer to a memory area allocated as queue buffer |
[in] | size | size of the queue buffer |
[in] | infy | pointer to a callback function that is invoked when data is read from the queue. The value can be NULL . |
Definition at line 69 of file chqueues.c.
References chSemInit(), GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_rdptr, GenericQueue::q_sem, GenericQueue::q_top, and GenericQueue::q_wrptr.
Referenced by sdObjectInit().
void chIQResetI | ( | InputQueue * | iqp | ) |
Resets an input queue.
All the data in the input queue is erased and lost, any waiting thread is resumed with status Q_RESET
.
[in] | iqp | pointer to an InputQueue structure |
Definition at line 86 of file chqueues.c.
References chSemResetI(), GenericQueue::q_buffer, GenericQueue::q_rdptr, GenericQueue::q_sem, and GenericQueue::q_wrptr.
Referenced by sdStop().
msg_t chIQPutI | ( | InputQueue * | iqp, | |
uint8_t | b | |||
) |
Input queue write.
A byte value is written into the low end of an input queue.
[in] | iqp | pointer to an InputQueue structure |
[in] | b | the byte value to be written in the queue |
Q_OK | if the operation has been completed with success. | |
Q_FULL | if the queue is full and the operation cannot be completed. |
Definition at line 103 of file chqueues.c.
References chIQIsFull, chSemSignalI(), GenericQueue::q_buffer, GenericQueue::q_sem, GenericQueue::q_top, and GenericQueue::q_wrptr.
Referenced by sdIncomingDataI().
msg_t chIQGetTimeout | ( | InputQueue * | iqp, | |
systime_t | time | |||
) |
Input queue read with timeout.
This function reads a byte value from an input queue. If the queue is empty then the calling thread is suspended until a byte arrives in the queue or a timeout occurs.
[in] | iqp | pointer to an InputQueue structure |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
Q_TIMEOUT | if the specified time expired. | |
Q_RESET | if the queue was reset. |
Definition at line 131 of file chqueues.c.
References chSemWaitTimeoutS(), chSysLock, chSysUnlock, GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_rdptr, GenericQueue::q_sem, GenericQueue::q_top, and RDY_OK.
size_t chIQReadTimeout | ( | InputQueue * | iqp, | |
uint8_t * | bp, | |||
size_t | n, | |||
systime_t | time | |||
) |
Input queue read with timeout.
The function reads data from an input queue into a buffer. The operation completes when the specified amount of data has been transferred or after the specified timeout or if the queue has been reset.
[in] | iqp | pointer to an InputQueue structure |
[out] | bp | pointer to the data buffer |
[in] | n | the maximum amount of data to be transferred, the value 0 is reserved |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
Definition at line 174 of file chqueues.c.
References chDbgCheck, chIQIsEmpty, chSemFastWaitI, chSemWaitTimeoutS(), chSysLock, chSysUnlock, GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_rdptr, GenericQueue::q_sem, GenericQueue::q_top, and RDY_OK.
void chOQInit | ( | OutputQueue * | oqp, | |
uint8_t * | bp, | |||
size_t | size, | |||
qnotify_t | onfy | |||
) |
Initializes an output queue.
A Semaphore is internally initialized and works as a counter of the free bytes in the queue.
[out] | oqp | pointer to an OutputQueue structure |
[in] | bp | pointer to a memory area allocated as queue buffer |
[in] | size | size of the queue buffer |
[in] | onfy | pointer to a callback function that is invoked when data is written to the queue. The value can be NULL . |
Definition at line 224 of file chqueues.c.
References chSemInit(), GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_rdptr, GenericQueue::q_sem, GenericQueue::q_top, and GenericQueue::q_wrptr.
Referenced by sdObjectInit().
void chOQResetI | ( | OutputQueue * | oqp | ) |
Resets an output queue.
All the data in the output queue is erased and lost, any waiting thread is resumed with status Q_RESET
.
[in] | oqp | pointer to an OutputQueue structure |
Definition at line 241 of file chqueues.c.
References chSemResetI(), GenericQueue::q_buffer, GenericQueue::q_rdptr, GenericQueue::q_sem, GenericQueue::q_top, and GenericQueue::q_wrptr.
Referenced by sdStop().
msg_t chOQPutTimeout | ( | OutputQueue * | oqp, | |
uint8_t | b, | |||
systime_t | time | |||
) |
Output queue write with timeout.
This function writes a byte value to an output queue. If the queue is full then the calling thread is suspended until there is space in the queue or a timeout occurs.
[in] | oqp | pointer to an OutputQueue structure |
[in] | b | the byte value to be written in the queue |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
Q_OK | if the operation succeeded. | |
Q_TIMEOUT | if the specified time expired. | |
Q_RESET | if the queue was reset. |
Definition at line 265 of file chqueues.c.
References chSemWaitTimeoutS(), chSysLock, chSysUnlock, GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_sem, GenericQueue::q_top, GenericQueue::q_wrptr, and RDY_OK.
msg_t chOQGetI | ( | OutputQueue * | oqp | ) |
Output queue read.
A byte value is read from the low end of an output queue.
[in] | oqp | pointer to an OutputQueue structure |
Q_EMPTY | if the queue is empty. |
Definition at line 292 of file chqueues.c.
References chOQIsEmpty, chSemSignalI(), GenericQueue::q_buffer, GenericQueue::q_rdptr, GenericQueue::q_sem, and GenericQueue::q_top.
Referenced by sdRequestDataI().
size_t chOQWriteTimeout | ( | OutputQueue * | oqp, | |
const uint8_t * | bp, | |||
size_t | n, | |||
systime_t | time | |||
) |
Output queue write with timeout.
The function writes data from a buffer to an output queue. The operation completes when the specified amount of data has been transferred or after the specified timeout or if the queue has been reset.
[in] | oqp | pointer to an OutputQueue structure |
[out] | bp | pointer to the data buffer |
[in] | n | the maximum amount of data to be transferred, the value 0 is reserved |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
Definition at line 327 of file chqueues.c.
References chDbgCheck, chOQIsFull, chSemFastWaitI, chSemWaitTimeoutS(), chSysLock, chSysUnlock, GenericQueue::q_buffer, GenericQueue::q_notify, GenericQueue::q_sem, GenericQueue::q_top, GenericQueue::q_wrptr, and RDY_OK.