Xenomai API  2.6.5
Real-time IPC protocols

Profile Revision: 1

More...

Collaboration diagram for Real-time IPC protocols:

Files

file  rtipc.h
 This file is part of the Xenomai project.
 

Data Structures

struct  rtipc_port_label
 Port label information structure. More...
 
struct  sockaddr_ipc
 Socket address structure for the RTIPC address family. More...
 

Typedefs

typedef int16_t rtipc_port_t
 Port number type for the RTIPC address family.
 

Supported operations

Standard socket operations supported by the RTIPC protocols.

int socket__AF_RTIPC (int domain=AF_RTIPC, int type=SOCK_DGRAM, int protocol)
 Create an endpoint for communication in the AF_RTIPC domain. More...
 
int close__AF_RTIPC (int sockfd)
 Close a RTIPC socket descriptor. More...
 
int bind__AF_RTIPC (int sockfd, const struct sockaddr_ipc *addr, socklen_t addrlen)
 Bind a RTIPC socket to a port. More...
 
int connect__AF_RTIPC (int sockfd, const struct sockaddr_ipc *addr, socklen_t addrlen)
 Initiate a connection on a RTIPC socket. More...
 
int setsockopt__AF_RTIPC (int sockfd, int level, int optname, const void *optval, socklen_t optlen)
 Set options on RTIPC sockets. More...
 
int getsockopt__AF_RTIPC (int sockfd, int level, int optname, void *optval, socklen_t *optlen)
 Get options on RTIPC sockets. More...
 
ssize_t sendmsg__AF_RTIPC (int sockfd, const struct user_msghdr *msg, int flags)
 Send a message on a RTIPC socket. More...
 
ssize_t recvmsg__AF_RTIPC (int sockfd, struct user_msghdr *msg, int flags)
 Receive a message from a RTIPC socket. More...
 
int getsockname__AF_RTIPC (int sockfd, struct sockaddr_ipc *addr, socklen_t *addrlen)
 Get socket name. More...
 
int getpeername__AF_RTIPC (int sockfd, struct sockaddr_ipc *addr, socklen_t *addrlen)
 Get socket peer. More...
 

RTIPC protocol list

protocols for the PF_RTIPC protocol family

enum  { IPCPROTO_IPC = 0, IPCPROTO_XDDP = 1, IPCPROTO_IDDP = 2, IPCPROTO_BUFP = 3 }
 

XDDP socket options

Setting and getting XDDP socket options.

#define XDDP_LABEL   1
 XDDP label assignment. More...
 
#define XDDP_POOLSZ   2
 XDDP local pool size configuration. More...
 
#define XDDP_BUFSZ   3
 XDDP streaming buffer size configuration. More...
 
#define XDDP_MONITOR   4
 XDDP monitoring callback. More...
 

XDDP events

Specific events occurring on XDDP channels, which can be monitored via the XDDP_MONITOR socket option.

#define XDDP_EVTIN   1
 Monitor writes to the non real-time endpoint. More...
 
#define XDDP_EVTOUT   2
 Monitor reads from the non real-time endpoint. More...
 
#define XDDP_EVTDOWN   3
 Monitor close from the non real-time endpoint. More...
 
#define XDDP_EVTNOBUF   4
 Monitor memory shortage for non real-time datagrams. More...
 

IDDP socket options

Setting and getting IDDP socket options.

#define IDDP_LABEL   1
 IDDP label assignment. More...
 
#define IDDP_POOLSZ   2
 IDDP local pool size configuration. More...
 

BUFP socket options

Setting and getting BUFP socket options.

#define BUFP_LABEL   1
 BUFP label assignment. More...
 
#define BUFP_BUFSZ   2
 BUFP buffer size configuration. More...
 

Socket level options

Setting and getting supported standard socket level options.

#define SO_SNDTIMEO   defined_by_kernel_header_file
 IPCPROTO_IDDP and IPCPROTO_BUFP protocols support the standard SO_SNDTIMEO socket option, from the SOL_SOCKET level. More...
 
