************************************************************************
*           Myricom GM networking software and documentation           *
*                 Copyright (c) 2000, 2001 by Myricom, Inc.            *
* All rights reserved.  See the file `COPYING' for copyright notice.   *
************************************************************************

README for the GM Test Programs
======

A variety of test scripts are available in {GM_HOME}/binary/bin to test your
GM installation.  This directory contains two README files, 
{GM_HOME}/tests/README.logp_tests, which contains information to run
the LogP tests as described in the paper:

LogP Performance Assessment of Fast Network Interfaces
by David Culler, Lok Tin Liu, Richard P. Martin, and Chad Yoshikawa
University of California, Berkeley, Nov. 1995.

and this file, README, which contains information on the following test
programs:

gm_board_info
-------------

  `gm_board_info' displays information about the Myrinet interfaces on this
  host and the status of the GM ports.  If the mapper has been run, it also 
  displays information about the other interfaces reachable from these 
  interfaces on the Myrinet network, and the routes to them.

gm_debug
--------

  `gm_debug' is the interface used to access debugging information
  in GM.  By default it reports the results of the hardware benchmark
  of the PCI bus performed by the Myrinet adapter when the driver was
  loaded, along with the state of various event counters from the
  GM firmware, which the user might find useful.  GM debug optionally
  displays other debugging information.

gm_counters
-----------

  `gm_counters' displays diagnostic statistics about the operation of the 
  Myrinet interface.  This program is used almost exclusively for problem
  diagnosis.  The output from 'gm_counters' is a subset of the output from
  'gm_debug'.

gm_stress
---------

  `gm_stress' is an all-to-all random size, random order, communication
  test for GM.  It is used to stress the Myrinet fabric by sending
  massive amounts of data to all hosts in the cluster.

gm_allsize
----------

  `gm_allsize' is a basic connectivity test for GM, and can also generate
  performance data.  It verifies performance and correctness of message
  passing between specific ports on specific interfaces. It operates between
  specified hosts, or (by default) in loopback mode.  It optionally outputs
  data in a format ready for plotting by the gnuplot utility program.

For a list of all possible runtime options for these commands, you can issue 
the command with --help as the runtime option, e.g., ./gm_debug --help.

-----------------------------------------------------------------------
We recommend the following five tests to validate your GM installation.
-----------------------------------------------------------------------

   cd {GM_HOME}/binary/bin
 
   1. Test that the Mapper has correctly detected all of the hosts in your
      Myrinet network by typing the following command on several of the
      hosts:
 
      ./gm_board_info
 
      Note:  In the output of this command, all hosts should be listed in
             the routing table of each node.

             If not all of the hosts are listed, then it is possible that a
             cable is not connected, or GM is not properly loaded on all 
             hosts in the Myrinet network.  A green LED should be lit up
             on the switch for each connection that is active.

             If you see *** No routes found *** in the output, this is
             an indication that the GM Mapper has not been run.  (See
             README-<arch> for details.)

             When ./gm_board_info successfully reports a list of hosts,
             you can then run ./gm_allsize and ./gm_stress to test the
             network.
 
   2. Test the basic connectivity of GM, by typing:
 
      ./gm_allsize --verify --geometric
 
      on one of the hosts in the Myrinet network.
 
      Note:  This loopback test will NOT work in a point-to-point (no switch)
             configuration.
 
   3. Test GM bandwidth between two hosts, type (on the first host)
 
      ./gm_allsize --slave --size=15
 
      and then type the following command (on the second host)
 
      ./gm_allsize --unidirectional --bandwidth --remote-host=<host1> \
 	--size=15 --geometric

      where <host1> is the name of the first host.

      These one-way tests are performed by running in slave mode on one
      machine and master on the node to be tested. This is done by adding
      '--slave' on the command line of the slave machine and '-h <host>' on
      the command line of the master where <host> is the name of the machine
      running in slave mode. The name of each host is as specified in the 
      output of ./gm_board_info.  The --size parameter indicates the maximum
      length of message that will be sent, where 2^{size} is the value of
      that length.  In this example, the maximum length of message sent
      is 2^{15}=32K.  The --geometric parameter reduces the number of 
      message lengths that will be tested. The default for gm_allsize is 
      to test every length from 1 to 2^max_size incrementing one byte at
      a time.

      These tests take a long time to run, and generate data files suitable
      for input to gnuplot.

 
   4. Test GM latency between two hosts, type (on the first host)
 
      ./gm_allsize --slave --size=15
 
      and then type the following command (on the second host)
 
      ./gm_allsize --bidirectional --latency --remote-host=<host1> \
	 --size=15 --geometric
 
      where <host1> is the name of the first host.

      These one-way tests are performed by running in slave mode on one
      machine and master on the node to be tested. This is done by adding
      '--slave' on the command line of the slave machine and '-h <host>' on
      the command line of the master where <host> is the name of the machine
      running in slave mode. The name of each host is as specified in the 
      output of ./gm_board_info.  The --size parameter indicates the maximum
      length of message that will be sent, where 2^{size} is the value of
      that length.  In this example, the maximum length of message sent
      is 2^{15}=32K.  The --geometric parameter reduces the number of 
      message lengths that will be tested. The default for gm_allsize is 
      to test every length from 1 to 2^max_size incrementing one byte at
      a time.

      These tests take a long time to run, and generate data files suitable for
      input to gnuplot.

   5. Run gm_stress on every host in the cluster to validate GM.
 
      Complete details on running gm_stress can be found on
      the FAQ.
           http://www.myri.com/scs/GM_FAQ.html#debug-stress
 
      This gm_stress command must be run simultaneously on each host, using
      the same list of host names in each case.  It can be run on any
      subset of hosts on the network.

--------------------------------------------------------------
We recommend the following test to verify your GM performance.
--------------------------------------------------------------

   1.  View the results of the hardware benchmark test of the PCI bus
       with the DMA engine of the Myrinet adapter.

       ./gm_debug --no-counters

       The output of this command gives the maximum sustained bandwidth 
       that can be obtained from the PCI bus.  Refer to the section
       entitled "GM Performance" in the {GM_HOME}/README for complete details
       on expected GM performance.

--------------------------------------------------------------------------- 
If you encountered difficulties during the installation or testing phase of 
GM and you send a message to help@myri.com, we will ask you for the output
of several of these tests.
--------------------------------------------------------------------------- 

If you have questions or comments about this documentation, email
"help@myri.com."
