Provided by: rds-tools_1.4.1-OFED-1.4.2-1_i386 bug

NAME

       RDS - Reliable Datagram Sockets

SYNOPSIS

       #include <sys/socket.h>
       #include <netinet/in.h>

DESCRIPTION

       This  is an implementation of the RDS socket API. It provides reliable,
       in-order  datagram  delivery  between  sockets  over   a   variety   of
       transports.

       Currently,  RDS  can be transported over Infiniband, and loopback.  RDS
       over TCP is disabled, but will be re-enabled in the near future.

       RDS uses standard AF_INET addresses as described in ip(7)  to  identify
       end points.

   Socket Creation
       RDS  is  still  in  development  and  as  such does not have a reserved
       protocol  family  constant.   Applications   must   read   the   string
       representation  of  the  protocol  family  value from the pf_rds sysctl
       parameter file described below.

       rds_socket = socket(pf_rds, SOCK_SEQPACKET, 0);

   Socket Options
       RDS  sockets  support  a  number  of   socket   options   through   the
       setsockopt(2)  and  getsockopt(2)  calls. The following generic options
       (with socket level SOL_SOCKET) are of specific importance:

       SO_RCVBUF
              Specifies the  size  of  the  receive  buffer.  See  section  on
              "Congestion Control" below.

       SO_SNDBUF
              Specifies   the   size   of   the   send  buffer.  See  "Message
              Transmission" below.

       SO_SNDTIMEO
              Specifies the send timeout when trying to enqueue a message on a
              socket with a full queue in blocking mode.

       In  addition  to  these,  RDS  supports  a  number of protocol specific
       options (with socket level SOL_RDS).  Just as  with  the  RDS  protocol
       family, an official value has not been assigned yet, so the kernel will
       assign a value dynamically.  The assigned value can be  retrieved  from
       the sol_rds sysctl parameter file.

       RDS  specific  socket  options  will be described in a separate section
       below.

   Binding
       A new RDS socket has no local address when it is  first  returned  from
       socket(2).   It  must  be  bound  to a local address by calling bind(2)
       before any messages can be sent or received. This will also attach  the
       socket  to  a  specific  transport,  based on the type of interface the
       local address is attached to.  From that point on, the socket can  only
       reach destinations which are available through this transport.

       For  instance,  when  binding to the address of an Infiniband interface
       such as ib0, the socket will use the Infiniband transport.  If  RDS  is
       not  able  to  associate  a  transport  with the given address, it will
       return EADDRNOTAVAIL.

       An RDS socket can only be bound to one address and only one socket  can
       be  bound  to a given address/port pair. If no port is specified in the
       binding address then an unbound port is selected at random.

       RDS does not allow the application to bind a previously bound socket to
       another  address.  Binding  to  the  wildcard address INADDR_ANY is not
       permitted either.

   Connecting
       The default mode of operation for RDS is to use unconnected socket, and
       specify  a destination address as an argument to sendmsg.  However, RDS
       allows sockets to be connected to a remote end point using  connect(2).
       If  a  socket  is  connected,  calling  sendmsg  without  specifying  a
       destination address will use the previously given remote address.

   Congestion Control
       RDS does not have explicit congestion  control  like  common  streaming
       protocols   such  as  TCP.  However,  sockets  have  two  queue  limits
       associated with them; the send queue size and the receive  queue  size.
       Messages are accounted based on the number of bytes of payload.

       The send queue size limits how much data local processes can queue on a
       local socket (see the following section). If that  limit  is  exceeded,
       the  kernel will not accept further messages until the queue is drained
       and messages have been delivered to  and  acknowledged  by  the  remote
       host.

       The receive queue size limits how much data RDS will put on the receive
       queue of a socket before marking  the  socket  as  congested.   When  a
       socket  becomes congested, RDS will send a congestion map update to the
       other participating hosts, who are then expected to stop  sending  more
       messages to this port.

       There  is a timing window during which a remote host can still continue
       to send messages to a congested port;  RDS  solves  this  by  accepting
       these  messages  even if the socket's receive queue is already over the
       limit.

       As the application pulls incoming messages off the receive queue  using
       recvmsg(2),  the  number  of bytes on the receive queue will eventually
       drop below the receive queue size, at which  point  the  port  is  then
       marked  uncongested,  and  another  congestion  update  is  sent to all
       participating hosts. This tells them  to  allow  applications  to  send
       additional messages to this port.

       The  default values for the send and receive buffer size are controlled
       by the A given  RDS  socket  has  limited  transmit  buffer  space.  It
       defaults  to  the  system  wide  socket  send  buffer  size  set in the
       wmem_default and rmem_default sysctls, respectively. They can be  tuned
       by the application through the SO_SNDBUF and SO_RCVBUF socket options.

   Blocking Behavior
       The  sendmsg(2)  and  recvmsg(2)  calls  can  block  in  a  variety  of
       situations.  Whether a call blocks or returns with an error depends  on
       the  non-blocking  setting  of the file descriptor and the MSG_DONTWAIT
       message flag. If the file descriptor is set to blocking mode (which  is
       the  default),  and  the  MSG_DONTWAIT flag is not given, the call will
       block.

       In addition, the SO_SNDTIMEO and SO_RCVTIMEO socket options can be used
       to  specify  a  timeout  (in  seconds)  after which the call will abort
       waiting, and return an error. The default timeout is 0, which tells RDS
       to block indefinitely.

   Message Transmission
       Messages  may  be  sent  using sendmsg(2) once the RDS socket is bound.
       Message length cannot exceed 4 gigabytes as the wire protocol  uses  an
       unsigned 32 bit integer to express the message length.

       RDS does not support out of band data. Applications are allowed to send
       to unicast addresses only; broadcast or multicast are not supported.

       A successful sendmsg(2) call puts the message in the socket's  transmit
       queue  where  it  will remain until either the destination acknowledges
       that the message is no longer in the network or the application removes
       the message from the send queue.

       Messages can be removed from the send queue with the RDS_CANCEL_SENT_TO
       socket option described below.

       While a message  is  in  the  transmit  queue  its  payload  bytes  are
       accounted  for.  If an attempt is made to send a message while there is
       not sufficient room on the transmit queue, the call will  either  block
       or return EAGAIN.

       Trying  to  send to a destination that is marked congested (see above),
       the call will either block or return ENOBUFS.

       A message sent with no payload bytes will not consume any space in  the
       destination's  send  buffer but will result in a message receipt on the
       destination. The receiver will not get any payload  data  but  will  be
       able to see the sender's address.

       Messages  sent  to  a port to which no socket is bound will be silently
       discarded by the destination host. No error messages  are  reported  to
       the sender.

   Message Receipt
       Messages  may  be  received with recvmsg(2) on an RDS socket once it is
       bound to a source address. RDS  will  return  messages  in-order,  i.e.
       messages  from  the  same sender will arrive in the same order in which
       they were be sent.

       The address of the sender will be returned in the sockaddr_in structure
       pointed to by the msg_name field, if set.

       If  the  MSG_PEEK  flag  is  given, the first message on the receive is
       returned without removing it from the queue.

       The memory consumed by messages waiting for delivery does not limit the
       number  of messages that can be queued for receive. RDS does attempt to
       perform congestion control as described in the section above.

       If the length of the message exceeds the size of the buffer provided to
       recvmsg(2),  then  the  remainder  of  the  bytes  in  the  message are
       discarded and the MSG_TRUNC flag is set in the msg_flags field. In this
       truncating  case  recvmsg(2)  will  still  return  the  number of bytes
       copied, not the length of entire messge.  If MSG_TRUNC is  set  in  the
       flags  argument  to recvmsg(2), then it will return the number of bytes
       in the entire message. Thus one  can  examine  the  size  of  the  next
       message  in  the  receive queue without incurring a copying overhead by
       providing a zero length buffer and setting MSG_PEEK  and  MSG_TRUNC  in
       the flags argument.

       The  sending address of a zero-length message will still be provided in
       the msg_name field.

   Control Messages
       RDS  uses  control  messages  (a.k.a.  ancillary  data)   through   the
       msg_control  and  msg_controllen  fields  in sendmsg(2) and recvmsg(2).
       Control messages generated by RDS have a cmsg_level value  of  sol_rds.
       Most  control  messages  are related to the zerocopy interface added in
       RDS version 3, and are described in rds-rdma(7).

       The only  exception  is  the  RDS_CMSG_CONG_UPDATE  message,  which  is
       described in the following section.

   Polling
       RDS  supports  the  poll(2)  interface in a limited fashion.  POLLIN is
       returned when there is a message (either a proper  RDS  message,  or  a
       control  message)  waiting  in  the socket's receive queue.  POLLOUT is
       always returned while there is room on the socket's send queue.

       Sending  to  congested  ports  requires  special  handling.   When   an
       application  tries  to send to a congested destination, the system call
       will return ENOBUFS.  However, it cannot poll for POLLOUT, as there  is
       probably still room on the transmit queue, so the call to poll(2) would
       return immediately, even though the destination is still congested.

       There are two ways of dealing with this  situation.  The  first  is  to
       simply  poll  for POLLIN.  By default, a process sleeping in poll(2) is
       always woken up when the  congestion  map  is  updated,  and  thus  the
       application can retry any previously congested sends.

       The  second  option  is explicit congestion monitoring, which gives the
       application more fine-grained control.

       With explicit monitoring, the application polls for POLLIN  as  before,
       and  additionally  uses the RDS_CONG_MONITOR socket option to install a
       64bit mask value in the socket, where each bit corresponds to  a  group
       of ports. When a congestion update arrives, RDS checks the set of ports
       that became uncongested against the bit mask installed in  the  socket.
       If  they overlap, a control messages is enqueued on the socket, and the
       application is woken up. When it calls recvmsg(2), it will be given the
       control message containing the bitmap.  on the socket.

       The   congestion   monitor   bitmask  can  be  set  and  queried  using
       setsockopt(2) with RDS_CONG_MONITOR, and a pointer to  the  64bit  mask
       variable.

       Congestion    updates    are   delivered   to   the   application   via
       RDS_CMSG_CONG_UPDATE  control  messages.  These  control  messages  are
       always   delivered   by  themselves  (or  possibly  additional  control
       messages), but never along with a RDS data message. The cmsg_data field
       of  the  control  message  is an 8 byte datum containing the 64bit mask
       value.

       Applications can use the following macros to test for and set  bits  in
       the bitmask:

       #define RDS_CONG_MONITOR_SIZE   64
       #define RDS_CONG_MONITOR_BIT(port)  (((unsigned int) port) % RDS_CONG_MONITOR_SIZE)
       #define RDS_CONG_MONITOR_MASK(port) (1 << RDS_CONG_MONITOR_BIT(port))

   Canceling Messages
       An  application  can  cancel (flush) messages from the send queue using
       the RDS_CANCEL_SENT_TO socket option  with  setsockopt(2).   This  call
       takes  an optional sockaddr_in address structure as argument. If given,
       only  messages  to  the  destination  specified  by  this  address  are
       discarded. If no address is given, all pending messages are discarded.

       Note  that  this affects messages that have not yet been transmitted as
       well  as  messages  that  have  been  transmitted,  but  for  which  no
       acknowledgment from the remote host has been received yet.

   Reliability
       If  sendmsg(2)  succeeds,  RDS  guarantees  that the  message  will  be
       visible  to recvmsg(2) on a socket bound to the destination address  as
       long as that destination socket remains open.

       If  there  is  no  socket  bound on the  destination,  the  message  is
       silently  dropped.   If  the sending RDS can't be sure that there is no
       socket bound then it will try to send the message indefinitely until it
       can be sure or the sent message is canceled.

       If  a socket is closed then all pending sent messages on the socket are
       canceled and may or may not be seen by the receiver.

       The RDS_CANCEL_SENT_TO socket option can be used to cancel all  pending
       messages to a given destination.

       If  a  receiving socket is closed with pending messages then the sender
       considers  those messages as  having  left  the  network and  will  not
       retransmit them.

       A  message will only be seen by recvmsg(2) once,  unless  MSG_PEEK  was
       specified.  Once  the message has been delivered it is removed from the
       sending socket's transmit queue.

       All messages sent from the same socket to the same destination will  be
       delivered  in  the  order  they're  sent.  Messages sent from different
       sockets, or to different destinations, may be delivered in any order.