#define SO_RCVTIMEO   defined_by_kernel_header_file
 All RTIPC protocols support the standard SO_RCVTIMEO socket option, from the SOL_SOCKET level. More...
 

Detailed Description

Profile Revision: 1

Device Characteristics

Device Flags: RTDM_PROTOCOL_DEVICE

Protocol Family: PF_RTIPC

Socket Type: SOCK_DGRAM

Device Class: RTDM_CLASS_RTIPC

Macro Definition Documentation

#define BUFP_BUFSZ   2

BUFP buffer size configuration.

All messages written to a BUFP socket are buffered in a single per-socket memory area. Configuring the size of such buffer prior to binding the socket to a destination port is mandatory.

It is not allowed to configure a buffer size after the socket was bound. However, multiple configuration calls are allowed prior to the binding; the last value set will be used.

Note
: the buffer memory is obtained from the host allocator by the bind call.
Parameters
[in]levelSOL_BUFP
[in]optnameBUFP_BUFSZ
[in]optvalPointer to a variable of type size_t, containing the required size of the buffer to reserve at binding time
[in]optlensizeof(size_t)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen is invalid or *optval is zero)
Calling context:
RT/non-RT
Examples:
bufp-label.c, and bufp-readwrite.c.
#define BUFP_LABEL   1

BUFP label assignment.

ASCII label strings can be attached to BUFP ports, in order to connect sockets to them in a more descriptive way than using plain numeric port values.

When available, this label will be registered when binding, in addition to the port number (see BUFP port binding).

It is not allowed to assign a label after the socket was bound. However, multiple assignment calls are allowed prior to the binding; the last label set will be used.

Parameters
[in]levelSOL_BUFP
[in]optnameBUFP_LABEL
[in]optvalPointer to struct rtipc_port_label
[in]optlensizeof(struct rtipc_port_label)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen is invalid)
Calling context:
RT/non-RT
Examples:
bufp-label.c.
#define IDDP_LABEL   1

IDDP label assignment.

ASCII label strings can be attached to IDDP ports, in order to connect sockets to them in a more descriptive way than using plain numeric port values.

When available, this label will be registered when binding, in addition to the port number (see IDDP port binding).

It is not allowed to assign a label after the socket was bound. However, multiple assignment calls are allowed prior to the binding; the last label set will be used.

Parameters
[in]levelSOL_IDDP
[in]optnameIDDP_LABEL
[in]optvalPointer to struct rtipc_port_label
[in]optlensizeof(struct rtipc_port_label)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen is invalid)
Calling context:
RT/non-RT
Examples:
iddp-label.c.
#define IDDP_POOLSZ   2

IDDP local pool size configuration.

By default, the memory needed to convey the data is pulled from Xenomai's system pool. Setting a local pool size overrides this default for the socket.

If a non-zero size was configured, a local pool is allocated at binding time. This pool will provide storage for pending datagrams.

It is not allowed to configure a local pool size after the socket was bound. However, multiple configuration calls are allowed prior to the binding; the last value set will be used.

Note
: the pool memory is obtained from the host allocator by the bind call.
Parameters
[in]levelSOL_IDDP
[in]optnameIDDP_POOLSZ
[in]optvalPointer to a variable of type size_t, containing the required size of the local pool to reserve at binding time
[in]optlensizeof(size_t)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen is invalid or *optval is zero)
Calling context:
RT/non-RT
Examples:
iddp-sendrecv.c.
#define SO_RCVTIMEO   defined_by_kernel_header_file

All RTIPC protocols support the standard SO_RCVTIMEO socket option, from the SOL_SOCKET level.

See also
setsockopt(), getsockopt() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399/
Examples:
xddp-label.c.
#define SO_SNDTIMEO   defined_by_kernel_header_file

IPCPROTO_IDDP and IPCPROTO_BUFP protocols support the standard SO_SNDTIMEO socket option, from the SOL_SOCKET level.

See also
setsockopt(), getsockopt() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399/
#define XDDP_BUFSZ   3

XDDP streaming buffer size configuration.

