Collaboration diagram for I/O Buffers Queues:

Detailed Description

Buffers Queues are used when there is the need to exchange fixed-length data buffers between ISRs and threads. On the ISR side data can be exchanged only using buffers, on the thread side data can be exchanged both using buffers and/or using an emulation of regular byte queues. There are several kind of buffers queues:

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

Macros
#define	BQ_BUFFER_SIZE(n, size) (((size_t)(size) + sizeof (size_t)) * (size_t)(n))
	Computes the size of a buffers queue buffer size. More...

Macro Functions
#define	bqSizeX(bqp) ((bqp)->bn)
	Returns the queue's number of buffers. More...

#define	bqSpaceI(bqp) ((bqp)->bcounter)
	Return the ready buffers number. More...

#define	bqGetLinkX(bqp) ((bqp)->link)
	Returns the queue application-defined link. More...

#define	bqIsSuspendedX(bqp) ((bqp)->suspended)
	Return the suspended state of the queue. More...

#define	bqSuspendI(bqp)
	Puts the queue in suspended state. More...

#define	bqResumeX(bqp)
	Resumes normal queue operations. More...

#define	ibqIsEmptyI(ibqp) ((bool)(bqSpaceI(ibqp) == 0U))
	Evaluates to `true` if the specified input buffers queue is empty. More...

#define	ibqIsFullI(ibqp)
	Evaluates to `true` if the specified input buffers queue is full. More...

#define	obqIsEmptyI(obqp)
	Evaluates to `true` if the specified output buffers queue is empty. More...

#define	obqIsFullI(obqp) ((bool)(bqSpaceI(obqp) == 0U))
	Evaluates to `true` if the specified output buffers queue is full. More...

Typedefs
typedef struct io_buffers_queue	io_buffers_queue_t
	Type of a generic queue of buffers. More...

typedef void(*	bqnotify_t) (io_buffers_queue_t *bqp)
	Double buffer notification callback type. More...

typedef io_buffers_queue_t	input_buffers_queue_t
	Type of an input buffers queue. More...

typedef io_buffers_queue_t	output_buffers_queue_t
	Type of an output buffers queue. More...

Data Structures
struct	io_buffers_queue
	Structure of a generic buffers queue. More...

Functions
void	ibqObjectInit (input_buffers_queue_t ibqp, bool suspended, uint8_t bp, size_t size, size_t n, bqnotify_t infy, void *link)
	Initializes an input buffers queue object. More...

void	ibqResetI (input_buffers_queue_t *ibqp)
	Resets an input buffers queue. More...

uint8_t *	ibqGetEmptyBufferI (input_buffers_queue_t *ibqp)
	Gets the next empty buffer from the queue. More...

void	ibqPostFullBufferI (input_buffers_queue_t *ibqp, size_t size)
	Posts a new filled buffer to the queue. More...

