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]	level	SOL_BUFP
[in]	optname	BUFP_BUFSZ
[in]	optval	Pointer to a variable of type size_t, containing the required size of the buffer to reserve at binding time
[in]	optlen	sizeof(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]	level	SOL_BUFP
[in]	optname	BUFP_LABEL
[in]	optval	Pointer to struct rtipc_port_label
[in]	optlen	sizeof(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]	level	SOL_IDDP
[in]	optname	IDDP_LABEL
[in]	optval	Pointer to struct rtipc_port_label
[in]	optlen	sizeof(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]	level	SOL_IDDP
[in]	optname	IDDP_POOLSZ
[in]	optval	Pointer to a variable of type size_t, containing the required size of the local pool to reserve at binding time
[in]	optlen	sizeof(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]	level	SOL_XDDP
[in]	optname	XDDP_BUFSZ
[in]	optval	Pointer to a variable of type size_t, containing the required size of the streaming buffer
[in]	optlen	sizeof(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]	level	SOL_XDDP
[in]	optname	XDDP_LABEL
[in]	optval	Pointer to struct rtipc_port_label
[in]	optlen	sizeof(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]	level	SOL_XDDP
[in]	optname	XDDP_MONITOR
[in]	optval	Pointer 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]	optlen	sizeof(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]	level	SOL_XDDP
[in]	optname	XDDP_POOLSZ
[in]	optval	Pointer to a variable of type size_t, containing the required size of the local pool to reserve at binding time
[in]	optlen	sizeof(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] addr The 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] addr The 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:

Level SOL_SOCKET
Level SOL_XDDP
Level SOL_IDDP
Level SOL_BUFP

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] flags Operation 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] flags Operation 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:

Level SOL_SOCKET
Level SOL_XDDP
Level SOL_IDDP
Level SOL_BUFP

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] protocol Any 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

Files

Data Structures

Typedefs

Supported operations

RTIPC protocol list

XDDP socket options

XDDP events

IDDP socket options

BUFP socket options

Socket level options

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation