[openib-general] [RFC] Proposed OpenIB Diagnostic Tools

[Hal Rosenstock]

Hi,

Attached is an initial proposal for diagnostic tools. They fall into two
categories: host and network. Applications (or scripts) and library
support would be supplied.

This is an initial writeup on the high level descriptions of the tools
and an initial syntax. All comments welcome.

BTW, are there coding guidelines for user space ?

Note that the implementation of these tools will take a back seat to
getting the OpenSM up and running with gen2.

At some point soon, I will put a copy of this in the gen2 tree perhaps
at /gen2/trunk/src/userspace/diags

-- Hal


-------------- next part --------------
Diagnostic Tools
11/29/04

user space applications (also library support)
two categories: host and network

Host Oriented Diagnostic Tools

1. ibstatus

Description:
ibstatus displays basic information obtained from the local IB driver.
-v enables verbose mode. Normal output includes LID, SMLID, port state,
link width active, and port physical state. Verbose includes all sysfs
supported parameters for that interface and port.

Syntax:
ibstatus [-v] [-I mthca0] [-p port]

Dependencies:
sysfs support in mthca

2. ibroute

Description:
ibroute uses SMPs to display the forwarding tables (unicast 
(LinearForwardingTable or LFT) or multicast (MulticastForwardingTable or MFT))
for the specified LID.

Syntax:
ibroute [-multi] [-m mkey] [-pa path] [-I mthca0] [-p port] LID

Dependencies:
user MAD access, SMA

3. ibtracert

Description:
ibtracert uses SMPs to trace the path from a source GID/LID to a 
destination GID/LID. The source GID/LID must be local to the node. 
Each hop along the path is displayed until the destination is reached or 
a hop does not respond. By using -mg and/or -ml options, multicast path
tracing can be performed between source and destination nodes.

Syntax:
ibtracert [-m mkey] [-pa path] [-sg SGID] [-sl SLID] [-dg DGID] [-dl DLID] \
		[-mg MGID] [-ml MLID] [-I mthca0] [-p port]

Dependencies:
user MAD access, SMA

4. smpquery

Description:
smpquery allows a basic subset of standard SMP queries including the following:
local information (LID, GID, etc.), node information (from NodeDescription,
NodeInfo, and possibly SwitchInfo if node is a switch), port information
(port address and state), and port parameters (SLtoVLMappingTable, 
VLArbitrationTable, HOQLife, ...).

Syntax:
smpquery [-m mkey] [-l LID] [-pa path] [-I mthca0] [-p port] \
	 	[-l] [-n] [-pi] [-pp]

Dependencies:
User MAD access

5. smpdump

Description:
smpdump is a general purpose SMP utility which gets SM attributes from a 
specified SMA. The result is dumped as hex (-x) or string (-s), with hex 
as the default.

Syntax:
smpdump [-m mkey] [-l LID] [-p path]  [-I mthca0] [-p port] \
		[-a attributeID] [-am attributeModifier] [-s] [-x]

Dependencies:
User MAD access

6. perfquery

Description:
perfquery uses PerfMgt GMPs to obtain the PortCounters (basic performance 
and error counters) from the PMA at the node specified. -r resets these 
counters after obtaining them.

Syntax:
perfquery [-I mthca0] [-p port] [-r] [-g GID] LID

Dependencies:
User MAD access, PMA

7. ibping

Description:
ibping uses UD transport to validate connectivity between IB nodes. 
It is run as client/server (daemon). -v option uses vendor MADs rather than
normal UD transport.

Syntax:
ibping [-d] [-v] [-c count] [-i interval] [-s packetsize] \
		[-I mthca0] [-p port] [-q qkey] [-g DGID] [-qp dqp] [-dl DLID] 

-d: run as daemon (server)

Dependencies:
user MAD access 


Network Oriented Diagnostics

8. ibnetdiscover

Description:
ibnetdiscover performs IB subnet discovery and outputs a human readable 
topology file. GUIDs, node types, and port numbers are displayed 
as well as port LIDs and NodeDescriptions. All nodes (and links) are displayed
(full topology).

Syntax:
ibnetdiscover [-I mthca0] [-p port] [-o topology-filename]

Dependencies:
user MAD access

Future versions of this file will be annotated with additional information
including system guid, system type, internal to physical mapping, and physical
location information (blade or ASIC number, etc.). 

9. ibhosts

Description:
ibhosts either walks the IB subnet topology or uses an already saved topology 
file and extracts the HCA nodes.

Syntax:
ibhosts [-I mthca0] [-p port] [-i topology-filename] [-o ibhosts-filename]

Dependencies:
user MAD access, ibnetdiscover

10. ibswitches

Description:
ibswitches either walks the IB subnet topology or uses an already saved 
topology file and extracts the IB switches. 

Syntax:
ibswitches [-I mthca0] [-p port] \
		[-i topology-filename] [-o ibswitches-filename]

Dependencies:
user MAD access, ibnetdiscover

11. ibnetverify

Description:
ibnetverify uses a full topology file that was created by ibnetdiscover, 
scans the network to see if the current topology matches or not displaying 
any discrepancies, and validates the connectivity and reports errors 
(from port counters).

Syntax:
ibnetverify -f filename [-I mthca0] [-p port]

Dependencies:
user MAD access, ibnetdiscover