/**
 * @file
 * This file is part of the Xenomai project.
 *
 * @note Copyright (C) 2009 Philippe Gerum <rpm@xenomai.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
 */

#ifndef _RTDM_UAPI_IPC_H
#define _RTDM_UAPI_IPC_H

/**
 * @ingroup rtdm_profiles
 * @defgroup rtdm_ipc Real-time IPC
 *
 * @b Profile @b Revision: 1
 * @n
 * @n
 * @par Device Characteristics
 * @n
 * @ref rtdm_driver_flags "Device Flags": @c RTDM_PROTOCOL_DEVICE @n
 * @n
 * @ref rtdm_driver.protocol_family "Protocol Family": @c PF_RTIPC @n
 * @n
 * @ref rtdm_driver.socket_type "Socket Type": @c SOCK_DGRAM @n
 * @n
 * @ref rtdm_driver_profile "Device Class": @c RTDM_CLASS_RTIPC @n
 * @n
 * @{
 *
 * @anchor rtipc_operations @name Supported operations
 * Standard socket operations supported by the RTIPC protocols.
 * @{
 */

/** Create an endpoint for communication in the AF_RTIPC domain.
 *
 * @param[in] domain The communication domain. Must be AF_RTIPC.
 *
 * @param[in] type The socket type. Must be SOCK_DGRAM.
 *
 * @param [in] protocol Any of @ref IPCPROTO_XDDP, @ref IPCPROTO_IDDP,
 * or @ref IPCPROTO_BUFP. @ref IPCPROTO_IPC is also valid, and refers
 * to the default RTIPC protocol, namely @ref IPCPROTO_IDDP.
 *
 * @return In addition to the standard error codes for @c socket(2),
 * the following specific error code may be returned:
 * - -ENOPROTOOPT (Protocol is known, but not compiled in the RTIPC driver).
 *   See @ref RTIPC_PROTO "RTIPC protocols"
 *   for available protocols.
 *
 * @par Calling context:
 * non-RT
 */
#ifdef DOXYGEN_CPP
int socket__AF_RTIPC(int domain =AF_RTIPC, int type =SOCK_DGRAM, int protocol);
#endif

/**
 * Close a RTIPC socket descriptor.
 *
 * Blocking calls to any of the @ref sendmsg__AF_RTIPC "sendmsg" or @ref
 * recvmsg__AF_RTIPC "recvmsg" functions will be unblocked when the socket
 * is closed and return with an error.
 *
 * @param[in] sockfd The socket descriptor to close.
 *
 * @return In addition to the standard error codes for @c close(2),
 * the following specific error code may be returned:
 * none
 *
 * @par Calling context:
 * non-RT
 */
#ifdef DOXYGEN_CPP
int close__AF_RTIPC(int sockfd);
#endif

/**
 * Bind a RTIPC socket to a port.
 *
 * Bind the socket to a destination port.
 *
 * @param[in] sockfd The RTDM file descriptor obtained from the socket
 * creation call.
 *
 * @param [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.
 *
 *   @em sipc_family must be AF_RTIPC, @em sipc_port is either -1,
 *   or a valid free port number between 0 and
 *   CONFIG_XENO_OPT_PIPE_NRDEV-1.
 *
 *   If @em sipc_port is -1, a free port will be assigned automatically.
 *
 *   Upon success, the pseudo-device /dev/rtp@em N will be reserved
 *   for this communication channel, where @em N is the assigned port
 *   number. The non real-time side shall open this device to exchange
 *   data over the bound socket.
 *
 * @anchor xddp_label_binding
 *   If a label was assigned (see @ref 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
 *   @c /proc/xenomai/registry/rtipc/xddp/@em label, where @em label is the
 *   label string passed to setsockopt() for the @ref XDDP_LABEL option.
 *
 * - IPCPROTO_IDDP
 *
 *   This action creates an endpoint for exchanging datagrams within
 *   the Xenomai domain.
 *
 *   @em sipc_family must be AF_RTIPC, @em sipc_port is either -1,
 *   or a valid free port number between 0 and
 *   CONFIG_XENO_OPT_IDDP_NRPORT-1.
 *
 *   If @em 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.
 *
 * @anchor iddp_label_binding
 *   If a label was assigned (see @ref 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 @c
 *   /proc/xenomai/registry/rtipc/iddp/@em label, where @em label is
 *   the label string passed to setsockopt() for the @ref IDDP_LABEL
 *   option.
 *
 * - IPCPROTO_BUFP
 *
 *   This action creates an endpoint for a one-way byte
 *   stream within the Xenomai domain.
 *
 *   @em sipc_family must be AF_RTIPC, @em sipc_port is either -1,
 *   or a valid free port number between 0 and CONFIG_XENO_OPT_BUFP_NRPORT-1.
 *
 *   If @em 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.
 *
 * @anchor bufp_label_binding
 *   If a label was assigned (see @ref 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 @c
 *   /proc/xenomai/registry/rtipc/bufp/@em label, where @em label is
 *   the label string passed to setsockopt() for the @a BUFP_LABEL
 *   option.
 *
 * @param[in] addrlen The size in bytes of the structure pointed to by
 * @a addr.
 *
 * @return In addition to the standard error codes for @c
 * 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)
 *   - -EAGAIN (no registry slot available, check/raise
 *     CONFIG_XENO_OPT_REGISTRY_NRSLOTS) .
 *
 * @par Calling context:
 * non-RT
 */
