contrib/ofed/libmthca/README

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