Message pipe services

Two-way communication channel between Xenomai & Linux domains. More...

Collaboration diagram for Message pipe services:

Macros
#define	P_MINOR_AUTO   XNPIPE_MINOR_AUTO
	Creation flags. More...
#define	P_URGENT   XNPIPE_URGENT
	Operation flags. More...

Functions
int	rt_pipe_delete (RT_PIPE *pipe)
	Delete a message pipe. More...
ssize_t	rt_pipe_read_timed (RT_PIPE *pipe, void *buf, size_t size, const struct timespec *abs_timeout)
	Read a message from a pipe. More...
static ssize_t	rt_pipe_read_until (RT_PIPE *pipe, void *buf, size_t size, RTIME timeout)
	Read from a pipe (with absolute scalar timeout). More...
static ssize_t	rt_pipe_read (RT_PIPE *pipe, void *buf, size_t size, RTIME timeout)
	Read from a pipe (with relative scalar timeout). More...
ssize_t	rt_pipe_write (RT_PIPE *pipe, const void *buf, size_t size, int mode)
	Write a message to a pipe. More...
ssize_t	rt_pipe_stream (RT_PIPE *pipe, const void *buf, size_t size)
	Stream bytes through a pipe. More...
int	rt_pipe_bind (RT_PIPE *pipe, const char *name, RTIME timeout)
	Bind to a message pipe. More...
int	rt_pipe_unbind (RT_PIPE *pipe)
	Unbind from a message pipe. More...
int	rt_pipe_create (RT_PIPE *pipe, const char *name, int minor, size_t poolsize)
	Create a message pipe. More...

Detailed Description

Two-way communication channel between Xenomai & Linux domains.

A message pipe is a two-way communication channel between Xenomai threads and normal Linux threads using regular file I/O operations on a pseudo-device. Pipes can be operated in a message-oriented fashion so that message boundaries are preserved, and also in byte-oriented streaming mode from real-time to normal Linux threads for optimal throughput.

Xenomai threads open their side of the pipe using the rt_pipe_create() service; regular Linux threads do the same by opening one of the /dev/rtpN special devices, where N is the minor number agreed upon between both ends of each pipe.

In addition, named pipes are available through the registry support, which automatically creates a symbolic link from entries under /proc/xenomai/registry/rtipc/xddp/ to the corresponding special device file.

Note

Alchemy's message pipes are fully based on the XDDP protocol available from the RTDM/ipc driver.

Macro Definition Documentation

P_MINOR_AUTO

#define P_MINOR_AUTO   XNPIPE_MINOR_AUTO

Creation flags.

P_URGENT

#define P_URGENT   XNPIPE_URGENT

Operation flags.

Function Documentation

rt_pipe_bind()

int rt_pipe_bind	(	RT_PIPE *	pipe,
		const char *	name,
		RTIME	timeout
	)

Bind to a message pipe.

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

Parameters

pipe	The address of a pipe descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the pipe to bind to. This string should match the object name argument passed to rt_pipe_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

Note

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

rt_pipe_create()

int rt_pipe_create	(	RT_PIPE *	pipe,
		const char *	name,
		int	minor,
		size_t	poolsize
	)

Create a message pipe.

This service opens a bi-directional communication channel for exchanging messages between Xenomai threads and regular Linux threads. Pipes natively preserve message boundaries, but can also be used in byte-oriented streaming mode from Xenomai to Linux.

rt_pipe_create() always returns immediately, even if no thread has opened the associated special device file yet. On the contrary, the non real-time side could block upon attempt to open the special device file until rt_pipe_create() is issued on the same pipe from a Xenomai thread, unless O_NONBLOCK was given to the open(2) system call.

Parameters

pipe	The address of a pipe 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 pipe. When non-NULL and non-empty, a copy of this string is used for indexing the created pipe into the object registry.

Named pipes are supported through the use of the registry. Passing a valid name parameter when creating a message pipe causes a symbolic link to be created from /proc/xenomai/registry/rtipc/xddp/name to the associated special device (i.e. /dev/rtp*), so that the specific minor information does not need to be known from those processes for opening the proper device file. In such a case, both sides of the pipe only need to agree upon a symbolic name to refer to the same data path, which is especially useful whenever the minor number is picked up dynamically using an adaptive algorithm, such as passing P_MINOR_AUTO as minor value.

Parameters

minor	The minor number of the device associated with the pipe. Passing P_MINOR_AUTO causes the minor number to be auto-allocated. In such a case, a symbolic link will be automatically created from /proc/xenomai/registry/rtipc/xddp/name to the allocated pipe device entry. Valid minor numbers range from 0 to CONFIG_XENO_OPT_PIPE_NRDEV-1.
poolsize	Specifies the size of a dedicated buffer pool for the pipe. Passing 0 means that all message allocations for this pipe are performed on the Cobalt core heap.

Returns

The minor number assigned to the connection is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get memory from the main heap in order to create the pipe.
• -ENODEV is returned if minor is different from P_MINOR_AUTO and is not a valid minor number.
• -EEXIST is returned if the name is conflicting with an already registered pipe.
• -EBUSY is returned if minor is already open.
• -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

rt_pipe_delete()

int rt_pipe_delete

(

RT_PIPE *

pipe

)

Delete a message pipe.

This routine deletes a pipe object previously created by a call to rt_pipe_create(). All resources attached to that pipe are automatically released, all pending data is flushed.

Parameters

