contrib/ofed/librdmacm/man/rsocket.7.in

   1 .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
   2 .TH "RSOCKET" 7 "2013-01-21" "librdmacm" "Librdmacm Programmer's Manual" librdmacm
   3 .SH NAME
   4 rsocket \- RDMA socket API
   5 .SH SYNOPSIS
   6 .B "#include <rdma/rsocket.h>"
   7 .SH "DESCRIPTION"
   8 RDMA socket API and protocol
   9 .SH "NOTES"
  10 Rsockets is a protocol over RDMA that supports a socket-level API
  11 for applications.  Rsocket APIs are intended to match the behavior
  12 of corresponding socket calls, except where noted.  Rsocket
  13 functions match the name and function signature of socket calls,
  14 with the exception that all function calls are prefixed with an 'r'.
  15 .P
  16 The following functions are defined:
  17 .P
  18 rsocket
  19 .P
  20 rbind, rlisten, raccept, rconnect
  21 .P
  22 rshutdown, rclose
  23 .P
  24 rrecv, rrecvfrom, rrecvmsg, rread, rreadv
  25 .P
  26 rsend, rsendto, rsendmsg, rwrite, rwritev
  27 .P
  28 rpoll, rselect
  29 .P
  30 rgetpeername, rgetsockname
  31 .P
  32 rsetsockopt, rgetsockopt, rfcntl
  33 .P
  34 Functions take the same parameters as that used for sockets.  The
  35 follow capabilities and flags are supported at this time:
  36 .P
  37 PF_INET, PF_INET6, SOCK_STREAM, SOCK_DGRAM
  38 .P
  39 SOL_SOCKET - SO_ERROR, SO_KEEPALIVE (flag supported, but ignored),
  40 SO_LINGER, SO_OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF
  41 .P
  42 IPPROTO_TCP - TCP_NODELAY, TCP_MAXSEG
  43 .P
  44 IPPROTO_IPV6 - IPV6_V6ONLY
  45 .P
  46 MSG_DONTWAIT, MSG_PEEK, O_NONBLOCK
  47 .P
  48 Rsockets provides extensions beyond normal socket routines that
  49 allow for direct placement of data into an application's buffer.
  50 This is also known as zero-copy support, since data is sent and
  51 received directly, bypassing copies into network controlled buffers.
  52 The following calls and options support direct data placement.
  53 .P
  54 riomap, riounmap, riowrite
  55 .TP
  56 off_t riomap(int socket, void *buf, size_t len, int prot, int flags, off_t offset)
  57 .TP
  58 Riomap registers an application buffer with the RDMA hardware
  59 associated with an rsocket.  The buffer is registered either for
  60 local only access (PROT_NONE) or for remote write access (PROT_WRITE).
  61 When registered for remote access, the buffer is mapped to a given
  62 offset.  The offset is either provided by the user, or if the user
  63 selects -1 for the offset, rsockets selects one.  The remote peer may
  64 access an iomapped buffer directly by specifying the correct offset.
  65 The mapping is not guaranteed to be available until after the remote
  66 peer receives a data transfer initiated after riomap has completed.
  67 .PP
  68 In order to enable the use of remote IO mapping calls on an rsocket,
  69 an application must set the number of IO mappings that are available
  70 to the remote peer.  This may be done using the rsetsockopt
  71 RDMA_IOMAPSIZE option.  By default, an rsocket does not support
  72 remote IO mappings.
  73 riounmap
  74 .TP
  75 int riounmap(int socket, void *buf, size_t len)
  76 .TP
  77 Riounmap removes the mapping between a buffer and an rsocket.
  78 .P
  79 riowrite
  80 .TP
  81 size_t riowrite(int socket, const void *buf, size_t count, off_t offset, int flags)
  82 .TP
  83 Riowrite allows an application to transfer data over an rsocket
  84 directly into a remotely iomapped buffer.  The remote buffer is specified
  85 through an offset parameter, which corresponds to a remote iomapped buffer.
  86 From the sender's perspective, riowrite behaves similar to rwrite.  From
  87 a receiver's view, riowrite transfers are silently redirected into a pre-
  88 determined data buffer.  Data is received automatically, and the receiver
  89 is not informed of the transfer.  However, iowrite data is still considered
  90 part of the data stream, such that iowrite data will be written before a
  91 subsequent transfer is received.  A message sent immediately after initiating
  92 an iowrite may be used to notify the receiver of the iowrite.
  93 .P
  94 In addition to standard socket options, rsockets supports options
  95 specific to RDMA devices and protocols.  These options are accessible
  96 through rsetsockopt using SOL_RDMA option level.
  97 .TP
  98 RDMA_SQSIZE - Integer size of the underlying send queue.
  99 .TP
 100 RDMA_RQSIZE - Integer size of the underlying receive queue.
 101 .TP
 102 RDMA_INLINE - Integer size of inline data.
 103 .TP
 104 RDMA_IOMAPSIZE - Integer number of remote IO mappings supported
 105 .TP
 106 RDMA_ROUTE - struct ibv_path_data of path record for connection.
 107 .P
 108 Note that rsockets fd's cannot be passed into non-rsocket calls.  For
 109 applications which must mix rsocket fd's with standard socket fd's or
 110 opened files, rpoll and rselect support polling both rsockets and
 111 normal fd's.
 112 .P
 113 Existing applications can make use of rsockets through the use of a
 114 preload library.  Because rsockets implements an end-to-end protocol,
 115 both sides of a connection must use rsockets.  The rdma_cm library
 116 provides such a preload library, librspreload.  To reduce the chance
 117 of the preload library intercepting calls without the user's explicit
 118 knowledge, the librspreload library is installed into %libdir%/rsocket
 119 subdirectory.
 120 .P
 121 The preload library can be used by setting LD_PRELOAD when running.
 122 Note that not all applications will work with rsockets.  Support is
 123 limited based on the socket options used by the application.
 124 Support for fork() is limited, but available.  To use rsockets with
 125 the preload library for applications that call fork, users must
 126 set the environment variable RDMAV_FORK_SAFE=1 on both the client
 127 and server side of the connection.  In general, fork is
 128 supportable for server applications that accept a connection, then
 129 fork off a process to handle the new connection.
 130 .P
 131 rsockets uses configuration files that give an administrator control
 132 over the default settings used by rsockets.  Use files under
 133 @CMAKE_INSTALL_FULL_SYSCONFDIR@/rdma/rsocket as shown:
 134 .P
 135 .P
 136 mem_default - default size of receive buffer(s)
 137 .P
 138 wmem_default - default size of send buffer(s)
 139 .P
 140 sqsize_default - default size of send queue
 141 .P
 142 rqsize_default - default size of receive queue
 143 .P
 144 inline_default - default size of inline data
 145 .P
 146 iomap_size - default size of remote iomapping table
 147 .P
 148 polling_time - default number of microseconds to poll for data before waiting
 149 .P
 150 All configuration files should contain a single integer value.  Values may
 151 be set by issuing a command similar to the following example.
 152 .P
 153 echo 1000000 > @CMAKE_INSTALL_FULL_SYSCONFDIR@/rdma/rsocket/mem_default
 154 .P
 155 If configuration files are not available, rsockets uses internal defaults.
 156 Applications can override default values programmatically through the
 157 rsetsockopt routine.
 158 .SH "SEE ALSO"
 159 rdma_cm(7)