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