In addition to sending datagrams, real-time threads may stream data in a byte-oriented mode through the port as well. This increases the bandwidth and reduces the overhead, when the overall data to send to the Linux domain is collected by bits, and keeping the message boundaries is not required.

This feature is enabled when a non-zero buffer size is set for the socket. In that case, the real-time data accumulates into the streaming buffer when MSG_MORE is passed to any of the send functions, until:

  • the receiver from the Linux domain wakes up and consumes it,
  • a different source port attempts to send data to the same destination port,
  • MSG_MORE is absent from the send flags,
  • the buffer is full,

whichever comes first.

Setting *optval to zero disables the streaming buffer, in which case all sendings are conveyed in separate datagrams, regardless of MSG_MORE.

Note
only a single streaming buffer exists per socket. When this buffer is full, the real-time data stops accumulating and sending operations resume in mere datagram mode. Accumulation may happen again after some or all data in the streaming buffer is consumed from the Linux domain endpoint.

The streaming buffer size may be adjusted multiple times during the socket lifetime; the latest configuration change will take effect when the accumulation resumes after the previous buffer was flushed.

Parameters
[in]levelSOL_XDDP
[in]optnameXDDP_BUFSZ
[in]optvalPointer to a variable of type size_t, containing the required size of the streaming buffer
[in]optlensizeof(size_t)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -ENOMEM (Not enough memory)
  • -EINVAL (optlen is invalid)
Calling context:
RT/non-RT
Examples:
xddp-stream.c.
#define XDDP_EVTDOWN   3

Monitor close from the non real-time endpoint.

XDDP_EVTDOWN is sent when the non real-time endpoint is closed. The argument is always 0.

#define XDDP_EVTIN   1

Monitor writes to the non real-time endpoint.

XDDP_EVTIN is sent when data is written to the non real-time endpoint the socket is bound to (i.e. via /dev/rtpN), which means that some input is pending for the real-time endpoint. The argument is the size of the incoming message.

#define XDDP_EVTNOBUF   4

Monitor memory shortage for non real-time datagrams.

XDDP_EVTNOBUF is sent when no memory is available from the pool to hold the message currently sent from the non real-time endpoint. The argument is the size of the failed allocation. Upon return from the callback, the caller will block and retry until enough space is available from the pool; during that process, the callback might be invoked multiple times, each time a new attempt to get the required memory fails.

#define XDDP_EVTOUT   2

Monitor reads from the non real-time endpoint.

XDDP_EVTOUT is sent when the non real-time endpoint successfully reads a complete message (i.e. via /dev/rtpN). The argument is the size of the outgoing message.

#define XDDP_LABEL   1

XDDP label assignment.

ASCII label strings can be attached to XDDP ports, so that opening the non-RT endpoint can be done by specifying this symbolic device name rather than referring to a raw pseudo-device entry (i.e. /dev/rtpN).

When available, this label will be registered when binding, in addition to the port number (see XDDP port binding).

It is not allowed to assign a label after the socket was bound. However, multiple assignment calls are allowed prior to the binding; the last label set will be used.

Parameters
[in]levelSOL_XDDP
[in]optnameXDDP_LABEL
[in]optvalPointer to struct rtipc_port_label
[in]optlensizeof(struct rtipc_port_label)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen invalid)
Calling context:
RT/non-RT
Examples:
xddp-label.c.
#define XDDP_MONITOR   4

XDDP monitoring callback.

Other RTDM drivers may install a user-defined callback via the rtdm_setsockopt call from the inter-driver API, in order to collect particular events occurring on the channel.

This notification mechanism is particularly useful to monitor a channel asynchronously while performing other tasks.

The user-provided routine will be passed the RTDM file descriptor of the socket receiving the event, the event code, and an optional argument. Four events are currently defined, see XDDP_EVENTS.

The XDDP_EVTIN and XDDP_EVTOUT events are fired on behalf of a fully atomic context; therefore, care must be taken to keep their overhead low. In those cases, the Xenomai services that may be called from the callback are restricted to the set allowed to a real-time interrupt handler.

