Pipes

Collaboration diagram for Pipes:

Detailed Description

Macros
#define	_PIPE_DATA(name, buffer, size)
	Data part of a static pipe initializer. More...
#define	PIPE_DECL(name, buffer, size)   pipe_t name = _PIPE_DATA(name, buffer, size)
	Static pipe initializer. More...

Data Structures
struct	pipe_t
	Structure representing a pipe object. More...

Functions
void	chPipeObjectInit (pipe_t *pp, uint8_t *buf, size_t n)
	Initializes a mailbox_t object. More...
void	chPipeReset (pipe_t *pp)
	Resets a pipe_t object. More...
size_t	chPipeWriteTimeout (pipe_t *pp, const uint8_t *bp, size_t n, sysinterval_t timeout)
	Pipe write with timeout. More...
size_t	chPipeReadTimeout (pipe_t *pp, uint8_t *bp, size_t n, sysinterval_t timeout)
	Pipe read with timeout. More...
static size_t	chPipeGetSizeI (const pipe_t *pp)
	Returns the pipe buffer size as number of bytes. More...
static size_t	chPipeGetUsedCountI (const pipe_t *pp)
	Returns the number of used byte slots into a pipe. More...
static size_t	chPipeGetFreeCountI (const pipe_t *pp)
	Returns the number of free byte slots into a pipe. More...
static uint8_t	chPipePeekI (const pipe_t *pp)
	Returns the next byte in the queue without removing it. More...
static void	chPipeResumeX (pipe_t *pp)
	Terminates the reset state. More...

Macro Definition Documentation

#define _PIPE_DATA	(		name,
			buffer,
			size
	)

Value:

{                                    \
  (uint8_t *)(buffer),                                                      \
  (uint8_t *)(buffer) + size,                                               \
  (uint8_t *)(buffer),                                                      \
  (uint8_t *)(buffer),                                                      \
  (size_t)0,                                                                \
  false,                                                                    \
  _THREADS_QUEUE_DATA(name.qw),                                             \
  _THREADS_QUEUE_DATA(name.qr),                                             \
  _MUTEX_DATA(name.mtx),                                                    \
}

Data part of a static pipe initializer.

This macro should be used when statically initializing a pipe that is part of a bigger structure.

Parameters

[in]	name	the name of the pipe variable
[in]	buffer	pointer to the pipe buffer array of uint8_t
[in]	size	number of uint8_t elements in the buffer array

Definition at line 84 of file chpipes.h.

#define PIPE_DECL	(		name,
			buffer,
			size
	)		pipe_t name = _PIPE_DATA(name, buffer, size)

Static pipe initializer.

Statically initialized pipes require no explicit initialization using chPipeObjectInit().

Parameters

[in]	name	the name of the pipe variable
[in]	buffer	pointer to the pipe buffer array of uint8_t
[in]	size	number of uint8_t elements in the buffer array

Definition at line 118 of file chpipes.h.

Function Documentation

void chPipeObjectInit	(	pipe_t *	pp,
		uint8_t *	buf,
		size_t	n
	)

Initializes a mailbox_t object.

Parameters

[out]	pp	the pointer to the pipe_t structure to be initialized
[in]	buf	pointer to the pipe buffer as an array of uint8_t
[in]	n	number of elements in the buffer array

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

Definition at line 89 of file chpipes.c.

References pipe_t::buffer, chDbgCheck, chThdQueueObjectInit, pipe_t::cnt, pipe_t::qr, pipe_t::qw, pipe_t::rdptr, pipe_t::reset, pipe_t::top, and pipe_t::wrptr.

void chPipeReset

(

pipe_t *

pp

)

Resets a pipe_t object.

All the waiting threads are resumed with status MSG_RESET and the queued data is lost.

Postcondition

The pipe is in reset state, all operations will fail and return MSG_RESET until the mailbox is enabled again using chPipeResumeX().

Parameters

[in]

pp

the pointer to an initialized pipe_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 115 of file chpipes.c.

References pipe_t::buffer, chDbgCheck, chSchRescheduleS(), chSysLock, chSysUnlock, chThdDequeueAllI(), pipe_t::cnt, MSG_RESET, pipe_t::qr, pipe_t::qw, pipe_t::rdptr, pipe_t::reset, and pipe_t::wrptr.

Here is the call graph for this function:

size_t chPipeWriteTimeout	(	pipe_t *	pp,
		const uint8_t *	bp,
		size_t	n,
		sysinterval_t	timeout
	)

Pipe write with timeout.

The function writes data from a buffer to a pipe. The operation completes when the specified amount of data has been transferred or after the specified timeout or if the pipe has been reset.

Parameters

[in]	pp	the pointer to an initialized pipe_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

MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

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

Definition at line 154 of file chpipes.c.

size_t chPipeReadTimeout	(	pipe_t *	pp,
		uint8_t *	bp,
		size_t	n,
		sysinterval_t	timeout
	)

Pipe read with timeout.

The function reads data from a pipe into a buffer. The operation completes when the specified amount of data has been transferred or after the specified timeout or if the pipe has been reset.

Parameters

[in]	pp	the pointer to an initialized pipe_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

MSG_RESET	if the mailbox has been reset.
MSG_TIMEOUT	if the operation has timed out.

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

Definition at line 181 of file chpipes.c.

static size_t chPipeGetSizeI ( const pipe_t *  pp )

inlinestatic

Returns the pipe buffer size as number of bytes.

Parameters

[in]

pp

the pointer to an initialized pipe_t object

Returns

The size of the pipe.

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 150 of file chpipes.h.

References pipe_t::buffer, and pipe_t::top.

Referenced by chPipeGetFreeCountI().

static size_t chPipeGetUsedCountI ( const pipe_t *  pp )

inlinestatic

Returns the number of used byte slots into a pipe.

Parameters

[in]

pp

the pointer to an initialized pipe_t object

Returns

The number of queued bytes.

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 166 of file chpipes.h.

References pipe_t::cnt.

Referenced by chPipeGetFreeCountI().

static size_t chPipeGetFreeCountI ( const pipe_t *  pp )

inlinestatic

Returns the number of free byte slots into a pipe.

Parameters

[in]

pp

the pointer to an initialized pipe_t object

Returns

The number of empty byte slots.

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 chpipes.h.

References chPipeGetSizeI(), and chPipeGetUsedCountI().

Here is the call graph for this function:

static uint8_t chPipePeekI ( const pipe_t *  pp )

inlinestatic

Returns the next byte in the queue without removing it.

Precondition

A byte must be present in the queue for this function to work or it would return garbage. The correct way to use this macro is to use chPipeGetFullCountI() and then use this macro, all within a lock state.

Parameters

[in]

pp

the pointer to an initialized pipe_t object

Returns

The next byte in 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 200 of file chpipes.h.

References pipe_t::rdptr.

static void chPipeResumeX ( pipe_t *  pp )

inlinestatic

Terminates the reset state.

Parameters

[in]

pp

the pointer to an initialized pipe_t object

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

Definition at line 214 of file chpipes.h.

References pipe_t::reset.