Lightweight FIFO IPC mechanism. More...

Collaboration diagram for Buffer services:

Data Structures
struct	RT_BUFFER_INFO
	Buffer status descriptor. More...

Macros
#define	B_PRIO 0x1 /* Pend by task priority order. */
	Creation flags. More...

Functions
int	rt_buffer_create (RT_BUFFER bf, const char name, size_t bufsz, int mode)
	Create an IPC buffer. More...

int	rt_buffer_delete (RT_BUFFER *bf)
	Delete an IPC buffer. More...

ssize_t	rt_buffer_write_timed (RT_BUFFER bf, const void ptr, size_t size, const struct timespec *abs_timeout)
	Write to an IPC buffer. More...

static ssize_t	rt_buffer_write_until (RT_BUFFER bf, const void ptr, size_t size, RTIME timeout)
	Write to an IPC buffer (with absolute scalar timeout). More...

static ssize_t	rt_buffer_write (RT_BUFFER bf, const void ptr, size_t size, RTIME timeout)
	Write to an IPC buffer (with relative scalar timeout). More...

ssize_t	rt_buffer_read_timed (RT_BUFFER bf, void ptr, size_t size, const struct timespec *abs_timeout)
	Read from an IPC buffer. More...

static ssize_t	rt_buffer_read_until (RT_BUFFER bf, void ptr, size_t size, RTIME timeout)
	Read from an IPC buffer (with absolute scalar timeout). More...

static ssize_t	rt_buffer_read (RT_BUFFER bf, void ptr, size_t size, RTIME timeout)
	Read from an IPC buffer (with relative scalar timeout). More...

int	rt_buffer_clear (RT_BUFFER *bf)
	Clear an IPC buffer. More...

int	rt_buffer_inquire (RT_BUFFER bf, RT_BUFFER_INFO info)
	Query buffer status. More...

int	rt_buffer_bind (RT_BUFFER bf, const char name, RTIME timeout)
	Bind to an IPC buffer. More...

int	rt_buffer_unbind (RT_BUFFER *bf)
	Unbind from an IPC buffer. More...

Detailed Description

Lightweight FIFO IPC mechanism.

A buffer is a lightweight IPC mechanism, implementing a fast, one-way producer-consumer data path. All messages written are buffered in a single memory area in strict FIFO order, until read either in blocking or non-blocking mode.

Message are always atomically handled on the write side (i.e. no interleave, no short writes), whilst only complete messages are normally returned to the read side. However, short reads may happen under a well-defined situation (see note in rt_buffer_read()), albeit they can be fully avoided by proper use of the buffer.

Macro Definition Documentation

◆ B_PRIO

#define B_PRIO 0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_buffer_create().

Function Documentation

◆ rt_buffer_bind()

int rt_buffer_bind	(	RT_BUFFER *	bf,
		const char *	name,
		RTIME	timeout
	)

Bind to an IPC buffer.

This routine creates a new descriptor to refer to an existing IPC buffer identified by its symbolic name. If the object does not exist on entry, the caller may block until a buffer of the given name is created.

Parameters

bf	The address of a buffer descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the buffer to bind to. This string should match the object name argument passed to rt_buffer_create().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns: Zero is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_buffer_clear()

int rt_buffer_clear ( RT_BUFFER * bf )

Clear an IPC buffer.

This routine empties a buffer from any data.

Parameters

bf	The buffer descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if bf is not a valid buffer descriptor.

Tags: unrestricted, switch-primary

◆ rt_buffer_create()

int rt_buffer_create	(	RT_BUFFER *	bf,
		const char *	name,
		size_t	bufsz,
		int	mode
	)

Create an IPC buffer.

This routine creates an IPC object that allows tasks to send and receive data asynchronously via a memory buffer. Data may be of an arbitrary length, albeit this IPC is best suited for small to medium-sized messages, since data always have to be copied to the buffer during transit. Large messages may be more efficiently handled by message queues (RT_QUEUE).

Parameters

