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 thread side and the reader is the ISR side.
Full duplex queue, bidirectional queue. Full duplex queues are implemented by pairing an input queue and an output queue together.

Collaboration diagram for I/O Buffers Queues:

Macro Functions
#define	bqSizeX(bqp)
	Returns the queue's number of buffers.
#define	bqSpaceI(bqp)
	Return the ready buffers number.
#define	bqGetLinkX(bqp)
	Returns the queue application-defined link.
#define	bqSetLinkX(bqp, lk)
	Sets the queue application-defined link.
#define	bqIsSuspendedX(bqp)
	Return the suspended state of the queue.
#define	bqSuspendI(bqp)
	Puts the queue in suspended state.
#define	bqResumeX(bqp)
	Resumes normal queue operations.
#define	ibqIsEmptyI(ibqp)
	Evaluates to `true` if the specified input buffers queue is empty.
#define	ibqIsFullI(ibqp)
	Evaluates to `true` if the specified input buffers queue is full.
#define	obqIsEmptyI(obqp)
	Evaluates to `true` if the specified output buffers queue is empty.
#define	obqIsFullI(obqp)
	Evaluates to `true` if the specified output buffers queue is full.

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

Macros
#define	BUFFERS_CHUNKS_SIZE 64
	Maximum size of blocks copied in critical sections.
#define	BQ_BUFFER_SIZE(n, size)
	Computes the size of a buffers queue buffer size.

Typedefs
typedef struct io_buffers_queue	io_buffers_queue_t
	Type of a generic queue of buffers.
typedef void(*	bqnotify_t) (io_buffers_queue_t *bqp)
	Double buffer notification callback type.
typedef io_buffers_queue_t	input_buffers_queue_t
	Type of an input buffers queue.
typedef io_buffers_queue_t	output_buffers_queue_t
	Type of an output buffers queue.

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.
void	ibqResetI (input_buffers_queue_t *ibqp)
	Resets an input buffers queue.
uint8_t *	ibqGetEmptyBufferI (input_buffers_queue_t *ibqp)
	Gets the next empty buffer from the queue.
void	ibqPostFullBufferI (input_buffers_queue_t *ibqp, size_t size)
	Posts a new filled buffer to the queue.