pipe	The pipe descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if pipe is not a valid pipe descriptor.
• -EIDRM is returned if pipe is a closed pipe descriptor.
• -EPERM is returned if this service was called from an asynchronous context.

Tags

mode-unrestricted, switch-secondary

rt_pipe_read()

ssize_t rt_pipe_read ( RT_PIPE *  pipe, void *  buf, size_t  size, RTIME  timeout  )

inlinestatic

Read from a pipe (with relative scalar timeout).

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

Parameters

pipe	The pipe descriptor.
buf	A pointer to a memory area which will be written upon success with the message received.
size	The count of bytes from the received message to read up into buf. If size is lower than the actual message size, -ENOBUFS is returned since the incompletely received message would be lost. If size is zero, this call returns immediately with no other action.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_pipe_read_timed()

ssize_t rt_pipe_read_timed	(	RT_PIPE *	pipe,
		void *	buf,
		size_t	size,
		const struct timespec *	abs_timeout
	)

Read a message from a pipe.

This service reads the next available message from a given pipe.

Parameters

pipe	The pipe descriptor.
buf	A pointer to a memory area which will be written upon success with the message received.
size	The count of bytes from the received message to read up into buf. If size is lower than the actual message size, -ENOBUFS is returned since the incompletely received message would be lost. If size is zero, this call returns immediately with no other action.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for a message to be available from the pipe (see note). Passing NULL causes the caller to block indefinitely until a message is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case no message is available.

Returns

The number of bytes available from the received message is returned upon success. Otherwise:

• -ETIMEDOUT is returned if abs_timeout is reached before a message arrives.
• -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no message is immediately available on entry to the call.
• -EINTR is returned if rt_task_unblock() was called for the current task before a message was available.
• -EINVAL is returned if pipe is not a valid pipe descriptor.
• -EIDRM is returned if pipe is deleted while the caller was waiting for a message. In such event, pipe 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_pipe_read_until()

ssize_t rt_pipe_read_until ( RT_PIPE *  pipe, void *  buf, size_t  size, RTIME  abs_timeout  )

inlinestatic

Read from a pipe (with absolute scalar timeout).

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

Parameters

pipe	The pipe descriptor.
buf	A pointer to a memory area which will be written upon success with the message received.
size	The count of bytes from the received message to read up into buf. If size is lower than the actual message size, -ENOBUFS is returned since the incompletely received message would be lost. If size is zero, this call returns immediately with no other action.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_pipe_stream()

ssize_t rt_pipe_stream	(	RT_PIPE *	pipe,
		const void *	buf,
		size_t	size
	)

Stream bytes through a pipe.

This service writes a sequence of bytes to be received from the associated special device. Unlike rt_pipe_send(), this service does not preserve message boundaries. Instead, an internal buffer is filled on the fly with the data, which will be consumed as soon as the receiver wakes up.

Data buffers sent by the rt_pipe_stream() service are always transmitted in FIFO order (i.e. P_NORMAL mode).

Parameters

pipe	The pipe descriptor.
buf	The address of the first data byte to send. The data will be copied to an internal buffer before transmission.
size	The size in bytes of the buffer. Zero is a valid value, in which case the service returns immediately without sending any data.

Returns

The number of bytes sent upon success; this value may be lower than size, depending on the available space in the internal buffer. Otherwise:

• -EINVAL is returned if mode is invalid or pipe is not a pipe descriptor.
• -ENOMEM is returned if not enough buffer space is available to complete the operation.
• -EIDRM is returned if pipe is a closed pipe descriptor.

Note

Writing data to a pipe before any peer has opened the associated special device is allowed. The output will be buffered until then, only restricted by the available memory in the associated buffer pool (see rt_pipe_create()).

Tags

xcontext, switch-primary

rt_pipe_unbind()

int rt_pipe_unbind

(

RT_PIPE *

pipe

)

Unbind from a message pipe.

Parameters

pipe	The pipe descriptor.

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

Tags

thread-unrestricted

rt_pipe_write()

ssize_t rt_pipe_write	(	RT_PIPE *	pipe,
		const void *	buf,
		size_t	size,
		int	mode
	)

Write a message to a pipe.

This service writes a complete message to be received from the associated special device. rt_pipe_write() always preserves message boundaries, which means that all data sent through a single call of this service will be gathered in a single read(2) operation from the special device.

This service differs from rt_pipe_send() in that it accepts a pointer to the raw data to be sent, instead of a canned message buffer.

Parameters

pipe	The pipe descriptor.
buf	The address of the first data byte to send. The data will be copied to an internal buffer before transmission.
size	The size in bytes of the message (payload data only). Zero is a valid value, in which case the service returns immediately without sending any message.
mode	A set of flags affecting the operation:

• P_URGENT causes the message to be prepended to the output queue, ensuring a LIFO ordering.
• P_NORMAL causes the message to be appended to the output queue, ensuring a FIFO ordering.

Returns

Upon success, this service returns size. Upon error, one of the following error codes is returned:

• -EINVAL is returned if mode is invalid or pipe is not a pipe descriptor.
• -ENOMEM is returned if not enough buffer space is available to complete the operation.
• -EIDRM is returned if pipe is a closed pipe descriptor.

Note

Writing data to a pipe before any peer has opened the associated special device is allowed. The output will be buffered until then, only restricted by the available memory in the associated buffer pool (see rt_pipe_create()).

Tags

xcontext, switch-primary