Parameters
[in]levelSOL_XDDP
[in]optnameXDDP_MONITOR
[in]optvalPointer to a pointer to function of type int (*)(int fd, int event, long arg), containing the address of the user-defined callback.Passing a NULL callback pointer in optval disables monitoring.
[in]optlensizeof(int (*)(int fd, int event, long arg))
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EPERM (Operation not allowed from user-space)
  • -EINVAL (optlen is invalid)
Calling context:
RT/non-RT, kernel space only
#define XDDP_POOLSZ   2

XDDP local pool size configuration.

By default, the memory needed to convey the data is pulled from Xenomai's system pool. Setting a local pool size overrides this default for the socket.

If a non-zero size was configured, a local pool is allocated at binding time. This pool will provide storage for pending datagrams.

It is not allowed to configure a local pool size after the socket was bound. However, multiple configuration calls are allowed prior to the binding; the last value set will be used.

Note
: the pool memory is obtained from the host allocator by the bind call.
Parameters
[in]levelSOL_XDDP
[in]optnameXDDP_POOLSZ
[in]optvalPointer to a variable of type size_t, containing the required size of the local pool to reserve at binding time
[in]optlensizeof(size_t)
Returns
0 is returned upon success. Otherwise:
  • -EFAULT (Invalid data address given)
  • -EALREADY (socket already bound)
  • -EINVAL (optlen invalid or *optval is zero)
Calling context:
RT/non-RT
Examples:
xddp-echo.c.

Enumeration Type Documentation

anonymous enum
Enumerator
IPCPROTO_IPC 

Default protocol (IDDP)

IPCPROTO_XDDP 

Cross-domain datagram protocol (RT <-> non-RT).

Real-time Xenomai threads and regular Linux threads may want to exchange data in a way that does not require the former to leave the real-time domain (i.e. primary mode). The RTDM-based XDDP protocol is available for this purpose.

On the Linux domain side, pseudo-device files named /dev/rtp<minor> give regular POSIX threads access to non real-time communication endpoints, via the standard character-based I/O interface. On the Xenomai domain side, sockets may be bound to XDDP ports, which act as proxies to send and receive data to/from the associated pseudo-device files. Ports and pseudo-device minor numbers are paired, meaning that e.g. socket port 7 will proxy the traffic to/from /dev/rtp7.

All data sent through a bound/connected XDDP socket via sendto(2) or write(2) will be passed to the peer endpoint in the Linux domain, and made available for reading via the standard read(2) system call. Conversely, all data sent using write(2) through the non real-time endpoint will be conveyed to the real-time socket endpoint, and made available to the recvfrom(2) or read(2) system calls.

IPCPROTO_IDDP 

Intra-domain datagram protocol (RT <-> RT).

The RTDM-based IDDP protocol enables real-time threads to exchange datagrams within the Xenomai domain, via socket endpoints.

IPCPROTO_BUFP 

Buffer protocol (RT <-> RT, byte-oriented).

The RTDM-based BUFP protocol implements a lightweight, byte-oriented, one-way Producer-Consumer data path. All messages written are buffered into a single memory area in strict FIFO order, until read by the consumer.

This protocol always prevents short writes, and only allows short reads when a potential deadlock situation arises (i.e. readers and writers waiting for each other indefinitely).

Function Documentation

int bind__AF_RTIPC ( int  sockfd,
const struct sockaddr_ipc addr,
socklen_t  addrlen 
)

Bind a RTIPC socket to a port.

Bind the socket to a destination port.

Parameters
[in]addrThe address to bind the socket to (see struct sockaddr_ipc). The meaning of such address depends on the RTIPC protocol in use for the socket:
  • IPCPROTO_XDDP

    This action creates an endpoint for channelling traffic between the Xenomai and Linux domains.

    sipc_family must be AF_RTIPC, sipc_port is either -1, or a valid free port number between 0 and CONFIG_XENO_OPT_PIPE_NRDEV-1.

    If sipc_port is -1, a free port will be assigned automatically.

    Upon success, the pseudo-device /dev/rtpN will be reserved for this communication channel, where N is the assigned port number. The non real-time side shall open this device to exchange data over the bound socket.

