************************************************************************
*           Myricom GM networking software and documentation           *
*                 Copyright (c) 2002 by Myricom, Inc.                  *
* All rights reserved.  See the file `COPYING' for copyright notice.   *
************************************************************************
 
README-aix for gm-1.6
 
    Supported platforms:  PowerPC running AIX 4.3 or AIX 5L 5.1.
                          
                          Other AIX platforms have not been tested, but
                          may be supportable by this binary, or by building
                          from source with few or no modifications.  If you
                          need support for such platforms, please contact
                          help@myri.com.

   Supported interfaces:  LANai7 (PCI64, PCI64A), and LANai9 (PCI64B, PCI64C)
 
Table of Contents:
-----------------

  I.  GM Binary Installation
      a.  Unpacking and installing the GM driver and other software
      b.  Loading the driver
      c.  Initializing the driver
      d.  Running the GM Mapper
      e.  Testing the GM Installation
 II.  GM Source Installation
      a.  Unpacking the GM Source Tree
      b.  Configuring and Compiling GM and Other Software
      c.  Installing, Loading, and Initializing the GM Driver
III.  Verifying GM Performance
 IV.  IP support via Ethernet Emulation 
  V.  Miscellaneous
      a.  De-installation of the GM Software
      b.  Rebooting the Host Platform
 
************************************************************************
If difficulties are encountered, please consult the FAQ
         http://www.myri.com/scs/GM_FAQ.html
and all technical support questions should be directed to help@myri.com.
************************************************************************

=========================
I. GM Binary Installation
=========================

These GM binaries assume the use of LANai9 or LANai7 interfaces.
If you need to use LANai4 interfaces with your AIX platform,
please contact help@myri.com.

-----------------------------------------
a. Unpacking and installing the GM driver:
-----------------------------------------

        gunzip -c gm-1.6.4_AIX.tar.gz | tar xvf -

The next step will install the GM driver and other software and
configuration files in /opt/gm/ or in an installation directory
of your choice.  In either case, the directory must exist before
executing this step, and it must be writable by the user doing
the installation (usually root, as shown below).

If this installation is to be shared by more than one host,
it is best to specify an installation directory that will be 
accessible to all of them, i.e., in an NFS-mounted filesystem.

        su root
        cd gm-1.6.4-000759AF4C00-AIX-3
        ./GM_INSTALL [--verbose] [[--prefix=]<install_dir>]

<install_dir> must be an absolute pathname; it must start with "/".
However, it may contain symbolic links.

The rest of these instructions use "<install_dir>" to represent
your installation directory, even if you used the default
"/opt/gm/".

----------------------
b.  Loading the driver:
----------------------

If Step a is successful, you will be prompted to load the
driver, like this:

    GM shared parts are now installed.  Remember to run
            <install_dir>/sbin/gm_install_drivers
    as root on each machine that will use GM to make GM useable
    on that machine.

Like GM_INSTALL, the gm_install_drivers script supports a
"--verbose" option for greater visibility.

---------------------------
c.  Initializing the driver:
---------------------------

When the driver load is successful, you will see another prompt:

    GM drivers are now installed.  Remember to run
            /usr/local/etc/rc.d/gm start
    to start the GM driver.

Here, again, you can add a "--verbose" option to the command
(insert it between "gm" and "start").

The last action of the "gm start" command is to run the program
gm_board_info, which gives you a first-level sanity test of the
installation.  Ordinarily, gm_board_info will report the
information about the Myrinet card in this host, but will not
show routes or node ids, pending running the mapper.

In addition to "start", the /usr/local/etc/rc.d/gm command
supports options "stop" and "restart".

-------------------------
d.  Running the GM Mapper:
-------------------------

Step a above has installed the mapper in <install_dir>/sbin.

Still as root:

    <install_dir>/sbin/mapper <install_dir>/etc/gm/map_once.args

There are 3 ways in which the GM Mapper can be run.  Refer to the
section 'Running the GM Mapper' of the README-linux for further
details.

-------------------------------
e.  Testing the GM Installation:
-------------------------------

A variety of test programs and scripts are available in
<install_dir>/bin/ to test your GM installation.  We recommend
the five tests described in tests/README.


==========================
II. GM Source Installation
==========================

Building GM from source requires the VaC compilers (C and C++)
and GNU make (hereinafter referred to as "gmake", although its
name may be simply "make" at your site).  The build must be done
on an AIX 4.3 or 5.1 platform.

Note that in general, you do *not* need to build the MCP;
prebuilt MCPs are included in the source tree.

--------------------------------
a.  Unpacking the GM Source Tree:
--------------------------------

The source tarball must be unpacked into a location where it will
be accessible (mountable) by the AIX host on which you will be
performing the build.

        gunzip -c gm-1.6.4_Linux_and_AIX.tar.gz | tar xvf -

The root of the source tree produced by the above command will be
named (gm-1.6.4_Linux_and_AIX).  We will refer to this name as
GM_ROOT from now on.


---------------------------------------------------
b.  Configuring and Compiling GM and Other Software:
---------------------------------------------------

	cd {GM_HOME}
        ./configure
	gmake

The gmake step will require several minutes.  If any errors occur,
please notify help@myri.com.

-------------------------------------------------------
c.  Installing, Loading, and Initializing the GM Driver:
-------------------------------------------------------

The "gmake" step above will create and populate a subdirectory
$GM_HOME/binary/, which is essentially identical to the binary
tree "<install_dir>" described in Step I.a above.

As root:

        cd $GM_HOME/binary

and proceed with GM_INSTALL as described in Step I.a.  Then follow
with Steps I.b through I.e.

 
=============================
III. Verifying GM Performance
=============================
 
We recommend the following test to verify the GM performance.  View
the results of the hardware benchmark test of the PCI bus with the
DMA engine of the Myrinet adapter.
 
       cd <install_dir>/bin
       ./gm_debug --no-counters
 
Note: 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 README file in the GM
      distribution for complete details on expected GM performance.
 

=====================================
IV. IP support via Ethernet Emulation 
=====================================

Assuming that AIX has assigned the name "ent2" to the Myrinet
device, IP over Myrinet is enabled as follows:

        ifconfig en2 <ipaddr> up

The following commands terminate and detach IP over Myrinet:

        ifconfig en2 down
        ifconfig en2 detach


================
V. Miscellaneous
================

-------------------------------------
a. De-installation of the GM Software:
-------------------------------------

The gm_install_drivers script generates the script
/sbin/gm_uninstall_drivers, which can be used to stop and unload
the driver.
 
The GM_INSTALL script generates the script
<install_dir>/sbin/GM_UNINSTALL, which can be used to uninstall
all GM software.

------------------------------
b. Rebooting the Host Platform:
------------------------------

By design, this driver does _not_ automatically initialize upon
host reboot.  Instead, after a reboot, you load/initialize it at
your convenience by repeating Steps I.c and I.d above.
