IBUTILS in OFED 1.0 Release Notes
=================================

June 2006


Overview
-------- 
The IBUTILS package provides means for debugging the connectivity and
status of InfiniBand (IB) devices in a fabric.  
The package tools are intended to provide the following services:   
* Discover the InfiniBand fabric connectivity
* Subnet manager is running or not
* Identify links which drop packets and/or incur errors by sending mad
  packets multiple times, across all the links  
* Fabric level mismatches or inconsistencies such as:
  - Duplicate port GUIDs - Two or more different ports with the same GUID
  - Duplicate node GUIDs - Two or more different nodes with the same node GUID
  - Duplicate LIDs - Two or more devices that have the same assigned LID
  - Zero valued LIDs - A device LID is equal to zero. This indicates that
    the SM did not assign this device with a LID  
  - Zero valued system GUIDs - A device system GUID is equal to zero
  - An Infiniband link is in INIT state which prevents data transfer 

The IBUTILS package includes the following stand-alone tools: 

ibdiagnet
	Discovers the network providing a listing of the following:
        - All the nodes, ports and links in the fabric 
        - Link Forwarding Tables (LFT) dump file 
        - Multicast Forwarding Tables (MFT) dump file 
        - Fabric Subnet Managers (SMs) query file and a list of all the masked
          GUIDs found
   
ibdiagpath
	Traces a path between two nodes specified by LIDs or a directed path of
	the source and destination nodes.
        ibdiagpath provides information regarding the nodes and ports traversed.
        It utilizes device specific health queries for the different devices
        along the path between the source and destination. 

Note: There are man pages for both tools.

The default directory for all files is /tmp 
   All the fabric reports are provided only after fabric discovery is completed.
   A summary of all the fabric SMs is created (reported in ibdiagnet.sm).

   Each report message includes: 
   - Device Type
   - Device portGUID
   - The direct path to the device 
   - If a topology file is provided to be matched with the discovered fabric,
     the node name is also provided in the report message. Otherwise, host
     names are included only in HCA related report messages.  


Known Issues

   ibdiagpath issues:
   - If no subnet manager is initialized in the subnet, FDB tables may be
     incorrectly set. Consequently, PortCounter MADs cannot be sent. 

   - A link along a LID-routed path in INIT state causes ibdiagpath performance
     queries to fail. The performance queries fail since they cannot proceed on 
     non-ACTIVE links. 

   - ibdiagpath cannot validate the provided topology file against the existing 
     fabric topology. If the topology file includes a device/link that does not
     exist, or the device/ link information is incorrect, then ibdiagpath may 
     -- in name-based routing -- extract a non-existing path based on the 
     incorrect topology file.

   - If the hostname provided for the -s flag is not the actual local hostname, 
     then all the extracted names from the topology file will be incorrect. 
     However, all the other information provided will be correct.


   IBUTILS Tools - General     
   - The path environment variable must include the path to ibis. To define the
     path to ibis use one of the following commands:
	export PATH=<path to ibis>:$PATH
      or
        setenv PATH <path to ibis>:$PATH  

   - IBUTILS tools cannot run from a host with more than one HCA.
     Workaround: Run the tools from a host with a single HCA card installed. 
     (To be fixed in the next release.)  