#ifdef DOXYGEN_CPP
int bind__AF_RTIPC(int sockfd, const struct sockaddr_ipc *addr,
		   socklen_t addrlen);
#endif

/**
 * Initiate a connection on a RTIPC socket.
 *
 * @param[in] sockfd The RTDM file descriptor obtained from the socket
 * creation call.
 *
 * @param [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 @ref
 * SO_RCVTIMEO) until a socket is bound to the same label via @c
 * bind(2) (see @ref XDDP_LABEL, @ref IDDP_LABEL, @ref 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 @c connect(2) or @c bind(2).
 *
 * @param[in] addrlen The size in bytes of the structure pointed to by
 * @a addr.
 *
 * @return In addition to the standard error codes for @c connect(2),
 * the following specific error code may be returned:
 * none.
 *
 * @par Calling context:
 * RT/non-RT
 */
#ifdef DOXYGEN_CPP
int connect__AF_RTIPC(int sockfd, const struct sockaddr_ipc *addr,
		      socklen_t addrlen);
#endif

/**
 * Set options on RTIPC sockets.
 *
 * These functions allow to set various socket options.
 * Supported Levels and Options:
 *
 * - Level @ref sockopts_socket "SOL_SOCKET"
 * - Level @ref sockopts_xddp "SOL_XDDP"
 * - Level @ref sockopts_iddp "SOL_IDDP"
 * - Level @ref sockopts_bufp "SOL_BUFP"
 * .
 *
 * @return In addition to the standard error codes for @c
 * setsockopt(2), the following specific error code may
 * be returned:
 * follow the option links above.
 *
 * @par Calling context:
 * non-RT
 */
#ifdef DOXYGEN_CPP
int setsockopt__AF_RTIPC(int sockfd, int level, int optname,
			 const void *optval, socklen_t optlen);
#endif
/**
 * Get options on RTIPC sockets.
 *
 * These functions allow to get various socket options.
 * Supported Levels and Options:
 *
 * - Level @ref sockopts_socket "SOL_SOCKET"
 * - Level @ref sockopts_xddp "SOL_XDDP"
 * - Level @ref sockopts_iddp "SOL_IDDP"
 * - Level @ref sockopts_bufp "SOL_BUFP"
 * .
 *
 * @return In addition to the standard error codes for @c
 * getsockopt(2), the following specific error code may
 * be returned:
 * follow the option links above.
 *
 * @par Calling context:
 * RT/non-RT
 */
#ifdef DOXYGEN_CPP
int getsockopt__AF_RTIPC(int sockfd, int level, int optname,
			 void *optval, socklen_t *optlen);
#endif

/**
 * Send a message on a RTIPC socket.
 *
 * @param[in] sockfd The RTDM file descriptor obtained from the socket
 * creation call.
 *
 * @param[in] msg The address of the message header conveying the
 * datagram.
 *
 * @param [in] flags Operation flags:
 *
 * - MSG_OOB Send out-of-band message.  For all RTIPC protocols except
 *   @ref 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. @ref
 *   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, @ref
 *   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 @ref 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
 *   @ref XDDP_BUFSZ for more.
 *
 * @note No RTIPC protocol allows for short writes, and only complete
 * messages are sent to the peer.
 *
 * @return In addition to the standard error codes for @c sendmsg(2),
 * the following specific error code may be returned:
 * none.
 *
 * @par Calling context:
 * RT
 */
#ifdef DOXYGEN_CPP
ssize_t sendmsg__AF_RTIPC(int sockfd, const struct msghdr *msg, int flags);
#endif

/**
 * Receive a message from a RTIPC socket.
 *
 * @param[in] sockfd The RTDM file descriptor obtained from the socket
 * creation call.
 *
 * @param[out] msg The address the message header will be copied at.
 *
 * @param [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 @ref 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 @ref
 * BUFP_BUFSZ. In that case, a short read is allowed to prevent a
 * deadlock.
 *
 * @return In addition to the standard error codes for @c recvmsg(2),
 * the following specific error code may be returned:
 * none.
 *
 * @par Calling context:
 * RT
 */
