NAME

e1x7diag − MVME1X7 LAN interface diagnostic test utility

SYNOPSIS

e1x7diag [-?BG] [{-c cntlr_num | -d dev_name}]
-t test_name [test_options] ... 

where test_name is one of:

{ all | diag | eloop | iloop }

where test_options for eloop and iloop are:

[[-i iterations] [-p packets]]

DESCRIPTION

The e1x7diag command is a diagnostic test utility for the MVME1X7 (or e1x7) on-board Local Area Network interface.  The user level command interacts with the e1x7 STREAMS driver via defined ioctl(2) commands (I/O controls).  The device driver then performs the requested diagnostic test on the hardware that it controls, returning the result to the utility.  The command then gives an indication of the individual test result, which is either "PASSED" or "FAILED".  It should be noted that the diagnostic tests run by this utility are of a non-destructive nature.  That is to say they can be run on a loaded system, with the interface up, and leave the system operational when the tests are completed.  However, the services that the interface provide are temporarily taken off-line for the duration of the tests.  This can impact the system, possibly introducing side affects at higher levels, if the interval of the test is suffuciently long. A knowledgable system administrator is the intended user of this utility. A practical usage is for on-line system analysis.

OPTIONS

The user may issue the following options on the e1x7diag command line:

-? Help flag. 
This flag will display a brief usage message to the user, yet offering enough information for the advanced user to run the command properly.

-B Boot-time diagnostics flag. 
Used when the e1x7diag command is being executed for boot-time diagnostic tests (see /etc/init.d/e1x7btd).  The -B flag will put the utility into boot-time mode, which will cause the utility to pass the result of all tests run back down to the e1x7 driver.  The result is then available via the various status gathering mechanisms for device drivers (see drv_getparm(1M,D3DK), frustat(1M)). 

-G GOLD mode flag. 
Used when the e1x7diag command is executed from within the GOLD package (see gold(1M)).  The -G flag will put the utility into GOLD mode, which will echo the command line arguments on stdout. 

-c cntlr_num
Specify the controller number of the e1x7 device on which the diagnostic tests are to be run. 
(default: 0)

-d dev_name
Specify the device name (path) of the e1x7 device on which the diagnostic tests are to be run. 
(default: /dev/e1x7_c0) NOTE: The -c and -d options are mutually exclusive; more specifically they provide the same information using a slightly different syntax. 

-t { all | diag }
Specify a test to execute, without optional parameters.

-t { eloop | iloop } [[-i iterations] [-p packets]]
Specify a test to execute, with optional parameters for the loopback tests.

-i iterations
Specify the number of iterations for a loopback test.
(default: 1) NOTE: If the value of iterations is 0 (zero), the test will loop "forever" or until the test is interrupted by the user. 

-p packets
Specify the number of packets to send per iteration for a loopback test.
(default: 100)

Test Names

The test_name keywords and definitions are as follows:

all The all test simply runs all of the "real" tests defined below in sequential order. 

diag The diag test executes the LANC chip (see NOTES) diagnose command. 

eloop The eloop test will run an external loopback test on the LANC chip.  The utility first sends an ioctl to turn loopback mode on, with a flag to indicate external mode.  Once this is completed, the utility simply goes into a loop for the number of iterations of the test.  Within this loop, the utility begins another loop.  The inner loop sends a single packet of data and then verifies the returned packet data.  This loop will continue for the number of packets per iteration value.  This particular method is implemented so as to let the user break out of a test.  (If the utility did not return to user context at a regular interval, the test would not be interruptable.)  When the loopback test is completed, either by completing iterations or by breaking out, the utility will send an ioctl to turn loopback mode off.  A hardware level explaination of the eloop test is in order here.  The external loopback mode of the LANC chip will test the transmit path of the hardware all the way to the medium (through serial interface unit).  The receiver detects data on the medium and so excerises the receive logic as well.  The interconnection of the transmitter and receiver takes place with a regular connection to a network medium. 

iloop The iloop test will run an internal loopback test on the LANC chip.  The utility first sends an ioctl to turn loopback mode on, with a flag to indicate internal mode.  Once this has been done, the test proceeds as in the eloop test above.  A hardware level explaination of the iloop test is in order here.  The internal loopback mode of the LANC chip will test the transmit path of the hardware right up to the point of giving the data to the serial interface unit (which puts the bits on the wire, or medium).  It is at this point the packet is turned around and given directly to the receive logic immediately.  So the receive path is also tested, sans the actual reading of data by the serial interface unit. 

EXAMPLES

The e1x7diag utility is simple and straight forward to use. 

e1x7diag -d /dev/e1x7_c0 -t all -B

The above command invokes the e1x7diag utility using the provided device on which to run the tests and it requests that the all test be executed.  The result of this command is seeing each test being run in a sequential order.  The -B option was also provided, which implies the result is passed down to the e1x7 STREAMS driver.  (This command is indeed the one run for boot-time diagnostics.) 

e1x7diag -c0 -t diag

The above command invokes the e1x7diag utility to run tests on controller 0 (zero, which happens to be the default).  In this case, we request that the LANC chip diagnose command be run. 

e1x7diag -t iloop -i0 -p64

The above command invokes the e1x7diag utility to run tests on the default device (/dev/e1x7_c0).  In this case, we request that the iloop test be run by itself.  There are also test options provided, which modify how the iloop in particular will be executed.  The -i option, with a 0 (zero) parameter, tells the utility to loop "forever".  However, the loopback tests are always interruptable at the user level.  The -p option tells the utility how many packets to send per iteration of the test. 

e1x7diag -t eloop -i32

The above command invokes the e1x7diag utility to run tests on the default device as well.  In this case, we request that the eloop test be run by itself.  A single test option is provided.  The -i option, with a parameter of 32, tells the utility to execute the external loopback test 32 times.  The default number of packets are sent on each iteration, as the -p option was not provided in this example. 

FILES

/etc/init.d/e1x7btd,
/etc/rc2.d/S68e1x7btd

SEE ALSO

drv_getparm(1M), frustat(1M), gold(1M), e1x7cntl(1M),
e1x7(7)

DIAGNOSTICS

If e1x7diag terminates normally, it displays a message that indicates whether the requested test(s) passed or failed, and then exits with a 0 status.  If e1x7diag does not terminate normally, it displays an error message to stderr and returns a non-zero exit status to indicate an error. 

NOTES

The Intel 82596 LAN Controller (or "LANC") is a chip used on the MVME1X7 single board computer.  The LANC chip provides the networking interface for IEEE 802.3 and ethernet type networks.  The e1x7 STREAMS driver supports more than one interface, but at the moment, it is only possible to have one hardware device per system.  Because this is the case, the -c and -d options are not required, as the default controller number and the default device name are the only possible choice.  These options are merely present now to support the full capabilities of the driver, should they ever be realized by hardware. 
 

  —  ENET1X7 Diagnostic Utility