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

NAME

       RDS-rdma - Zerocopy Interface for RDMA over RDS

DESCRIPTION

       This  manual page describes the zerocopy interface of RDS, which was added in RDSv3. For a
       description of the basic RDS interface, please refer to rds(7).

       The principal mode of operation for RDS  zerocopy  is  like  this:  one  participant  (the
       client) wishes to initiate a direct transfer to or from some area of memory in its process
       address space.  This memory does not have to be aligned.

       The client obtains a handle for this  region  of  memory,  and  passes  it  to  the  other
       participant  (the  server). This is called the RDMA cookie. To the application, the cookie
       is an opaque 64bit data type.

       The client sends this handle to the server application, along with other  details  of  the
       RDMA  request  (such  as  which  data  to  transfer  to that memory area).  Throughout the
       following discussion, we will refer to this message as the RDMA request.

       The server uses this RDMA cookie  to  initiate  the  requested  RDMA  transfer.  The  RDMA
       transfer  is  combined  atomically  with  a  normal RDS message, which is delivered to the
       client. This message is called the RDMA ACK throughout  the  following.   Atomic  in  this
       context means that either both the RDMA succeeds and the RDMA ACK is delivered, or neither
       succeeds.

       Thus, when the client receives the  RDMA  ACK,  it  knows  that  the  RDMA  has  completed
       successfully. It can then release the RDMA cookie for this memory region, if it wishes to.

       RDMA  operations  are not reliable, in the sense that unlike normal RDS messages, RDS RDMA
       operations may fail, and get dropped.

INTERFACE

       The interface is currently based on control messages (ancillary data) sent or received via
       the  sendmsg(2)  and  recvmsg(2)  system calls. Optionally, an older interface can be used
       that is based on the setsockopt(2)  system  call.  However,  we  recommend  using  control
       messages, as this reduces the number of system calls required.

   Control message interface
       With  the  control message interface, the RDMA cookie is passed to the server out-of-band,
       included in an extension header attached to the RDS message.

       The following outlines the mode of operation; the data types used  will  be  specified  in
       details in a subsequent section.

       Initially,  the  client  will  send  RDMA  requests along with a RDS_CMSG_RDMA_MAP control
       message. The control message contains the address and length  of  the  memory  region  for
       which  to obtain a handle, some flags, and a pointer to a memory location (in the caller's
       address space) where the kernel will store the RDMA cookie.

       Alternatively, if the application has already obtained a RDMA cookie for the memory  range
       it   wants   to   RDMA  to/from,  it  can  hand  this  cookie  to  the  kernel  using  the
       RDS_CMSG_RDMA_DEST control message.

       Either way, the kernel will include the resulting RDMA cookie in an extension header  that
       is transmitted as part of the RDMA request to the server.

       When  the  server  receives  the  RDMA request, the kernel will deliver the cookie wrapped
       inside a RDS_CMSG_RDMA_DEST control message.

       The server then initiates the data transfer by sending the RDMA ACK message along  with  a
       RDS_CMSG_RDMA_ARGS  control  message. This message contains the RDMA cookie, and the local
       memory to copy to or from.

       The  server  process  may  request  a  notification  when  an  RDMA  operation  completes.
       Notifications   are   delivered  as  a  RDS_CMSG_RDMA_STATUS  control  messages.  When  an
       application calls recvmsg(2), it will either receive a regular RDS message (possibly  with
       other  RDMA related control messages), or an empty message with one or more status control
       messages.

       In addition, applications When an RDMA operation fails for some reason and  is  discarded,
       the  application  can ask to receive notifications for failed messages as well, regardless
       of whether it asked for success  notification  of  an  individual  message  or  not.  This
       behavior is turned on by setting the RDS_RECVERR socket option.

   Setsockopt interface
       In addition to the control message interface, RDS allows a process to register and release
       memory ranges for RDMA through calls to setsockopt(2).

       RDS_GET_MR
              To obtain a RDMA  cookie  for  a  given  memory  range,  the  application  can  use
              setsockopt  with  RDS_GET_MR.   This  operates  essentially  the  same  way  as the
              RDS_CMSG_RDMA_MAP control message: the argument contains the address and length  of
              the  memory  range  to  be  registered, and a pointer to a RDMA cookie variable, in
              which the system call will store the cookie for the registered range.

       RDS_FREE_MR
              Memory ranges can be released by calling setsockopt with  RDS_FREE_MR,  giving  the
              RDMA cookie and additional flags as arguments.

       RDS_RECVERR
              This  is  a  boolean option which can be set as well as queried (using getsockopt).
              When enabled, RDS will send RDMA notification messages to the application  for  any
              RDMA operation that fails. This option defaults to off.

       For all of these calls, the level argument to setsockopt is SOL_RDS.