bf	The address of a buffer descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the buffer. When non-NULL and non-empty, a copy of this string is used for indexing the created buffer into the object registry.
bufsz	The size of the buffer space available to hold data. The required memory is obtained from the main heap.
mode	The buffer creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new buffer:

B_FIFO makes tasks pend in FIFO order for reading data from the buffer.
B_PRIO makes tasks pend in priority order for reading data from the buffer.

This parameter also applies to tasks blocked on the buffer's write side (see rt_buffer_write()).

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if mode is invalid or bufsz is zero.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the buffer.
-EEXIST is returned if the name is conflicting with an already registered buffer.
-EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.

Tags: xthread-only, mode-unrestricted, switch-secondary

Note: Buffers can be shared by multiple processes which belong to the same Xenomai session.

References B_PRIO.

◆ rt_buffer_delete()

int rt_buffer_delete ( RT_BUFFER * bf )

Delete an IPC buffer.

This routine deletes a buffer object previously created by a call to rt_buffer_create().

Parameters

bf	The buffer descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if bf is not a valid buffer descriptor.
-EPERM is returned if this service was called from an asynchronous context.

Tags: mode-unrestricted, switch-secondary

◆ rt_buffer_inquire()

int rt_buffer_inquire	(	RT_BUFFER *	bf,
		RT_BUFFER_INFO *	info
	)

Query buffer status.

This routine returns the status information about the specified buffer.

Parameters

bf	The buffer descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns: Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

-EINVAL is returned if bf is not a valid buffer descriptor.

Tags: unrestricted, switch-primary

◆ rt_buffer_read()

ssize_t rt_buffer_read	(	RT_BUFFER *	bf,
		void *	ptr,
		size_t	len,
		RTIME	timeout
	)

inlinestatic

Read from an IPC buffer (with relative scalar timeout).

This routine is a variant of rt_buffer_read_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

bf	The buffer descriptor.
ptr	A pointer to a memory area which will be written upon success with the received data.
len	The length in bytes of the memory area pointed to by ptr.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough data is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case not enough data is available.

Tags: xthread-nowait, switch-primary

◆ rt_buffer_read_timed()

ssize_t rt_buffer_read_timed	(	RT_BUFFER *	bf,
		void *	ptr,
		size_t	len,
		const struct timespec *	abs_timeout
	)

Read from an IPC buffer.

This routine reads the next message from the specified buffer. If no message is available on entry, the caller is allowed to block until enough data is written to the buffer, or a timeout elapses.

Parameters

bf	The buffer descriptor.
ptr	A pointer to a memory area which will be written upon success with the received data.
len	The length in bytes of the memory area pointed to by ptr. Under normal circumstances, rt_buffer_read_timed() only returns entire messages as specified by the len argument, or an error value. However, short reads are allowed when a potential deadlock situation is detected (see note below).
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for a message to be available from the buffer (see note). Passing NULL causes the caller to block indefinitely until enough data is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case not enough data is available.

Returns: The number of bytes read from the buffer is returned upon success. Otherwise:

-ETIMEDOUT is returned if abs_timeout is reached before a complete message arrives.
-EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and not enough data is immediately available on entry to form a complete message.
-EINTR is returned if rt_task_unblock() was called for the current task before enough data became available to form a complete message.
-EINVAL is returned if bf is not a valid buffer descriptor, or len is greater than the actual buffer length.
-EIDRM is returned if bf is deleted while the caller was waiting for data. In such event, bf is no more valid upon return of this service.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Note: A short read (i.e. fewer bytes returned than requested by len) may happen whenever a pathological use of the buffer is encountered. This condition only arises when the system detects that one or more writers are waiting for sending data, while a reader would have to wait for receiving a complete message at the same time. For instance, consider the following sequence, involving a 1024-byte buffer (bf) and two threads:

writer thread > rt_write_buffer(&bf, ptr, 1, TM_INFINITE); (one byte to read, 1023 bytes available for sending) writer thread > rt_write_buffer(&bf, ptr, 1024, TM_INFINITE); (writer blocks - no space for another 1024-byte message) reader thread > rt_read_buffer(&bf, ptr, 1024, TM_INFINITE); (short read - a truncated (1-byte) message is returned)