msg_t	ibqGetFullBufferTimeout (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Gets the next filled buffer from the queue. More...

msg_t	ibqGetFullBufferTimeoutS (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Gets the next filled buffer from the queue. More...

void	ibqReleaseEmptyBuffer (input_buffers_queue_t *ibqp)
	Releases the buffer back in the queue. More...

void	ibqReleaseEmptyBufferS (input_buffers_queue_t *ibqp)
	Releases the buffer back in the queue. More...

msg_t	ibqGetTimeout (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Input queue read with timeout. More...

size_t	ibqReadTimeout (input_buffers_queue_t ibqp, uint8_t bp, size_t n, sysinterval_t timeout)
	Input queue read with timeout. More...

void	obqObjectInit (output_buffers_queue_t obqp, bool suspended, uint8_t bp, size_t size, size_t n, bqnotify_t onfy, void *link)
	Initializes an output buffers queue object. More...

void	obqResetI (output_buffers_queue_t *obqp)
	Resets an output buffers queue. More...

uint8_t *	obqGetFullBufferI (output_buffers_queue_t obqp, size_t sizep)
	Gets the next filled buffer from the queue. More...

void	obqReleaseEmptyBufferI (output_buffers_queue_t *obqp)
	Releases the next filled buffer back in the queue. More...

msg_t	obqGetEmptyBufferTimeout (output_buffers_queue_t *obqp, sysinterval_t timeout)
	Gets the next empty buffer from the queue. More...

msg_t	obqGetEmptyBufferTimeoutS (output_buffers_queue_t *obqp, sysinterval_t timeout)
	Gets the next empty buffer from the queue. More...

void	obqPostFullBuffer (output_buffers_queue_t *obqp, size_t size)
	Posts a new filled buffer to the queue. More...

void	obqPostFullBufferS (output_buffers_queue_t *obqp, size_t size)
	Posts a new filled buffer to the queue. More...

msg_t	obqPutTimeout (output_buffers_queue_t *obqp, uint8_t b, sysinterval_t timeout)
	Output queue write with timeout. More...

size_t	obqWriteTimeout (output_buffers_queue_t obqp, const uint8_t bp, size_t n, sysinterval_t timeout)
	Output queue write with timeout. More...

bool	obqTryFlushI (output_buffers_queue_t *obqp)
	Flushes the current, partially filled, buffer to the queue. More...

void	obqFlush (output_buffers_queue_t *obqp)
	Flushes the current, partially filled, buffer to the queue. More...

Macro Definition Documentation

#define BQ_BUFFER_SIZE	(	n,
		size
	)	(((size_t)(size) + sizeof (size_t)) * (size_t)(n))

Computes the size of a buffers queue buffer size.

Parameters

[in]	n	number of buffers in the queue
[in]	size	size of the buffers

Definition at line 138 of file hal_buffers.h.

#define bqSizeX ( bqp ) ((bqp)->bn)

Returns the queue's number of buffers.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Returns: The number of buffers.

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 153 of file hal_buffers.h.

Referenced by obqResetI().

#define bqSpaceI ( bqp ) ((bqp)->bcounter)

Return the ready buffers number.

Returns the number of filled buffers if used on an input queue or the number of empty buffers if used on an output queue.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Returns: The number of ready buffers.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 165 of file hal_buffers.h.

#define bqGetLinkX ( bqp ) ((bqp)->link)

Returns the queue application-defined link.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Returns: The application-defined link.

Function Class:Special function, this function has special requirements see the notes.

Definition at line 175 of file hal_buffers.h.

Referenced by ibnotify(), and obnotify().

#define bqIsSuspendedX ( bqp ) ((bqp)->suspended)

Return the suspended state of the queue.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Returns: The suspended state.

Return values

false	if blocking access to the queue is enabled.
true	if blocking access to the queue is suspended.

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 187 of file hal_buffers.h.

#define bqSuspendI ( bqp )

Value:

{                                                   \
  (bqp)->suspended = true;                                                  \
  osalThreadDequeueAllI(&(bqp)->waiting, MSG_RESET);                        \
}

Puts the queue in suspended state.

When the queue is put in suspended state all waiting threads are woken with message MSG_RESET and subsequent attempt at waiting on the queue will result in an immediate return with MSG_RESET message.

Note: The content of the queue is not altered, queues can be accessed is suspended state until a blocking operation is met then a MSG_RESET occurs.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 203 of file hal_buffers.h.

Referenced by sduSuspendHookI().

#define bqResumeX ( bqp )

Value:

{                                                    \
  (bqp)->suspended = false;                                                 \
}

Resumes normal queue operations.

Parameters

[in] bqp pointer to an io_buffers_queue_t structure

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 215 of file hal_buffers.h.

Referenced by sduConfigureHookI(), and sduWakeupHookI().

#define ibqIsEmptyI ( ibqp ) ((bool)(bqSpaceI(ibqp) == 0U))

Evaluates to true if the specified input buffers queue is empty.

Parameters

[in] ibqp pointer to an input_buffers_queue_t structure

Returns: The queue status.

Return values

false	if the queue is not empty.
true	if the queue is empty.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 229 of file hal_buffers.h.

Referenced by ibqGetFullBufferTimeoutS(), and ibqReleaseEmptyBufferS().

#define ibqIsFullI ( ibqp )

Value:

/*lint -save -e9007 [13.5] No side effects, a pointer is passed.*/        \
  ((bool)(((ibqp)->bwrptr == (ibqp)->brdptr) && ((ibqp)->bcounter != 0U)))  \
  /*lint -restore*/

Evaluates to true if the specified input buffers queue is full.

Parameters

[in] ibqp pointer to an input_buffers_queue_t structure

Returns: The queue status.

Return values

false	if the queue is not full.
true	if the queue is full.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 241 of file hal_buffers.h.

Referenced by ibqGetEmptyBufferI(), and ibqPostFullBufferI().

#define obqIsEmptyI ( obqp )

Value:

/*lint -save -e9007 [13.5] No side effects, a pointer is passed.*/        \
  ((bool)(((obqp)->bwrptr == (obqp)->brdptr) && ((obqp)->bcounter != 0U)))  \
  /*lint -restore*/

Evaluates to true if the specified output buffers queue is empty.

Parameters

[in] obqp pointer to an output_buffers_queue_t structure

Returns: The queue status.

Return values

false	if the queue is not empty.
true	if the queue is empty.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 256 of file hal_buffers.h.

Referenced by obqGetFullBufferI(), obqReleaseEmptyBufferI(), and obqTryFlushI().

#define obqIsFullI ( obqp ) ((bool)(bqSpaceI(obqp) == 0U))

Evaluates to true if the specified output buffers queue is full.

Parameters

[in] obqp pointer to an output_buffers_queue_t structure

Returns: The queue status.

Return values

false	if the queue is not full.
true	if the queue is full.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 271 of file hal_buffers.h.

Referenced by obqGetEmptyBufferTimeoutS(), and obqPostFullBufferS().

Typedef Documentation

typedef struct io_buffers_queue io_buffers_queue_t

Type of a generic queue of buffers.

Definition at line 47 of file hal_buffers.h.

typedef void(* bqnotify_t) (io_buffers_queue_t *bqp)

Double buffer notification callback type.

Parameters

[in] iodbp the buffers queue pointer

Definition at line 54 of file hal_buffers.h.

typedef io_buffers_queue_t input_buffers_queue_t

Type of an input buffers queue.

Definition at line 121 of file hal_buffers.h.

typedef io_buffers_queue_t output_buffers_queue_t

Type of an output buffers queue.

Definition at line 126 of file hal_buffers.h.

Function Documentation

void ibqObjectInit	(	input_buffers_queue_t *	ibqp,
		bool	suspended,
		uint8_t *	bp,
		size_t	size,
		size_t	n,
		bqnotify_t	infy,
		void *	link
	)

Initializes an input buffers queue object.

Parameters

[out]	ibqp	pointer to the `input_buffers_queue_t` object
[in]	suspended	initial state of the queue
[in]	bp	pointer to a memory area allocated for buffers
[in]	size	buffers size
[in]	n	number of buffers
[in]	infy	callback called when a buffer is returned to the queue
[in]	link	application defined pointer

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 76 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::bn, io_buffers_queue::brdptr, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, io_buffers_queue::bwrptr, io_buffers_queue::link, io_buffers_queue::notify, osalDbgCheck, osalThreadQueueObjectInit(), io_buffers_queue::ptr, io_buffers_queue::suspended, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by sduObjectInit().

Here is the call graph for this function:

void ibqResetI ( input_buffers_queue_t * ibqp )

Resets an input buffers queue.

All the data in the input buffers queue is erased and lost, any waiting thread is resumed with status MSG_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] ibqp pointer to the input_buffers_queue_t object

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 107 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::brdptr, io_buffers_queue::buffers, io_buffers_queue::bwrptr, osalDbgCheckClassI, osalThreadDequeueAllI(), io_buffers_queue::ptr, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by sduConfigureHookI(), and sduStop().

Here is the call graph for this function:

uint8_t * ibqGetEmptyBufferI ( input_buffers_queue_t * ibqp )

Gets the next empty buffer from the queue.

Note: The function always returns the same buffer if called repeatedly.

Parameters

[in] ibqp pointer to the input_buffers_queue_t object

Returns: A pointer to the next buffer to be filled.

Return values

NULL	if the queue is full.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 129 of file hal_buffers.c.

References io_buffers_queue::bwrptr, ibqIsFullI, and osalDbgCheckClassI.

void ibqPostFullBufferI	(	input_buffers_queue_t *	ibqp,
		size_t	size
	)

Posts a new filled buffer to the queue.

Parameters

[in]	ibqp	pointer to the `input_buffers_queue_t` object
[in]	size	used size of the buffer, cannot be zero

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 148 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, io_buffers_queue::bwrptr, ibqIsFullI, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, osalThreadDequeueNextI(), and io_buffers_queue::waiting.

Referenced by sduDataReceived().

Here is the call graph for this function:

msg_t ibqGetFullBufferTimeout	(	input_buffers_queue_t *	ibqp,
		sysinterval_t	timeout
	)

Gets the next filled buffer from the queue.

Note: The function always acquires the same buffer if called repeatedly.

Postcondition: After calling the function the fields ptr and top are set at beginning and end of the buffer data or NULL if the queue is empty.

Parameters

[in]	ibqp	pointer to the `input_buffers_queue_t` object
[in]	timeout	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

MSG_OK	if a buffer has been acquired.
MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 190 of file hal_buffers.c.

References ibqGetFullBufferTimeoutS(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

msg_t ibqGetFullBufferTimeoutS	(	input_buffers_queue_t *	ibqp,
		sysinterval_t	timeout
	)

Gets the next filled buffer from the queue.

Note: The function always acquires the same buffer if called repeatedly.

Postcondition: After calling the function the fields ptr and top are set at beginning and end of the buffer data or NULL if the queue is empty.

Parameters

[in]	ibqp	pointer to the `input_buffers_queue_t` object
[in]	timeout	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

MSG_OK	if a buffer has been acquired.
MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 222 of file hal_buffers.c.

References io_buffers_queue::brdptr, ibqIsEmptyI, osalDbgAssert, osalDbgCheckClassS, osalThreadEnqueueTimeoutS(), io_buffers_queue::ptr, io_buffers_queue::suspended, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by ibqGetFullBufferTimeout(), ibqGetTimeout(), and ibqReadTimeout().

Here is the call graph for this function:

void ibqReleaseEmptyBuffer ( input_buffers_queue_t * ibqp )

Releases the buffer back in the queue.

Note: The object callback is called after releasing the buffer.

Parameters

[in] ibqp pointer to the input_buffers_queue_t object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 254 of file hal_buffers.c.

References ibqReleaseEmptyBufferS(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

void ibqReleaseEmptyBufferS ( input_buffers_queue_t * ibqp )

Releases the buffer back in the queue.

Note: The object callback is called after releasing the buffer.

Parameters

[in] ibqp pointer to the input_buffers_queue_t object

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 269 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::brdptr, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, ibqIsEmptyI, io_buffers_queue::notify, osalDbgAssert, osalDbgCheckClassS, and io_buffers_queue::ptr.

Referenced by ibqGetTimeout(), ibqReadTimeout(), and ibqReleaseEmptyBuffer().

msg_t ibqGetTimeout	(	input_buffers_queue_t *	ibqp,
		sysinterval_t	timeout
	)

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 new buffer arrives in the queue or a timeout occurs.

Parameters

[in]	ibqp	pointer to the `input_buffers_queue_t` object
[in]	timeout	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.

Return values

MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 309 of file hal_buffers.c.

References ibqGetFullBufferTimeoutS(), ibqReleaseEmptyBufferS(), osalSysLock(), osalSysUnlock(), io_buffers_queue::ptr, and io_buffers_queue::top.

Here is the call graph for this function:

size_t ibqReadTimeout	(	input_buffers_queue_t *	ibqp,
		uint8_t *	bp,
		size_t	n,
		sysinterval_t	timeout
	)

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.

Parameters

[in]	ibqp	pointer to the `input_buffers_queue_t` object
[out]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred, the value 0 is reserved
[in]	timeout	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.

Return values

0	if a timeout occurred.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 358 of file hal_buffers.c.

References ibqGetFullBufferTimeoutS(), ibqReleaseEmptyBufferS(), osalDbgCheck, osalSysLock(), osalSysUnlock(), io_buffers_queue::ptr, and io_buffers_queue::top.

Here is the call graph for this function:

void obqObjectInit	(	output_buffers_queue_t *	obqp,
		bool	suspended,
		uint8_t *	bp,
		size_t	size,
		size_t	n,
		bqnotify_t	onfy,
		void *	link
	)

Initializes an output buffers queue object.

Parameters

[out]	obqp	pointer to the `output_buffers_queue_t` object
[in]	suspended	initial state of the queue
[in]	bp	pointer to a memory area allocated for buffers
[in]	size	buffers size
[in]	n	number of buffers
[in]	onfy	callback called when a buffer is posted in the queue
[in]	link	application defined pointer

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 432 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::bn, io_buffers_queue::brdptr, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, io_buffers_queue::bwrptr, io_buffers_queue::link, io_buffers_queue::notify, osalDbgCheck, osalThreadQueueObjectInit(), io_buffers_queue::ptr, io_buffers_queue::suspended, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by sduObjectInit().

Here is the call graph for this function:

void obqResetI ( output_buffers_queue_t * obqp )

Resets an output buffers queue.

All the data in the output buffers queue is erased and lost, any waiting thread is resumed with status MSG_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] obqp pointer to the output_buffers_queue_t object

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 463 of file hal_buffers.c.

References io_buffers_queue::bcounter, bqSizeX, io_buffers_queue::brdptr, io_buffers_queue::buffers, io_buffers_queue::bwrptr, osalDbgCheckClassI, osalThreadDequeueAllI(), io_buffers_queue::ptr, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by sduConfigureHookI(), and sduStop().

Here is the call graph for this function:

uint8_t * obqGetFullBufferI	(	output_buffers_queue_t *	obqp,
		size_t *	sizep
	)

Gets the next filled buffer from the queue.

Note: The function always returns the same buffer if called repeatedly.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[out]	sizep	pointer to the filled buffer size

Returns: A pointer to the filled buffer.

Return values

NULL	if the queue is empty.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 486 of file hal_buffers.c.

References io_buffers_queue::brdptr, obqIsEmptyI, and osalDbgCheckClassI.

Referenced by obnotify(), sduDataTransmitted(), and sduSOFHookI().

void obqReleaseEmptyBufferI ( output_buffers_queue_t * obqp )

Releases the next filled buffer back in the queue.

Parameters

[in] obqp pointer to the output_buffers_queue_t object

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 508 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::brdptr, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, obqIsEmptyI, osalDbgAssert, osalDbgCheckClassI, osalThreadDequeueNextI(), and io_buffers_queue::waiting.

Referenced by sduDataTransmitted().

Here is the call graph for this function:

msg_t obqGetEmptyBufferTimeout	(	output_buffers_queue_t *	obqp,
		sysinterval_t	timeout
	)

Gets the next empty buffer from the queue.

Note: The function always acquires the same buffer if called repeatedly.

Postcondition: After calling the function the fields ptr and top are set at beginning and end of the buffer data or NULL if the queue is empty.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	timeout	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

MSG_OK	if a buffer has been acquired.
MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 545 of file hal_buffers.c.

References obqGetEmptyBufferTimeoutS(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

msg_t obqGetEmptyBufferTimeoutS	(	output_buffers_queue_t *	obqp,
		sysinterval_t	timeout
	)

Gets the next empty buffer from the queue.

Note: The function always acquires the same buffer if called repeatedly.

Postcondition: After calling the function the fields ptr and top are set at beginning and end of the buffer data or NULL if the queue is empty.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	timeout	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

MSG_OK	if a buffer has been acquired.
MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 577 of file hal_buffers.c.

References io_buffers_queue::bsize, io_buffers_queue::bwrptr, obqIsFullI, osalDbgAssert, osalDbgCheckClassS, osalThreadEnqueueTimeoutS(), io_buffers_queue::ptr, io_buffers_queue::suspended, io_buffers_queue::top, and io_buffers_queue::waiting.

Referenced by obqGetEmptyBufferTimeout(), obqPutTimeout(), and obqWriteTimeout().

Here is the call graph for this function:

void obqPostFullBuffer	(	output_buffers_queue_t *	obqp,
		size_t	size
	)

Posts a new filled buffer to the queue.

Note: The object callback is called after releasing the buffer.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	size	used size of the buffer, cannot be zero

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 610 of file hal_buffers.c.

References obqPostFullBufferS(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

void obqPostFullBufferS	(	output_buffers_queue_t *	obqp,
		size_t	size
	)

Posts a new filled buffer to the queue.

Note: The object callback is called after releasing the buffer.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	size	used size of the buffer, cannot be zero

Function Class:This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 626 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, io_buffers_queue::bwrptr, io_buffers_queue::notify, obqIsFullI, osalDbgAssert, osalDbgCheck, osalDbgCheckClassS, and io_buffers_queue::ptr.

Referenced by obqFlush(), obqPostFullBuffer(), obqPutTimeout(), and obqWriteTimeout().

msg_t obqPutTimeout	(	output_buffers_queue_t *	obqp,
		uint8_t	b,
		sysinterval_t	timeout
	)

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 a new buffer is freed in the queue or a timeout occurs.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	b	byte value to be transferred
[in]	timeout	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.

Return values

MSG_TIMEOUT	if the specified time expired.
MSG_RESET	if the queue has been reset or has been put in suspended state.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 671 of file hal_buffers.c.

References io_buffers_queue::bsize, obqGetEmptyBufferTimeoutS(), obqPostFullBufferS(), osalSysLock(), osalSysUnlock(), io_buffers_queue::ptr, and io_buffers_queue::top.

Here is the call graph for this function:

size_t obqWriteTimeout	(	output_buffers_queue_t *	obqp,
		const uint8_t *	bp,
		size_t	n,
		sysinterval_t	timeout
	)

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.

Parameters

[in]	obqp	pointer to the `output_buffers_queue_t` object
[in]	bp	pointer to the data buffer
[in]	n	the maximum amount of data to be transferred, the value 0 is reserved
[in]	timeout	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.

Return values

0	if a timeout occurred.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 721 of file hal_buffers.c.

References io_buffers_queue::bsize, obqGetEmptyBufferTimeoutS(), obqPostFullBufferS(), osalDbgCheck, osalSysLock(), osalSysUnlock(), io_buffers_queue::ptr, and io_buffers_queue::top.

Here is the call graph for this function:

bool obqTryFlushI ( output_buffers_queue_t * obqp )

Flushes the current, partially filled, buffer to the queue.

Note: The notification callback is not invoked because the function is meant to be called from ISR context. An operation status is returned instead.

Parameters

[in] obqp pointer to the output_buffers_queue_t object

Returns: The operation status.

Return values

false	if no new filled buffer has been posted to the queue.
true	if a new filled buffer has been posted to the queue.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 795 of file hal_buffers.c.

References io_buffers_queue::bcounter, io_buffers_queue::bsize, io_buffers_queue::btop, io_buffers_queue::buffers, io_buffers_queue::bwrptr, obqIsEmptyI, osalDbgCheckClassI, and io_buffers_queue::ptr.

Referenced by sduSOFHookI().

void obqFlush ( output_buffers_queue_t * obqp )

Flushes the current, partially filled, buffer to the queue.

Parameters

[in] obqp pointer to the output_buffers_queue_t object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 832 of file hal_buffers.c.

References io_buffers_queue::bwrptr, obqPostFullBufferS(), osalSysLock(), osalSysUnlock(), and io_buffers_queue::ptr.

Here is the call graph for this function:

Detailed Description

Macros

Macro Functions

Typedefs

Data Structures

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation