lnet/klnds/mxlnd/README

   1 *************************************************************************
   2 *                                                                       *
   3 *    Myrinet Express Lustre Networking Driver (MXLND) documentation     *
   4 *                                                                       *
   5 *************************************************************************
   6
   7 README of MXLND
   8
   9 MXLND provides support for Myricom's Myrinet Express (MX) communication
  10 layer in Lustre.
  11
  12 MXLND may be used with either MX-10G or MX-2G. See MX's README for
  13 supported NICs.
  14
  15 Table of Contents:
  16     I. Installation
  17        1. Configuring and compiling
  18        2. Module Parameters
  19    II. MXLND Performance
  20   III. Caveats
  21        1. Systems with different page sizes
  22        2. Multi-homing
  23        3. MX endpoint collision
  24    IV. License
  25     V. Support
  26
  27 ================
  28 I. Installation
  29 ================
  30
  31 MXLND is supported on Linux 2.6. It may be possible to run it on 2.4,
  32 but it has not been tested. MXLND requires Myricom's MX version 1.2.8
  33 or higher. See MX's README for the supported list of processors.
  34
  35 MXLND requires the optional MX kernel library interface. MX must be compiled
  36 with --enable-kernel-lib.
  37
  38 1. Configuring and compiling
  39
  40 MXLND should be already integrated into the Lustre build process. To
  41 build MXLND, you will need to set the path to your MX installation
  42 in Lustre's ./configure:
  43
  44     --with-mx=/opt/mx
  45
  46 replacing /opt with the actual path. Configure will check to ensure that
  47 the MX version has the required functions. If not, it will fail to build.
  48 To check if MXLND built, look for:
  49
  50     checking whether to enable Myrinet MX support... yes
  51
  52 in configure's output or the presence of Makefile in
  53 $LUSTRE/lnet/klnds/mxlnd.
  54
  55 2. Module Parameters
  56
  57 MXLND supports a number of load-time parameters using Linux's module
  58 parameter system. On our test systems, we created the following file:
  59
  60     /etc/modprobe.d/kmxlnd
  61
  62 On some (older?) systems, you may need to modify /etc/modprobe.conf.
  63
  64 The available options are:
  65
  66     n_waitd     # of completion daemons
  67     cksum       set non-zero to enable small message (< 4KB) checksums
  68     ntx         # of total tx message descriptors
  69     peercredits # concurrent sends to one peer
  70     board       index value of the Myrinet board
  71     ep_id       MX endpoint ID
  72     ipif_name   IPoMX interface name
  73     polling     Use 0 to block (wait). A value > 0 will poll that many times before blocking
  74
  75     credits     Unused - was # concurrent sends to all peers
  76     max_peers   Unused - was maximum number of peers that may connect
  77     hosts       Unused - was IP-to-hostname resolution file
  78
  79 You may want to vary the options to obtain the optimal performance for your
  80 platform.
  81
  82     n_waitd sets the number of threads that process completed MX requests
  83 (sends and receives). In our testing, the default of 1 performed best.
  84
  85     cksum turns on small message checksums. It can be used to aid in trouble-
  86 shooting. MX also provides an optional checksumming feature which can check
  87 all messages (large and small). See the MX README for details.
  88
  89     ntx is the number of total sends in flight from this machine.
  90
  91     peercredits is the number of in-flight messages for a specific peer. This is part
  92 of the flow-control system in Lustre. Increasing this value may improve performance
  93 but it requires more memory since each message requires at least one page.
  94
  95     board is the index of the Myricom NIC. Hosts can have multiple Myricom NICs
  96 and this identifies which one MXLND should use.
  97
  98     ep_id is the MX endpoint ID. Each process that uses MX is required to have at
  99 least one MX endpoint to access the MX library and NIC. The ID is a simple index
 100 starting at 0. When used on a server, the server will attempt to use this end-
 101 point. When used on a client, it specifies the endpoint to connect to on the
 102 management server.
 103
 104     ipif_name is the name of the Ethernet interface over MX. Generally, it is
 105 myriN, where N matches the MX board index.
 106
 107     polling determines whether this host will poll or block for MX request com-
 108 pletions. A value of 0 blocks and any positive value will poll that many times
 109 before blocking. Since polling increases CPU usage, we suggest you set this to
 110 0 on the client and experiment with different values for servers.
 111
 112 =====================
 113 II. MXLND Performance
 114 =====================
 115
 116 On MX-2G systems, MXLND should easily saturate the link and use minimal CPU
 117 (5-10% for read and write operations). On MX-10G systems, MXLND can saturate
 118 the link and use moderate CPU resources (20-30% for read and write operations).
 119 MX-10G relies on PCI-Express which is relatively new and performance varies
 120 considerably by processor, motherboard and PCI-E chipset. Refer to Myricom's
 121 website for the latest DMA read/write performance results by motherboard. The
 122 DMA results will place an upper-bound on MXLND performance.
 123
 124 ============
 125 III. Caveats
 126 ============
 127
 128 1. Systems with different page sizes
 129
 130 MXLND will set the maximum small message size equal to the kernel's page size.
 131 This means that machines running MXLND that have different page sizes are not
 132 able to communicate with each other. If you wish to run MXLND in this case,
 133 send email to help@myri.com.
 134
 135 2. Multi-homing
 136
 137 At this time, the MXLND does not support more than one interface at a time.
 138 Thus, a single Lustre router cannot route between two MX-10G, between two
 139 MX-2G, or between MX-10G and MX-2G fabrics.
 140
 141 3. MX endpoint collision
 142
 143 Each process that uses MX is required to have at least one MX endpoint to
 144 access the MX library and NIC. Other processes may need to use MX and no two
 145 processes can use the same endpoint ID.  MPICH-MX dynamically chooses one at
 146 MPI startup and should not interfere with MXLND. Sockets-MX, on the other hand,
 147 is hard coded to use 0 for its ID. If it is possible that anyone will want to
 148 run Sockets-MX on this system, use a non-0 value for MXLND's endpoint ID.
 149
 150
 151 ===========
 152 IV. License
 153 ===========
 154
 155 MXLND is copyright (C) 2006 of Myricom, Inc.
 156
 157 MXLND is part of Lustre, http://www.lustre.org.
 158
 159 MXLND is free software; you can redistribute it and/or modify it under the
 160 terms of version 2 of the GNU General Public License as published by the Free
 161 Software Foundation.
 162
 163 MXLND is distributed in the hope that it will be useful, but WITHOUT ANY
 164 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 165 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 166
 167 You should have received a copy of the GNU General Public License along with
 168 Lustre; if not, write to the Free Software Foundation, Inc., 675 Mass Ave,
 169 Cambridge, MA 02139, USA.
 170
 171 ==========
 172 V. Support
 173 ==========
 174
 175 If you have questions about MXLND, please contact help@myri.com.