contrib/ofed/libibverbs/README

   1 Introduction
   2 ============
   3
   4 libibverbs is a library that allows programs to use RDMA "verbs" for
   5 direct access to RDMA (currently InfiniBand and iWARP) hardware from
   6 userspace.  For more information on RDMA verbs, see the InfiniBand
   7 Architecture Specification vol. 1, especially chapter 11, and the RDMA
   8 Consortium's RDMA Protocol Verbs Specification.
   9
  10 Using libibverbs
  11 ================
  12
  13 Device nodes
  14 ------------
  15
  16 The verbs library expects special character device files named
  17 /dev/infiniband/uverbsN to be created.  When you load the kernel
  18 modules, including both the low-level driver for your IB hardware as
  19 well as the ib_uverbs module, you should see one or more uverbsN
  20 entries in /sys/class/infiniband_verbs in addition to the
  21 /dev/infiniband/uverbsN character device files.
  22
  23 To create the appropriate character device files automatically with
  24 udev, a rule like
  25
  26     KERNEL="uverbs*", NAME="infiniband/%k"
  27
  28 can be used.  This will create device nodes named
  29
  30     /dev/infiniband/uverbs0
  31
  32 and so on.  Since the RDMA userspace verbs should be safe for use by
  33 non-privileged users, you may want to add an appropriate MODE or GROUP
  34 to your udev rule.
  35
  36 Permissions
  37 -----------
  38
  39 To use IB verbs from userspace, a process must be able to access the
  40 appropriate /dev/infiniband/uverbsN special device file.  You can
  41 check the permissions on this file with the command
  42
  43         ls -l /dev/infiniband/uverbs*
  44
  45 Make sure that the permissions on these files are such that the
  46 user/group that your verbs program runs as can access the device file.
  47
  48 To use IB verbs from userspace, a process must also have permission to
  49 tell the kernel to lock sufficient memory for all of your registered
  50 memory regions as well as the memory used internally by IB resources
  51 such as queue pairs (QPs) and completion queues (CQs).  To check your
  52 resource limits, use the command
  53
  54         ulimit -l
  55
  56 (or "limit memorylocked" for csh-like shells).
  57
  58 If you see a small number such as 32 (the units are KB) then you will
  59 need to increase this limit.  This is usually done for ordinary users
  60 via the file /etc/security/limits.conf.  More configuration may be
  61 necessary if you are logging in via OpenSSH and your sshd is
  62 configured to use privilege separation.
  63
  64 Valgrind support
  65 ----------------
  66
  67 When running applications that use libibverbs under the Valgrind
  68 memory-checking debugger, Valgrind will falsely report "read from
  69 uninitialized" for memory that was initialized by the kernel drivers.
  70 Specifically, Valgrind cannot see when kernel drivers write to
  71 userspace memory, so when the process reads from that memory, Valgrind
  72 incorrectly assumes that the memory contents are uninitialized, and
  73 therefore raises a warning.
  74
  75 libibverbs can be built with specific support for the Valgrind
  76 memory-checking debugger by specifying the --with-valgrind command
  77 line argument to configure.  This flag enables code in libibverbs to
  78 tell Valgrind "this memory may look uninitialized, but it's really
  79 OK," which therefore suppresses the incorrect "read from
  80 uninitialized" warnings.  This code adds trivial overhead to the
  81 critical performance path, so it is disabled by default.  The intent
  82 is that production users can use a "normal" build of libibverbs and
  83 developers can use the "valgrind debug" build by simply switching
  84 their LD_LIBRARY_PATH environment variables.
  85
  86 Libibverbs needs some header files from Valgrind in order to compile
  87 this support; it is important to use the header files from the same
  88 version of Valgrind that will be used at run time.  You may need to
  89 specify the directory where Valgrind's header files are installed as
  90 an argument to --with-valgrind.  For example
  91
  92         ./configure --with-valgrind=/opt/valgrind
  93
  94 will make the libibverbs build look for valgrind headers in
  95 /opt/valgrind/include
  96
  97 Reporting bugs
  98 ==============
  99
 100 Bugs should be reported to the OpenFabrics mailing list
 101 <general@lists.openfabrics.org>.  In your bug report, please include:
 102
 103  * Information about your system:
 104    - Linux distribution and version
 105    - Linux kernel and version
 106    - InfiniBand/iWARP hardware and firmware version
 107    - ... any other relevant information
 108
 109  * How to reproduce the bug.  Command line arguments for a libibverbs
 110    example program or source code that other developers can
 111    compile and run is most convenient.
 112
 113  * If the bug is a crash, the exact output printed out when the crash
 114    occurred, including any kernel messages produced.
 115
 116  * If a verbs call is mysteriously returning an error or failing, the
 117    output of "strace -ewrite -ewrite=all <command>".
 118
 119 Submitting patches
 120 ==================
 121
 122 Patches should also be submitted to the OpenFabrics mailing list
 123 <general@lists.openfabrics.org>.  Please use unified diff form (the -u
 124 option to GNU diff), and include a good description of what your patch
 125 does and why it should be applied.  If your patch fixes a bug, please
 126 make sure to describe the bug and how your fix works.
 127
 128 Please include a change to the ChangeLog file (in standard GNU
 129 changelog format) as part of your patch.
 130
 131 Make sure that your contribution can be licensed under the same
 132 license as the original code you are patching, and that you have all
 133 necessary permissions to release your work.
 134
 135 TODO
 136 ====
 137
 138 1.1 series
 139 ----------
 140
 141 The libibverbs API and ABI are frozen for all releases in the 1.1
 142 series.  Methods were added to struct ibv_context to implement the
 143 following features, so it should be possible to add them in a future
 144 release in the 1.1 series:
 145
 146  * Memory window (MW) support.
 147
 148  * Implement the reregister memory region (MR) verb.  We will add an
 149    extension to the IB spec to allow the application to indicate that
 150    the region is only being extended, and that operations in progress
 151    should _not_ fail (contrary to the IB spec, which states that
 152    reregister must be implemented so that it behaves equivalently to a
 153    deregister followed by a register).
 154
 155 Other possibilities
 156 -------------------
 157
 158 There are no plans to implement the following features, which would be
 159 needed for completeness but don't seem particularly useful.  However,
 160 if there is demand from application developers or an implementation is
 161 contributed, then the feature may be added.
 162
 163  * Implement the query address handle (AH) verb.
 164  * Implement the query memory region (MR) verb.