SYSCTL VALUES

       These  parameteres  may  only  be  accessed  through  their  files   in
       /proc/sys/net/rds.  Access through sysctl(2) is not supported.

       pf_rds This  file  contains  the  string representation of the protocol
              family constant passed to socket(2) to create a new RDS socket.

       sol_rds
              This file contains the string representation of the socket level
              parameter  that  is passed to getsockopt(2) and setsockopt(2) to
              manipulate RDS socket options.

       max_unacked_bytes and max_unacked_packets
              These  parameters  are  used   to   tune   the   generation   of
              acknowledgements.  By default, the system receiving RDS messages
              does not send back explicit acknowledgements unless it transmits
              a  message of its own (in which case the ACK is piggybacked onto
              the outgoing message), or when the sending  system  requests  an
              ACK.

              However,  the  sender  needs  to see an ACK from time to time so
              that it can purge old messages from the send queue. The  unacked
              bytes  and  packet  counters  are used to keep track of how much
              data has been sent without requesting an ACK. The default is  to
              request  an  acknowledgement  every  16 packets, or every 16 MB,
              whichever comes first.

       reconnect_delay_min_ms and reconnect_delay_max_ms
              RDS uses host-to-host  connections  to  transport  RDS  messages
              (both  for  the  TCP  and  the  Infiniband  transport).  If this
              connection breaks, RDS will try to re-establish the  connection.
              Because  this  reconnect  may  be triggered by both hosts at the
              same time and fail, RDS uses a random backoff before  attempting
              a  reconnect.  These  two  parameters  specify  the  minimum and
              maximum delay in milliseconds. The  default  values  are  1  and
              1000, respectively.

SEE ALSO

       rds-rdma(7), socket(2), bind(2), sendmsg(2), recvmsg(2), getsockopt(2),
       setsockopt(2).

                                                                        RDS(7)