Pipe management services.
[Native RTAI API.]


Detailed Description

Pipe management services.

Message pipes are an improved replacement for the legacy RT-FIFOS. A message pipe is a two-way communication channel between a kernel-based real-time thread and a user-space process. Pipes can be operated in a message-oriented fashion so that message boundaries are preserved, and also in byte streaming mode from kernel to user-space for optimal throughput.

Kernel-based RTAI tasks open their side of the pipe using the rt_pipe_open() service; user-space processes do the same by opening the /dev/rtpN special devices, where N is the minor number agreed between both ends of each pipe.


Files

file  pipe.c
 This file is part of the RTAI project.

Functions

int rt_pipe_open (RT_PIPE *pipe, int minor)
 Open a pipe.
int rt_pipe_close (RT_PIPE *pipe)
 Close a pipe.
ssize_t rt_pipe_read (RT_PIPE *pipe, RT_PIPE_MSG **msgp, RTIME timeout)
 Read a message from a pipe.
ssize_t rt_pipe_write (RT_PIPE *pipe, RT_PIPE_MSG *msg, size_t size, int mode)
 Write a message to a pipe.
ssize_t rt_pipe_stream (RT_PIPE *pipe, const void *buf, size_t size)
 Stream bytes to a pipe.
ssize_t rt_pipe_flush (RT_PIPE *pipe)
 Flush the pipe.
RT_PIPE_MSG * rt_pipe_alloc (size_t size)
 Allocate a message pipe buffer.
int rt_pipe_free (RT_PIPE_MSG *msg)
 Free a message pipe buffer.


Function Documentation

RT_PIPE_MSG * rt_pipe_alloc size_t  size  ) 
 

Allocate a message pipe buffer.

This service allocates a message buffer from the system heap which can be subsequently filled by the caller then passed to rt_pipe_write() for sending. The beginning of the available data area of size contiguous bytes is accessible from P_MSGPTR(msg).

Parameters:
size The requested size in bytes of the buffer. This value should represent the size of the payload data.
Returns:
The address of the allocated message buffer upon success, or NULL if the allocation fails.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_pipe_close RT_PIPE *  pipe  ) 
 

Close a pipe.

This service closes a pipe previously opened by rt_pipe_open(). Data pending for transmission to user-space are lost.

Parameters:
pipe The descriptor address of the affected pipe.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF can be returned if pipe is scrambled.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_pipe_flush RT_PIPE *  pipe  ) 
 

Flush the pipe.

This service flushes any pending data buffered by rt_pipe_stream(). The data will be immediately sent to the user-space side of the pipe.

Parameters:
pipe The descriptor address of the pipe to flush.
Returns:
The number of bytes flushed upon success. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EPIPE is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_pipe_free RT_PIPE_MSG *  msg  ) 
 

Free a message pipe buffer.

This service releases a message buffer returned by rt_pipe_read() to the system heap.

Parameters:
msg The address of the message buffer to free.
Returns:
0 is returned upon success, or -EINVAL if msg is not a valid message buffer previously allocated by the rt_pipe_alloc() service.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_pipe_open RT_PIPE *  pipe,
int  minor
 

Open a pipe.

This service opens a bi-directional communication channel allowing data exchange between real-time tasks and regular user-space processes. Pipes natively preserve message boundaries, but can also be used in byte stream mode from kernel to user space.

rt_pipe_open() always returns immediately, even if the user-space side of the same pipe has not been opened yet. On the contrary, the user-space opener might be suspended until rt_pipe_open() is issued on the same pipe from kernel space, unless O_NONBLOCK has been specified to open(2).

Parameters:
pipe The address of a pipe descriptor RTAI will use to store the pipe-related data. This descriptor must always be valid while the pipe is active therefore it must be allocated in permanent memory.
minor The minor number of the device associated with the pipe.
Returns:
0 is returned upon success. Otherwise:
  • -ENODEV is returned if minor is not a valid minor number for the pipe pseudo-device (i.e. /dev/rtp*).

  • -EBUSY is returned if minor is already open.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_pipe_read RT_PIPE *  pipe,
RT_PIPE_MSG **  msgp,
RTIME  timeout
 

Read a message from a pipe.

This service retrieves the next message sent from the user-space side of the pipe. rt_pipe_read() always preserves message boundaries, which means that all data sent through the same write(2) operation on the user-space side will be gathered in a single message by this service.

Unless otherwise specified, the caller is blocked for a given amount of time if no data is immediately available on entry.

Parameters:
pipe The descriptor address of the pipe to read from.
msgp A pointer to a memory location which will be written upon success with the address of the received message. Once consumed, the message space should be freed using rt_pipe_free(). The application code can retrieve the actual data and size carried by the message by respectively using the P_MSGPTR() and P_MSGSIZE() macros.
timeout The number of clock ticks to wait for some message to arrive (see note). Passing TM_INFINITE causes the caller to block indefinitely until some data is eventually available. Passing TM_NONBLOCK causes the service to return immediately without waiting if no data is available on entry.
Returns:
The number of read bytes available from the received message is returned upon success; this value will be equal to P_MSGSIZE(*msgp). Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

  • -ETIMEDOUT is returned if timeout is different from TM_NONBLOCK and no data is available within the specified amount of time.

  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and no data is immediately available on entry.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before any data was available.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if timeout is equal to TM_NONBLOCK.

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_pipe_stream RT_PIPE *  pipe,
const void *  buf,
size_t  size
 

Stream bytes to a pipe.

This service writes a sequence of bytes to be received by the user-space side of the pipe. Unlike rt_pipe_write(), this service does not preserve message boundaries. Instead, an internal buffer is filled on the fly with the data. The actual sending may be delayed until the internal buffer is full, or the Linux kernel is re-entered after the real-time system enters a quiescent state.

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

Parameters:
pipe The descriptor address of the pipe to write to.
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 buffering any data.
Returns:
The number of sent bytes upon success; this value will be equal to size. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EPIPE is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

  • -ENOSYS is returned if the byte streaming mode has been disabled at configuration time by nullifying the size of the pipe buffer (see CONFIG_RTAI_OPT_NATIVE_PIPE_BUFSZ).

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_pipe_write RT_PIPE *  pipe,
RT_PIPE_MSG *  msg,
size_t  size,
int  mode
 

Write a message to a pipe.

This service writes a complete message to be received by the user-space side of the pipe. 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 on the user-space side.

Parameters:
pipe The descriptor address of the pipe to write to.
msg The address of the message to be sent. The message space must have been allocated using the rt_pipe_alloc() service. Once passed to rt_pipe_write(), the memory pointed to by msg is no more under the control of the application code and thus should not be referenced by it anymore; deallocation of this memory will be automatically handled as needed.
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.
Additionally, rt_pipe_write() causes any data buffered by rt_pipe_stream() to be flushed prior to sending the message. For this reason, rt_pipe_write() can return a non-zero byte count to the caller if some pending data has been flushed, even if size was zero on entry.

Parameters:
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 if the latter is non-zero, or the number of bytes flushed otherwise. Upon error, one of the following error codes is returned:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EPIPE is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible.


Generated on Mon Dec 13 09:49:49 2004 for RTAI API by  doxygen 1.3.9.1