msg_t	ibqGetFullBufferTimeout (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Gets the next filled buffer from the queue.
msg_t	ibqGetFullBufferTimeoutS (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Gets the next filled buffer from the queue.
void	ibqReleaseEmptyBuffer (input_buffers_queue_t *ibqp)
	Releases the buffer back in the queue.
void	ibqReleaseEmptyBufferS (input_buffers_queue_t *ibqp)
	Releases the buffer back in the queue.
msg_t	ibqGetTimeout (input_buffers_queue_t *ibqp, sysinterval_t timeout)
	Input queue read with timeout.
size_t	ibqReadTimeout (input_buffers_queue_t ibqp, uint8_t bp, size_t n, sysinterval_t timeout)
	Input queue read with timeout.
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.
void	obqResetI (output_buffers_queue_t *obqp)
	Resets an output buffers queue.
uint8_t *	obqGetFullBufferI (output_buffers_queue_t obqp, size_t sizep)
	Gets the next filled buffer from the queue.
void	obqReleaseEmptyBufferI (output_buffers_queue_t *obqp)
	Releases the next filled buffer back in the queue.
msg_t	obqGetEmptyBufferTimeout (output_buffers_queue_t *obqp, sysinterval_t timeout)
	Gets the next empty buffer from the queue.
msg_t	obqGetEmptyBufferTimeoutS (output_buffers_queue_t *obqp, sysinterval_t timeout)
	Gets the next empty buffer from the queue.
void	obqPostFullBuffer (output_buffers_queue_t *obqp, size_t size)
	Posts a new filled buffer to the queue.
void	obqPostFullBufferS (output_buffers_queue_t *obqp, size_t size)
	Posts a new filled buffer to the queue.
msg_t	obqPutTimeout (output_buffers_queue_t *obqp, uint8_t b, sysinterval_t timeout)
	Output queue write with timeout.
size_t	obqWriteTimeout (output_buffers_queue_t obqp, const uint8_t bp, size_t n, sysinterval_t timeout)
	Output queue write with timeout.
bool	obqTryFlushI (output_buffers_queue_t *obqp)
	Flushes the current, partially filled, buffer to the queue.
void	obqFlush (output_buffers_queue_t *obqp)
	Flushes the current, partially filled, buffer to the queue.

Macro Definition Documentation

◆ BUFFERS_CHUNKS_SIZE

#define BUFFERS_CHUNKS_SIZE 64

Maximum size of blocks copied in critical sections.

Note: Increasing this value increases performance at expense of IRQ servicing efficiency.; It must be a power of two.

Definition at line 43 of file hal_buffers.h.

Referenced by ibqReadTimeout(), and obqWriteTimeout().

◆ BQ_BUFFER_SIZE

#define BQ_BUFFER_SIZE	(		n,
			size )

Value:

(((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 154 of file hal_buffers.h.

◆ bqSizeX

#define bqSizeX ( bqp )

Value:

((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 169 of file hal_buffers.h.

Referenced by obqResetI().

◆ bqSpaceI

#define bqSpaceI ( bqp )

Value:

((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 181 of file hal_buffers.h.

◆ bqGetLinkX

#define bqGetLinkX ( bqp )

Value:

((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 191 of file hal_buffers.h.

Referenced by ibnotify(), and obnotify().

◆ bqSetLinkX

#define bqSetLinkX	(		bqp,
			lk )

Value:

((bqp)->link = lk)

Sets the queue application-defined link.

Parameters

[in]	bqp	pointer to an `io_buffers_queue_t` structure
[in]	lk	The application-defined link.

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

Definition at line 201 of file hal_buffers.h.

◆ bqIsSuspendedX

#define bqIsSuspendedX ( bqp )

Value:

((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 213 of file hal_buffers.h.

Referenced by sduSuspendHookI().

◆ bqSuspendI

#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 229 of file hal_buffers.h.

Referenced by sduSuspendHookI().

◆ bqResumeX

#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 241 of file hal_buffers.h.

Referenced by sduConfigureHookI(), and sduWakeupHookI().

◆ ibqIsEmptyI

#define ibqIsEmptyI ( ibqp )

Value:

((bool)(bqSpaceI(ibqp) == 0U))

bqSpaceI

#define bqSpaceI(bqp)

Return the ready buffers number.

Definition hal_buffers.h:181

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 255 of file hal_buffers.h.

Referenced by ibqGetFullBufferTimeoutS(), and ibqReleaseEmptyBufferS().

◆ ibqIsFullI

#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 267 of file hal_buffers.h.

Referenced by ibqGetEmptyBufferI(), and ibqPostFullBufferI().

◆ obqIsEmptyI

#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 282 of file hal_buffers.h.

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

◆ obqIsFullI

#define obqIsFullI ( obqp )

Value:

((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 297 of file hal_buffers.h.

Referenced by obqGetEmptyBufferTimeoutS(), and obqPostFullBufferS().

Typedef Documentation

◆ io_buffers_queue_t

typedef struct io_buffers_queue io_buffers_queue_t

Type of a generic queue of buffers.

Definition at line 63 of file hal_buffers.h.

◆ bqnotify_t

typedef void(* bqnotify_t) (io_buffers_queue_t *bqp)

Double buffer notification callback type.

Parameters

[in] bqp the buffers queue pointer

Definition at line 70 of file hal_buffers.h.

◆ input_buffers_queue_t

typedef io_buffers_queue_t input_buffers_queue_t

Type of an input buffers queue.

Definition at line 137 of file hal_buffers.h.

◆ output_buffers_queue_t

typedef io_buffers_queue_t output_buffers_queue_t

Type of an output buffers queue.

Definition at line 142 of file hal_buffers.h.

Function Documentation

◆ ibqObjectInit()

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:: Object or module nitializer function.

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:

◆ ibqResetI()

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, MSG_RESET, 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:

◆ ibqGetEmptyBufferI()

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.

Referenced by sdu_start_receive().

◆ ibqPostFullBufferI()

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, MSG_OK, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, osalThreadDequeueNextI(), and io_buffers_queue::waiting.

Referenced by sduDataReceived().

Here is the call graph for this function:

◆ ibqGetFullBufferTimeout()

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 189 of file hal_buffers.c.

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

Here is the call graph for this function:

◆ ibqGetFullBufferTimeoutS()

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 220 of file hal_buffers.c.

References io_buffers_queue::brdptr, ibqIsEmptyI, MSG_OK, MSG_RESET, 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:

◆ ibqReleaseEmptyBuffer()

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 252 of file hal_buffers.c.

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

Here is the call graph for this function:

◆ ibqReleaseEmptyBufferS()

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

◆ ibqGetTimeout()

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 306 of file hal_buffers.c.

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

Referenced by _get(), and _gett().

Here is the call graph for this function:

◆ ibqReadTimeout()

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 354 of file hal_buffers.c.

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

Referenced by _read(), and _readt().

Here is the call graph for this function:

◆ obqObjectInit()

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:: Object or module nitializer function.

Definition at line 428 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:

◆ obqResetI()

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 459 of file hal_buffers.c.

References io_buffers_queue::bcounter, bqSizeX, io_buffers_queue::brdptr, io_buffers_queue::buffers, io_buffers_queue::bwrptr, MSG_RESET, 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:

◆ obqGetFullBufferI()

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 482 of file hal_buffers.c.

References io_buffers_queue::brdptr, obqIsEmptyI, and osalDbgCheckClassI.

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

◆ obqReleaseEmptyBufferI()

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 505 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, MSG_OK, obqIsEmptyI, osalDbgAssert, osalDbgCheckClassI, osalThreadDequeueNextI(), and io_buffers_queue::waiting.

Referenced by sduDataTransmitted().

Here is the call graph for this function:

◆ obqGetEmptyBufferTimeout()

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 541 of file hal_buffers.c.

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

Here is the call graph for this function:

◆ obqGetEmptyBufferTimeoutS()

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 572 of file hal_buffers.c.

References io_buffers_queue::bsize, io_buffers_queue::bwrptr, MSG_OK, MSG_RESET, 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:

◆ obqPostFullBuffer()

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 605 of file hal_buffers.c.

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

Here is the call graph for this function:

◆ obqPostFullBufferS()

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

◆ obqPutTimeout()

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 665 of file hal_buffers.c.

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

Referenced by _put(), and _putt().

Here is the call graph for this function:

◆ obqWriteTimeout()

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 714 of file hal_buffers.c.

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

Referenced by _write(), and _writet().

Here is the call graph for this function:

◆ obqTryFlushI()

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

◆ obqFlush()

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 825 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

Macro Functions

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ BUFFERS_CHUNKS_SIZE

◆ BQ_BUFFER_SIZE

◆ bqSizeX

◆ bqSpaceI

◆ bqGetLinkX

◆ bqSetLinkX

◆ bqIsSuspendedX

◆ bqSuspendI

◆ bqResumeX

◆ ibqIsEmptyI

◆ ibqIsFullI

◆ obqIsEmptyI

◆ obqIsFullI

Typedef Documentation

◆ io_buffers_queue_t

◆ bqnotify_t

◆ input_buffers_queue_t

◆ output_buffers_queue_t

Function Documentation

◆ ibqObjectInit()

◆ ibqResetI()

◆ ibqGetEmptyBufferI()

◆ ibqPostFullBufferI()

◆ ibqGetFullBufferTimeout()

◆ ibqGetFullBufferTimeoutS()

◆ ibqReleaseEmptyBuffer()

◆ ibqReleaseEmptyBufferS()

◆ ibqGetTimeout()

◆ ibqReadTimeout()

◆ obqObjectInit()

◆ obqResetI()

◆ obqGetFullBufferI()

◆ obqReleaseEmptyBufferI()

◆ obqGetEmptyBufferTimeout()

◆ obqGetEmptyBufferTimeoutS()

◆ obqPostFullBuffer()

◆ obqPostFullBufferS()

◆ obqPutTimeout()

◆ obqWriteTimeout()

◆ obqTryFlushI()

◆ obqFlush()