O Support]

Collaboration diagram for I/O Queues:

Description

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:

Input queue, unidirectional queue where the writer is the lower side and the reader is the upper side.
Output queue, unidirectional queue where the writer is the upper side and the reader is the lower side.
Full duplex queue, bidirectional queue. Full duplex queues are implemented by pairing an input queue and an output queue together.

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 Documentation

#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 chIQPutI(), chOQPutTimeout(), 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.

Referenced by chOQGetI().

#define Q_FULL -4

Returned by the queue functions if the queue is full.

Definition at line 59 of file chqueues.h.

Referenced by chIQPutI().

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

Note:: The returned value can be less than zero when there are waiting threads on the internal semaphore.

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.

Parameters:

[in] iqp pointer to an InputQueue structure

Returns:: A byte value from the queue or:

Return values:

Q_RESET

if the queue was reset.

Definition at line 123 of file chqueues.h.

#define _INPUTQUEUE_DATA	(	name,
		buffer,
		size,
		inotify	)

Value:

{                 \
  (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.

Parameters:

`[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().

Parameters:

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

Parameters:

`[in]`	oqp	pointer to an `OutputQueue` structure
`[in]`	b	the byte value to be written in the queue

Returns:: The operation status:

Return values:

	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	)

Value:

{                \
  (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.

Parameters:

`[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().

Parameters:

`[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 Documentation

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.

Function Documentation

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.

Note:: The callback is invoked from within the S-Locked system state, see System States.

Parameters:

`[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().

Here is the call graph for this function:

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.

Note:: A reset operation can be used by a low level driver in order to obtain immediate attention from the high level layers.

Parameters:

[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().

Here is the call graph for this function:

msg_t chIQPutI	(	InputQueue *	iqp,
		uint8_t	b
	)

Input queue write.

A byte value is written into the low end of an input queue.

Parameters:

`[in]`	iqp	pointer to an `InputQueue` structure
`[in]`	b	the byte value to be written in the queue

Returns:: The operation status, it can be one of:

Return values:

	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, Q_FULL, Q_OK, GenericQueue::q_sem, GenericQueue::q_top, and GenericQueue::q_wrptr.

Referenced by sdIncomingDataI().

Here is the call graph for this function:

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.

Parameters:

[in] iqp pointer to an InputQueue structure

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

Here is the call graph for this function:

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.

Note:: The function is not atomic, if you need atomicity it is suggested to use a semaphore or a mutex for mutual exclusion.; The queue callback is invoked before entering a sleep state and at the end of the transfer.

Parameters:

`[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: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns:: The number of bytes effectively transferred.

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.

Here is the call graph for this function:

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.

Note:: The callback is invoked from within the S-Locked system state, see System States.

Parameters:

`[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().

Here is the call graph for this function:

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.

Note:: A reset operation can be used by a low level driver in order to obtain immediate attention from the high level layers.

Parameters:

[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().

Here is the call graph for this function:

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.

Parameters:

[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:

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 queue was reset.

Definition at line 265 of file chqueues.c.

References chSemWaitTimeoutS(), chSysLock, chSysUnlock, GenericQueue::q_buffer, GenericQueue::q_notify, Q_OK, GenericQueue::q_sem, GenericQueue::q_top, GenericQueue::q_wrptr, and RDY_OK.

Here is the call graph for this function:

msg_t chOQGetI ( OutputQueue * oqp )

Output queue read.

A byte value is read from the low end of an output queue.

Parameters:

[in] oqp pointer to an OutputQueue structure

Returns:: The byte value from the queue or:

Return values:

Q_EMPTY

if the queue is empty.

Definition at line 292 of file chqueues.c.

References chOQIsEmpty, chSemSignalI(), GenericQueue::q_buffer, Q_EMPTY, GenericQueue::q_rdptr, GenericQueue::q_sem, and GenericQueue::q_top.

Referenced by sdRequestDataI().

Here is the call graph for this function:

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.

Note:: The function is not atomic, if you need atomicity it is suggested to use a semaphore or a mutex for mutual exclusion.; The queue callback is invoked before entering a sleep state and at the end of the transfer.

Parameters:

`[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: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns:: The number of bytes effectively transferred.

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.

Here is the call graph for this function:

I/O Queues [I/O Support]

Description

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

I/O Queues
[I/O Support]