#ifdef DOXYGEN_CPP
ssize_t recvmsg__AF_RTIPC(int sockfd, struct msghdr *msg, int flags);
#endif

/**
 * Get socket name.
 *
 * The name of the local endpoint for the socket is copied back (see
 * struct sockaddr_ipc).
 *
 * @return In addition to the standard error codes for @c getsockname(2),
 * the following specific error code may be returned:
 * none.
 *
 * @par Calling context:
 * RT/non-RT
 */
#ifdef DOXYGEN_CPP
int getsockname__AF_RTIPC(int sockfd, struct sockaddr_ipc *addr, socklen_t *addrlen);
#endif

/**
 * 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 @c
 * connect(2), or implicitly via @c bind(2) if no @c connect(2) was
 * called prior to binding the socket to a port, in which case both
 * the local and remote names are equal.
 *
 * @return In addition to the standard error codes for @c getpeername(2),
 * the following specific error code may be returned:
 * none.
 *
 * @par Calling context:
 * RT/non-RT
 */
#ifdef DOXYGEN_CPP
int getpeername__AF_RTIPC(int sockfd, struct sockaddr_ipc *addr, socklen_t *addrlen);
#endif

/** @} */

#include <cobalt/uapi/kernel/types.h>
#include <cobalt/uapi/kernel/pipe.h>
#include <rtdm/rtdm.h>

/* Address family */
#define AF_RTIPC		111

/* Protocol family */
#define PF_RTIPC		AF_RTIPC

/**
 * @anchor RTIPC_PROTO @name RTIPC protocol list
 * protocols for the PF_RTIPC protocol family
 *
 * @{ */
enum {
/** Default protocol (IDDP) */
	IPCPROTO_IPC  = 0,
/**
 * 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@em \<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 @c
 * sendto(2) or @c write(2) will be passed to the peer endpoint in the
 * Linux domain, and made available for reading via the standard @c
 * read(2) system call. Conversely, all data sent using @c write(2)
 * through the non real-time endpoint will be conveyed to the
 * real-time socket endpoint, and made available to the @c recvfrom(2)
 * or @c read(2) system calls.
 */
	IPCPROTO_XDDP = 1,
/**
 * 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_IDDP = 2,
/**
 * 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).
 */
	IPCPROTO_BUFP = 3,
	IPCPROTO_MAX
};
/** @} */

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

/**
 * Port label information structure.
 */
struct rtipc_port_label {
	/** Port label string, null-terminated. */
	char label[XNOBJECT_NAME_LEN];
};

/**
 * Socket address structure for the RTIPC address family.
 */
struct sockaddr_ipc {
	/** RTIPC address family, must be @c AF_RTIPC */
	sa_family_t sipc_family;
	/** Port number. */
	rtipc_port_t sipc_port;
};

#define SOL_XDDP		311
/**
 * @anchor sockopts_xddp @name XDDP socket options
 * Setting and getting XDDP socket options.
 * @{ */
/**
 * 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/rtp@em N).
 *
 * When available, this label will be registered when binding, in
 * addition to the port number (see @ref xddp_label_binding
 * "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.
 *
 * @param [in] level @ref sockopts_xddp "SOL_XDDP"
 * @param [in] optname @b XDDP_LABEL
 * @param [in] optval Pointer to struct rtipc_port_label
 * @param [in] optlen sizeof(struct rtipc_port_label)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen invalid)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define XDDP_LABEL		1
/**
 * 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
 * @ref bind__AF_RTIPC "bind call".
 *
 * @param [in] level @ref sockopts_xddp "SOL_XDDP"
 * @param [in] optname @b XDDP_POOLSZ
 * @param [in] optval Pointer to a variable of type size_t, containing
 * the required size of the local pool to reserve at binding time
 * @param [in] optlen sizeof(size_t)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen invalid or *@a optval is zero)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define XDDP_POOLSZ		2
/**
 * 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 @ref
 * sendmsg__AF_RTIPC "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 *@a 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.
 *
 * @param [in] level @ref sockopts_xddp "SOL_XDDP"
 * @param [in] optname @b XDDP_BUFSZ
 * @param [in] optval Pointer to a variable of type size_t, containing
 * the required size of the streaming buffer
 * @param [in] optlen sizeof(size_t)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -ENOMEM (Not enough memory)
 * - -EINVAL (@a optlen is invalid)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define XDDP_BUFSZ		3
/**
 * XDDP monitoring callback
 *
 * Other RTDM drivers may install a user-defined callback via the @ref
 * 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 @ref 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.
 *
 * @param [in] level @ref sockopts_xddp "SOL_XDDP"
 * @param [in] optname @b XDDP_MONITOR
 * @param [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 @a optval disables monitoring.
 * @param [in] optlen sizeof(int (*)(int fd, int event, long arg))
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EPERM (Operation not allowed from user-space)
 * - -EINVAL (@a optlen is invalid)
 * .
 *
 * @par Calling context:
 * RT/non-RT, kernel space only
 */