If a label was assigned (see XDDP_LABEL) prior to binding the socket to a port, a registry link referring to the created pseudo-device will be automatically set up as /proc/xenomai/registry/rtipc/xddp/label, where label is the label string passed to setsockopt() for the XDDP_LABEL option.

  • IPCPROTO_IDDP

    This action creates an endpoint for exchanging datagrams within the Xenomai domain.

    sipc_family must be AF_RTIPC, sipc_port is either -1, or a valid free port number between 0 and CONFIG_XENO_OPT_IDDP_NRPORT-1.

    If sipc_port is -1, a free port will be assigned automatically. The real-time peer shall connect to the same port for exchanging data over the bound socket.

If a label was assigned (see IDDP_LABEL) prior to binding the socket to a port, a registry link referring to the assigned port number will be automatically set up as /proc/xenomai/registry/rtipc/iddp/label, where label is the label string passed to setsockopt() for the IDDP_LABEL option.

  • IPCPROTO_BUFP

    This action creates an endpoint for a one-way byte stream within the Xenomai domain.

    sipc_family must be AF_RTIPC, sipc_port is either -1, or a valid free port number between 0 and CONFIG_XENO_OPT_BUFP_NRPORT-1.

    If sipc_port is -1, an available port will be assigned automatically. The real-time peer shall connect to the same port for exchanging data over the bound socket.

If a label was assigned (see BUFP_LABEL) prior to binding the socket to a port, a registry link referring to the assigned port number will be automatically set up as /proc/xenomai/registry/rtipc/bufp/label, where label is the label string passed to setsockopt() for the BUFP_LABEL option.

Returns
In addition to the standard error codes for bind(2), the following specific error code may be returned:
  • -EFAULT (Invalid data address given)
  • -ENOMEM (Not enough memory)
  • -EINVAL (Invalid parameter)
  • -EADDRINUSE (Socket already bound to a port, or no port available)
Calling context:
non-RT
int close__AF_RTIPC ( int  sockfd)

Close a RTIPC socket descriptor.

Blocking calls to any of the sendmsg or recvmsg functions will be unblocked when the socket is closed and return with an error.

Returns
In addition to the standard error codes for close(2), the following specific error code may be returned: none
Calling context:
non-RT
int connect__AF_RTIPC ( int  sockfd,
const struct sockaddr_ipc addr,
socklen_t  addrlen 
)

Initiate a connection on a RTIPC socket.

Parameters
[in]addrThe address to connect the socket to (see struct sockaddr_ipc).
  • If sipc_port is a valid port for the protocol, it is used verbatim and the connection succeeds immediately, regardless of whether the destination is bound at the time of the call.
  • If sipc_port is -1 and a label was assigned to the socket, connect() blocks for the requested amount of time (see SO_RCVTIMEO) until a socket is bound to the same label via bind(2) (see XDDP_LABEL, IDDP_LABEL, BUFP_LABEL), in which case a connection is established between both endpoints.
  • If sipc_port is -1 and no label was assigned to the socket, the default destination address is cleared, meaning that any subsequent write to the socket will return -EDESTADDRREQ, until a valid destination address is set via connect(2) or bind(2).
Returns
In addition to the standard error codes for connect(2), the following specific error code may be returned: none.
Calling context:
RT/non-RT
int getpeername__AF_RTIPC ( int  sockfd,
struct sockaddr_ipc addr,
socklen_t *  addrlen 
)

Get socket peer.

The name of the remote endpoint for the socket is copied back (see struct sockaddr_ipc). This is the default destination address for messages sent on the socket. It can be set either explicitly via connect(2), or implicitly via bind(2) if no connect(2) was called prior to binding the socket to a port, in which case both the local and remote names are equal.

Returns
In addition to the standard error codes for getpeername(2), the following specific error code may be returned: none.
Calling context:
RT/non-RT
int getsockname__AF_RTIPC ( int  sockfd,
struct sockaddr_ipc addr,
socklen_t *  addrlen 
)