In order to prevent both threads to wait for each other indefinitely, a short read is allowed, which may be completed by a subsequent call to rt_buffer_read() or rt_buffer_read_until(). If that case arises, thread priorities, buffer and/or message lengths should likely be fixed, in order to eliminate such condition.

Tags: xthread-nowait, switch-primary

Note: abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_buffer_read_until()

ssize_t rt_buffer_read_until	(	RT_BUFFER *	bf,
		void *	ptr,
		size_t	len,
		RTIME	abs_timeout
	)

inlinestatic

Read from an IPC buffer (with absolute scalar timeout).

This routine is a variant of rt_buffer_read_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

bf	The buffer descriptor.
ptr	A pointer to a memory area which will be written upon success with the received data.
len	The length in bytes of the memory area pointed to by ptr.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough data is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case not enough data is available.

Tags: xthread-nowait, switch-primary

◆ rt_buffer_unbind()

int rt_buffer_unbind ( RT_BUFFER * bf )

Unbind from an IPC buffer.

Parameters

bf	The buffer descriptor.

This routine releases a previous binding to an IPC buffer. After this call has returned, the descriptor is no more valid for referencing this object.

Tags: thread-unrestricted

◆ rt_buffer_write()

ssize_t rt_buffer_write	(	RT_BUFFER *	bf,
		const void *	ptr,
		size_t	len,
		RTIME	timeout
	)

inlinestatic

Write to an IPC buffer (with relative scalar timeout).

This routine is a variant of rt_buffer_write_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

bf	The buffer descriptor.
ptr	The address of the message data to be written to the buffer.
len	The length in bytes of the message data.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough buffer space is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case of buffer space shortage.

Tags: xthread-nowait, switch-primary

◆ rt_buffer_write_timed()

ssize_t rt_buffer_write_timed	(	RT_BUFFER *	bf,
		const void *	ptr,
		size_t	len,
		const struct timespec *	abs_timeout
	)

Write to an IPC buffer.

This routine writes a message to the specified buffer. If not enough buffer space is available on entry to hold the message, the caller is allowed to block until enough room is freed, or a timeout elapses, whichever comes first.

Parameters

bf	The buffer descriptor.
ptr	The address of the message data to be written to the buffer.
len	The length in bytes of the message data. Zero is a valid value, in which case the buffer is left untouched, and zero is returned to the caller.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for enough buffer space to be available to hold the message (see note). Passing NULL causes the caller to block indefinitely until enough buffer space is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case of buffer space shortage.

Returns: The number of bytes written to the buffer is returned upon success. Otherwise:

-ETIMEDOUT is returned if the absolute abs_timeout date is reached before enough buffer space is available to hold the message.
-EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no buffer space is immediately available on entry to hold the message.
-EINTR is returned if rt_task_unblock() was called for the current task before enough buffer space became available to hold the message.
-EINVAL is returned if bf is not a valid buffer descriptor, or len is greater than the actual buffer length.
-EIDRM is returned if bf is deleted while the caller was waiting for buffer space. In such event, bf is no more valid upon return of this service.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_buffer_write_until()

ssize_t rt_buffer_write_until	(	RT_BUFFER *	bf,
		const void *	ptr,
		size_t	len,
		RTIME	abs_timeout
	)

inlinestatic

Write to an IPC buffer (with absolute scalar timeout).

This routine is a variant of rt_buffer_write_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

bf	The buffer descriptor.
ptr	The address of the message data to be written to the buffer.
len	The length in bytes of the message data.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough buffer space is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case of buffer space shortage.

Tags: xthread-nowait, switch-primary

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ B_PRIO

Function Documentation

◆ rt_buffer_bind()

◆ rt_buffer_clear()

◆ rt_buffer_create()

◆ rt_buffer_delete()

◆ rt_buffer_inquire()

◆ rt_buffer_read()

◆ rt_buffer_read_timed()

◆ rt_buffer_read_until()

◆ rt_buffer_unbind()

◆ rt_buffer_write()

◆ rt_buffer_write_timed()

◆ rt_buffer_write_until()