#define XDDP_MONITOR		4
/** @} */

/**
 * @anchor XDDP_EVENTS @name XDDP events
 * Specific events occurring on XDDP channels, which can be monitored
 * via the @ref XDDP_MONITOR socket option.
 *
 * @{ */
/**
 * @ref XDDP_MONITOR "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/rtp@em N), which
 * means that some input is pending for the real-time endpoint. The
 * argument is the size of the incoming message.
 */
#define XDDP_EVTIN		1
/**
 * @ref XDDP_MONITOR "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/rtp@em N). The argument is
 * the size of the outgoing message.
 */
#define XDDP_EVTOUT		2
/**
 * @ref XDDP_MONITOR "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_EVTDOWN		3
/**
 * @ref XDDP_MONITOR "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_EVTNOBUF		4
/** @} */

#define SOL_IDDP		312
/**
 * @anchor sockopts_iddp @name IDDP socket options
 * Setting and getting IDDP socket options.
 * @{ */
/**
 * 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 @ref iddp_label_binding
 * "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.
 *
 * @param [in] level @ref sockopts_iddp "SOL_IDDP"
 * @param [in] optname @b IDDP_LABEL
 * @param [in] optval Pointer to struct rtipc_port_label
 * @param [in] optlen sizeof(struct rtipc_port_label)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen is invalid)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define IDDP_LABEL		1
/**
 * 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
 * @ref bind__AF_RTIPC "bind call".
 *
 * @param [in] level @ref sockopts_iddp "SOL_IDDP"
 * @param [in] optname @b IDDP_POOLSZ
 * @param [in] optval Pointer to a variable of type size_t, containing
 * the required size of the local pool to reserve at binding time
 * @param [in] optlen sizeof(size_t)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen is invalid or *@a optval is zero)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define IDDP_POOLSZ		2
/** @} */

#define SOL_BUFP		313
/**
 * @anchor sockopts_bufp @name BUFP socket options
 * Setting and getting BUFP socket options.
 * @{ */
/**
 * 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 @ref bufp_label_binding
 * "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.
 *
 * @param [in] level @ref sockopts_bufp "SOL_BUFP"
 * @param [in] optname @b BUFP_LABEL
 * @param [in] optval Pointer to struct rtipc_port_label
 * @param [in] optlen sizeof(struct rtipc_port_label)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen is invalid)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define BUFP_LABEL		1
/**
 * 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
 * @ref bind__AF_RTIPC "bind call".
 *
 * @param [in] level @ref sockopts_bufp "SOL_BUFP"
 * @param [in] optname @b BUFP_BUFSZ
 * @param [in] optval Pointer to a variable of type size_t, containing
 * the required size of the buffer to reserve at binding time
 * @param [in] optlen sizeof(size_t)
 *
 * @return 0 is returned upon success. Otherwise:
 *
 * - -EFAULT (Invalid data address given)
 * - -EALREADY (socket already bound)
 * - -EINVAL (@a optlen is invalid or *@a optval is zero)
 * .
 *
 * @par Calling context:
 * RT/non-RT
 */
#define BUFP_BUFSZ		2
/** @} */

/**
 * @anchor sockopts_socket @name Socket level options
 * Setting and getting supported standard socket level options.
 * @{ */
/**
 *
 * @ref IPCPROTO_IDDP and @ref IPCPROTO_BUFP protocols support the
 * standard SO_SNDTIMEO socket option, from the @c SOL_SOCKET level.
 *
 * @see @c setsockopt(), @c getsockopt() in IEEE Std 1003.1,
 * http://www.opengroup.org/onlinepubs/009695399/
 */
#ifdef DOXYGEN_CPP
#define SO_SNDTIMEO defined_by_kernel_header_file
#endif
/**
 *
 * All RTIPC protocols support the standard SO_RCVTIMEO socket option,
 * from the @c SOL_SOCKET level.
 *
 * @see @c setsockopt(), @c getsockopt() in IEEE Std 1003.1,
 * http://www.opengroup.org/onlinepubs/009695399/
 */
#ifdef DOXYGEN_CPP
#define SO_RCVTIMEO defined_by_kernel_header_file
#endif
/** @} */

/**
 * @anchor rtdm_ipc_examples @name RTIPC examples
 * @{ */
/** @example bufp-readwrite.c */
/** @example bufp-label.c */
/** @example iddp-label.c */
/** @example iddp-sendrecv.c */
/** @example xddp-echo.c */
/** @example xddp-label.c */
/** @example xddp-stream.c */
/** @} */

/** @} */

#endif /* !_RTDM_UAPI_IPC_H */