Get socket name.

The name of the local endpoint for the socket is copied back (see struct sockaddr_ipc).

Returns
In addition to the standard error codes for getsockname(2), the following specific error code may be returned: none.
Calling context:
RT/non-RT
int getsockopt__AF_RTIPC ( int  sockfd,
int  level,
int  optname,
void *  optval,
socklen_t *  optlen 
)

Get options on RTIPC sockets.

These functions allow to get various socket options. Supported Levels and Options:

Returns
In addition to the standard error codes for getsockopt(2), the following specific error code may be returned: follow the option links above.
Calling context:
RT/non-RT
ssize_t recvmsg__AF_RTIPC ( int  sockfd,
struct user_msghdr *  msg,
int  flags 
)

Receive a message from a RTIPC socket.

Parameters
[in]flagsOperation flags:
  • MSG_DONTWAIT Non-blocking I/O operation. The caller will not be blocked whenever no message is immediately available for receipt at the time of the call, but will rather return with -EWOULDBLOCK.
Note
IPCPROTO_BUFP does not allow for short reads and always returns the requested amount of bytes, except in one situation: whenever some writer is waiting for sending data upon a buffer full condition, while the caller would have to wait for receiving a complete message. This is usually the sign of a pathological use of the BUFP socket, like defining an incorrect buffer size via BUFP_BUFSZ. In that case, a short read is allowed to prevent a deadlock.
Returns
In addition to the standard error codes for recvmsg(2), the following specific error code may be returned: none.
Calling context:
RT
ssize_t sendmsg__AF_RTIPC ( int  sockfd,
const struct user_msghdr *  msg,
int  flags 
)

Send a message on a RTIPC socket.

Parameters
[in]flagsOperation flags:
  • MSG_OOB Send out-of-band message. For all RTIPC protocols except IPCPROTO_BUFP, sending out-of-band data actually means pushing them to the head of the receiving queue, so that the reader will always receive them before normal messages. IPCPROTO_BUFP does not support out-of-band sending.
  • MSG_DONTWAIT Non-blocking I/O operation. The caller will not be blocked whenever the message cannot be sent immediately at the time of the call (e.g. memory shortage), but will rather return with -EWOULDBLOCK. Unlike other RTIPC protocols, IPCPROTO_XDDP accepts but never considers MSG_DONTWAIT since writing to a real-time XDDP endpoint is inherently a non-blocking operation.
  • MSG_MORE Accumulate data before sending. This flag is accepted by the IPCPROTO_XDDP protocol only, and tells the send service to accumulate the outgoing data into an internal streaming buffer, instead of issuing a datagram immediately for it. See XDDP_BUFSZ for more.
Note
No RTIPC protocol allows for short writes, and only complete messages are sent to the peer.
Returns
In addition to the standard error codes for sendmsg(2), the following specific error code may be returned: none.
Calling context:
RT
int setsockopt__AF_RTIPC ( int  sockfd,
int  level,
int  optname,
const void *  optval,
socklen_t  optlen 
)

Set options on RTIPC sockets.

These functions allow to set various socket options. Supported Levels and Options:

Returns
In addition to the standard error codes for setsockopt(2), the following specific error code may be returned: follow the option links above.
Calling context:
non-RT
int socket__AF_RTIPC ( int  domain = AF_RTIPC,
int  type = SOCK_DGRAM,
int  protocol 
)

Create an endpoint for communication in the AF_RTIPC domain.

Parameters
[in]protocolAny of IPCPROTO_XDDP, IPCPROTO_IDDP, or IPCPROTO_BUFP. IPCPROTO_IPC is also valid, and refers to the default RTIPC protocol, namely IPCPROTO_IDDP.
Returns
In addition to the standard error codes for socket(2), the following specific error code may be returned:
  • -ENOPROTOOPT (Protocol is known, but not compiled in the RTIPC driver). See RTIPC protocols for available protocols.
Calling context:
non-RT