RDMA MACROS AND TYPES

       RDMA cookie
              typedef u_int64_t       rds_rdma_cookie_t

              This  encapsulates  a  memory  location  in  the  client  process.  In  the current
              implementation, it contains the R_Key of the remote memory region, and  the  offset
              into it (so that the application does not have to worry about alignment.

              The   RDMA   cookie   is  used  in  several  struct  types  described  below.   The
              RDS_CMSG_RDMA_DEST control message contains a rds_rdma_cookie_t all  by  itself  as
              payload.

       Mapping arguments
              The  following  data  type is used with RDS_CMSG_RDMA_MAP control messages and with
              the RDS_GET_MR socket option:

              struct rds_iovec {
                      u_int64_t       addr;
                      u_int64_t       bytes;
              };

              struct rds_get_mr_args {
                      struct rds_iovec vec;
                      u_int64_t       cookie_addr;
                      uint64_t        flags;
              };

              The cookie_addr specifies a memory location where to store the RDMA cookie.

              The flags value is a bitwise OR of any of the following flags:

              RDS_RDMA_USE_ONCE
                     This tells the kernel that the allocated RDMA cookie is to be  used  exactly
                     once.  When  the  RDMA  ACK  message  arrives, the kernel will automatically
                     unbind the memory area and release any resources associated with the cookie.

                     If this flag is not set, it is the application's responsibility  to  release
                     the memory region at a later time using the RDS_FREE_MR socket option.

              RDS_RDMA_INVALIDATE
                     Normally, RDMA memory mappings are invalidated lazily, as this requires some
                     relatively costly synchronization with the HCA. However, this means that the
                     server  application  can  continue  to access the registered memory for some
                     indeterminate amount of time.  If this  flag  is  set,  the  RDS  code  will
                     invalidate  the  mapping  at the time it is released (either upon arrival of
                     the RDMA ACK, if USE_ONCE was specified; or when the application destroys it
                     using FREE_MR).

       RDMA Operation
              RDMA  operations  are  initiated by the server using the RDS_CMSG_RDMA_ARGS control
              message, which takes the following data as payload:

              struct rds_rdma_args {
                      rds_rdma_cookie_t cookie;
                      struct rds_iovec remote_vec;
                      u_int64_t       local_vec_addr;
                      u_int64_t       nr_local;
                      u_int64_t       flags;
                      u_int32_t       user_token;
              };

              The cookie argument contains the RDMA cookie received from the client.   The  local
              memory  is  given  via  an  array  of  rds_iovecs.   The  array address is given in
              local_vec_addr, and its number of elements is given in nr_local.

              The struct member remote_vec specifies a  location  relative  to  the  memory  area
              identified  by  the  cookie:  remote_vec.addr  is  an  offset into that region, and
              remote_vec.bytes is the length of the memory window to copy to/from.   This  length
              must  match the size of the local memory area, i.e. the sum of bytes in all members
              of the local iovec.

              The flags field contains the bitwise OR of any of the following flags:

              RDS_RDMA_READWRITE
                     If set, any RDMA  WRITE  is  initiated  from  the  server's  memory  to  the
                     client's.  If  not  set, RDS will do a RDMA READ from the client's memory to
                     the server's memory.

              RDS_RDMA_FENCE
                     By default, Infiniband makes no guarantee about the ordering of an RDMA READ
                     with  respect to subsequent SEND operations. Setting this flag asks that the
                     RDMA READ should be fenced off the subsequent RDS ACK message. Setting  this
                     flag  requires  an  additional round-trip of the IB fabric, but it is a good
                     idea to use set this flag by default, unless you are really sure you do  not
                     want it.

              RDS_RDMA_NOTIFY_ME
                     This  flag  requests  a  notification  upon completion of the RDMA operation
                     (successful or otherwise). The noticiation will contain  the  value  of  the
                     user_token  field  passed in by the application. This allows the application
                     to release resources (such as buffers) assosicated with the RDMA transfer.

              The user_token can be used to  pass  an  application  specific  identifier  to  the
              kernel.  This  token  is  returned to the application when a status notification is
              generated (see the following section).

       RDMA Notification
              The RDS kernel code is able to notify the server application when an RDMA operation
              completes.  These  notifications  are  delivered  via  RDS_CMSG_RDMA_STATUS control
              messages.

              By default, no notifications are generated. There are two ways an  application  can
              request  them.  On one hand, status notifications can be enabled on a per-operation
              basis by setting the RDS_RDMA_NOTIFY_ME flag in the RDMA arguments.  On  the  other
              hand,  the  application can request notifications for all RDMA operations that fail
              by setting the RDS_RECVERR socket option (see below).  In both cases, the format of
              the  notification  is  the  same;  and  at  most  one notification will be sent per
              completed operation.

              The message format is this:

              struct rds_rdma_notify {
                      u_int32_t       user_token;
                      int32_t         status;
              };

              The user_token field contains the value previously  given  to  the  kernel  in  the
              RDS_CMSG_RDMA_ARGS  control message. The status field contains a status value, with
              0 indicating success, and non-zero indicating an error.

              The following status codes are currently defined:

              RDS_RDMA_SUCCESS
                     The RDMA operation succeeded.

              RDS_RDMA_REMOTE_ERROR
                     The RDMA operation failed due to a remote access error. This is usually  due
                     to an invalid R_key, offset or transfer size.

              RDS_RDMA_CANCELED
                     The RDMA operation was canceled by the application.  (This error code is not
                     yet generated).

              RDS_RDMA_DROPPED
                     RDMA operations were discarded  after  the  connection  broke  and  was  re-
                     established. The RDMA operation may have been processed partially.

              RDS_RDMA_OTHER_ERROR
                     Any other failure.

       RDMA setsockopt arguments
              When using the RDS_GET_MR socket option to register a memory range, the application
              passes a pointer to a struct rds_get_mr_args variable, described above.

              The RDS_FREE_MR call takes an argument of type struct rds_free_mr_args:

              struct rds_free_mr_args {
                      rds_rdma_cookie_t cookie;
                      u_int64_t       flags;
              };

              cookie specifies the RDMA cookie to be released. RDMA access to  the  memory  range
              will  usually  not  be  invoked  instantly, because the operation is rather costly.
              However, if the flags argument contains RDS_RDMA_INVALIDATE,  RDS  will  invalidate
              the indicated mapping immediately, as described in section Mapping arguments above.

              If  the  cookie  argument is 0, and RDS_RDMA_INVALIDATE is set, RDS will invalidate
              old memory mappings on all devices.

ERRORS

       In addition to the usual error codes returned by  sendmsg,  recvmsg  and  setsockopt,  RDS
       returns the following error codes:

       EAGAIN RDS  was  unable  to map a memory range because the limit was exceeded (returned by
              RDS_CMSG_RDMA_MAP and RDS_GET_MR).

       EINVAL When sending a message, there were were  conflicting  control  messages  (e.g.  two
              RDMA_MAP messages, or a RDMA_MAP  and a  RDMA_DEST message).

              In  a  RDS_CMSG_RDMA_MAP  or RDS_GET_MR operation, the application specified memory
              range greater than the maximum size supported.

              When setting up an RDMA operation with RDS_CMSG_RDMA_ARGS, the size  of  the  local
              memory (given in the rds_iovec) did not match the size of the remote memory range.

       EBUSY  RDS was unable to obtain a DMA mapping for the indicated memory.

LIMITS

       Currently, the following limits apply

       ·      The  maximum  size  of  a  zerocopy  transfer  is 1MB. This can be adjusted via the
              fmr_message_size module parameter.

       ·      The maximum number of memory ranges that can be mapped is limited to  2048  at  the
              moment.  This  can be adjusted via the fmr_pool_size module parameter. However, the
              actual limit imposed by the hardware may in fact be lower.

AUTHORS

       RDS was written and is Copyright (C) 2007-2008 by Oracle, Inc.

                                                                                  RDS zerocopy(7)