contrib/ofed/libmlx4/README

   1 Introduction
   2 ============
   3
   4 libmlx4 is a userspace driver for Mellanox ConnectX InfiniBand HCAs.
   5 It is a plug-in module for libibverbs that allows programs to use
   6 Mellanox hardware directly from userspace.  See the libibverbs package
   7 for more information.
   8
   9 Using libmlx4
  10 ==============
  11
  12 libmlx4 will be loaded and used automatically by programs linked with
  13 libibverbs.  The mlx4_ib kernel module must be loaded for HCA devices
  14 to be detected and used.
  15
  16 Supported Hardware
  17 ==================
  18
  19 libmlx4 currently supports HCAs based on the following Mellanox chip:
  20
  21     MT25408 ConnectX (PCI Express)
  22
  23 These HCAs use the mlx4_ib kernel driver.  Support for other Mellanox
  24 HCAs, which use the ib_mthca kernel driver, is provided by the
  25 libmthca userspace driver.
  26
  27 Valgrind Support
  28 ================
  29
  30 When running applications that use libibverbs under the Valgrind
  31 memory-checking debugger, Valgrind will falsely report "read from
  32 uninitialized" for memory that was initialized by the kernel drivers
  33 or HCA hardware.  Specifically, Valgrind cannot see when kernel
  34 drivers or HCA hardware write to userspace memory, so when the process
  35 reads from that memory, Valgrind incorrectly assumes that the memory
  36 contents are uninitialized, and therefore raises a warning.
  37
  38 libmlx4 can be built with specific support for the Valgrind
  39 memory-checking debugger by specifying the --with-valgrind command
  40 line argument to configure.  This flag enables code in libibverbs to
  41 tell Valgrind "this memory may look uninitialized, but it's really
  42 OK," which therefore suppresses the incorrect "read from
  43 uninitialized" warnings.  This code adds trivial overhead to the
  44 critical performance path, so it is disabled by default.  The intent
  45 is that production users can use a "normal" build of libmlx4 and
  46 developers can use the "valgrind debug" build by simply switching
  47 their OPENIB_DRIVER_PATH environment variables.
  48
  49 Libmlx4 needs some header files from Valgrind in order to compile this
  50 support; it is important to use the header files from the same version
  51 of Valgrind that will be used at run time.  You may need to specify
  52 the directory where Valgrind's header files are installed as an
  53 argument to --with-valgrind.  For example
  54
  55         ./configure --with-valgrind=/opt/valgrind
  56
  57 will make the libmlx4 build look for valgrind headers in
  58 /opt/valgrind/include