Combined End of Line Tool for the Intel(R) Adapters
===================================================
April 21, 2016

Contents
========
- OVERVIEW
- RUNNING THE UTILITY
- LOGFILE
- OPTIONS
- INVM FILE FORMAT
- EXAMPLES
- INVALID TEST SCENARIO
- ERROR CODES
- INSTALLATION
- CUSTOMER SUPPORT
- LEGAL


OVERVIEW
========
Combined End of Line Tool (CELO) is a command line LAN Hardware Diagnostic
tool. This tool runs similar to DIAGS.EXE, but runs in batch mode. It outputs
to the screen and a logfile for parsing at a later time.

Notes:
 - When the device is in MFP (Multiple Functions per Port)mode (such as
   Dell's NPAR technology), the loopback diagnostic test is not supported.

 - On the Intel(R) Ethernet Switch FM10000 Host Interface, loopback diagnostic
   tests, and other tests that rely on the loopback test, will fail if the
   Switch Manager is not running.


RUNNING THE UTILITY
===================
Using the "/?" option will display a list of supported command line options.
If the utility is run with no parameters, it runs through applicable
Non-Network diagnostics: Device Registers, EEPROM, Interrupt, and FIFO tests.
All available Intel adapters are located and tested. When finished, it exits
back to the command prompt.


LOGFILE
-------
All test results are stored in a logfile called 'celo.log'.
This file is stored in the same directory that you ran
CELO from.


OPTIONS
-------
Non-Network Diagnostics:
  /DIAGS	- Run Non-Network diagnostic tests: EEPROM, FIFOS, REGS
 		  and internal loopback.
  /EEPROM	- Test EEPROM Checksum.
  /FIFOS	- Test FIFOS on Network Adapter.
  /FLASH 	- Tests for a working flash.
  /IRQ		- Test Network Adapter IRQ.
  /MACADDR X	- Checks first three bytes of MAC address. Where X is a six
 		  digit hex number. Up to five MAC address prefixes, separated
 		  by spaces, can be tested.
  /RDMA	- Tests RDMA engine.
  /REGS		- Perform Read/Write tests on network adapter.

Network Diagnostics:
  /CARD=XX	- Allows user to select which Network Adapter to test (1-32).
  /CARD X Y Z	- Test card installed at x, y, z, where
		  x = Bus #, y = Device #, and z = Function #.
  /EXCLUDE=XX	- Allows user to select a Network Adapter to exclude from
		  testing (1-32).
  /EXCLUDE X Y Z - Exclude card installed at x, y, z from testing, where
		  x = Bus #, y = Device #, and z = Function #. When this
		  option is used CELO assumes that only the card being
		  excluded may have drivers loaded on it. If this is not the
		  case, and if drivers are present on cards being tested then
		  results are unpredictable (it will result in system hang).
  /EXTLB [W X Y Z]  - Test External Loopback with an external dongle where:
		    W = <10Mbps Tx Count	- default: 500>
		    X = <100Mbps Tx Count	- default: 500>
		    Y = <1000Mbps Tx Count	- default: 5000>
		    Z = <10000Mbps Tx Count	- default: 5000>
  /HOTSWAP	- Test PCI Express card with Hotswap feature.
		  Hotswap stops the test and prompts the user to swap the card.
		  Note: This is system dependent and may not work.

  /LB		- Runs the Internal Loopback Test. It runs the best loopback test
		  that the adapter supports.
  /LINK		- Check for network Adapter Link. Note: This test is
		  supported in auto-negotiation mode. The TTL test is recommended
		  over the LINK test.
  /MAXSPEED	- Deprecated. Peer responder now fails if it cannot link at
		  the max common speed supported by *both* sender and
		  responder.
  /NETWORK	- Run Network specific diagnostic tests: LINK,NWTEST.
  /NIC=XX	Selects a specific adapter.
  /NWTEST	- Run Network Test which searches for a responder, when the
		  responder is located, it sends directed packets to the
		  responder in lock-step. It sends packets in random sizes with
		  varying data contents and validates the contents of each packet.
		  If a responder does not exist, the test fails.
		  Note: You must have link to run this test.
  /SENDRESP [X Y]- Run peer sender/responder test from NIC X to NIC Y both
		  present in the same system. This will send a preset number
		  of packets from one adapter to the other and verify
		  reception and validity of the packets from the partner.
		  This will run the test at all speeds supported by both the
		  sender adapter and the responder adapter. This is a
		  hardware test to verify adapter design functionality.
		  Note: This test assumes the adapters are connected directly,
		  via a crossover cable not through a switch or a hub.
		  Results going through a switch or hub are not predictable.
		  No support for Spanning Tree environments.
  /TDR		- Run TDR Test.
  /TIMEOUT [n]	- When used with the /EXTLB command, the /TIMEOUT option will
  /TTL		- The Time To Link Test will time how long it takes to
		  link with the specified link partner. Different link speed
		  can be set by both forcing and auto-negotiating to test at
		  various speeds and settings.
		  cause the test to fail after the specified 'n' number of seconds.
Bypass configuration:
  /BYPASS_AUX_ON=mode	- Determines what action the microcontroller
			  should take on first power on when aux supply
			  is applied.
  /BYPASS_AUX_OFF=mode	- Determines what action the microcontroller
			  should take if a power failure is detected.
  /BYPASS_DEVICES	- Shows available adapters and bypass support.
  /BYPASS_FORCE=forceMode - Force requested state on switching matrix.
  /BYPASS_MAIN_ON=mode	- Determines what action the microcontroller
			  should take on system power on when the main supply is
			  ramped up.
  /BYPASS_MAIN_OFF=mode	- Determines what action the microcontroller
			  should take on system power down when the main supply
			  is ramped down.
  /BYPASS_STATUS	- Display status of the relays.
  /BYPASS_WD_TIMEOUT=mode - Determines what action the microcontroller
			  should take if watchdog timeout event is detected.
  /BYPASS_ENABLE_WD	- Enables Watchdog Timer.
  /BYPASS_DISABLE_WD	- Disables Watchdog Timer.
  /BYPASS_WD_TIMEOUT_VALUE timeout - Sets low resolution Watchdog Timeout.
  /BYPASS_RESTORE	- Restores port pairs to known preconfigured
			  default state.
  /BYPASS_CLEARLOG	- Clear event log content on the bypass NIC.

    forceMode	- one of: {AUTO, NORMAL, BYPASS, ISOLATE}
    mode	- one of: {KEEP, NORMAL, BYPASS, ISOLATE}
    timeout	- one of: {1, 1.5, 2, 3, 4, 8, 16, 32}

Other:
  /? or /HELP	- Brings up command line help.
  /AUTONEGSPEED X
		- Select the speed and duplex where X is one of:
		  10H, 10F, 100H, 100F, 1000, 10G (depending on the NIC
		  capabilities).
		  Note: 1000h violates 1GbE protocol.
		  Different link speeds can be set by both forcing and
		  autonegotiating to test at various speeds and settings.
  /DEBUGLOG	- Logs debug messages into the debugfile.
  /DEVICES	- Displays the device list and quits.
  /EEPROMVER	- Displays the version of the EERPOM image on screen.
  /ERRORLOG[=<[path\]filename>]
		- Output is only logged if an error or test failure occurs.
		  If no filename is specified output is directed to ERROR.LOG.
  /FORCEDSPEED X
		- Select the speed and duplex where X is one of:
		  10h, 10f, 100h, 100f. Note: 10GbE cannot be forced and 1000h
		  violates 1GbE protocol. Note that not all speeds can be forced
		  and that forcing speed only on one end can cause a speed-duplex
		  mismatch in which case the link results can be
		  unpredictable.
  /INVMISLOCKED	- Checks if autoload configuration stored in OTP memory
		  is protected against write attempts.
  /INVMTEST=XXX	- Checks if a continuous region of XXX or more empty bytes
		  in the OTP memory is available for any update.
  /INVMVERIFY /FILE=<config_file>
		- Compares autoload configuration stored in OTP memory
		  with the configuration defined in configuration
		  <config_file> file.
  /INVMVERSION	- Displays the INVM version information. A value
		  of "00.0-0" indicates an empty or invalid version. "Unsupported"
		  indicates the device does not support INVM.
  /LOGFILE=(<[path\]filename> | OFF)
		- By default output is logged to CELO.LOG. LOGFILE is used
		  to specify an alternate path and filename or to turn
		  logging off.
  /LOOP		- Causes CELO to loop until <ESC> key is hit.
  /LOOP n	- Causes CELO to loop n times, where n is the number of loops
		  designated by the user.
  /NVMSECURITY	- Checks if appropriate NVM image has been loaded
		  during manufacturing and NVM security is enabled.
  /RESPONDER	- Puts the adapter into responder mode for   /nwtest.
  /SHOWLINKINFO	- Runs applicable Non-Network diagnostics as well as
		  displaying the adapter's link status on screen. May take up to
		  10 seconds for link auto-negotiation.
  /SILENT	- Causes CELO to suppress output to the screen.
  /STOPFAIL	- CELO will stop testing and exit, if a test fails
		  (by default, CELO does not exit upon failure).
  /VERSION	- Displays CELO version information and the diagnostic
		  library version information.


INVM FILE FORMAT
----------------
The <config_file> is a text file that stores sets of configuration entries
and their values. These pairs are used to program the INVM with options such
as MAC address, LEDs configuration, device ID and WoL behaviour. Values can be
changed only if the INVM has enough free locations available and write
protection has not been applied.

File syntax:
  Single record entry:
    <Record type> <Address> = <Data> <Reset type> <Comment>

Ordered section:
  Ordered_Section_Start
    <Single record entry #1>
	.
	.
    <Single record entry #N>
  Ordered_Section_End

where:
  <Record type> - record type:
    WALD - autoload word record
    CSRALD - CSR autoload record
    PHYALD - PHY autoload record
  <Address> - address in the range of:
    0x0000 - 0x07FF in WALD records definition
    0x00000 - 0x1FFFF in CSRALD records definition
    0x00000 - 0x1F in PHYALD records definition
  <Data> - Data to set:
    0x0000 - 0xFFFF in WALD and PHYALD records definition
    0x00000000 - 0xFFFFFFFF in CSRALD records definition
  <Reset type> - Describes the set of reset events for which the setting
                 is applied:
    LPG_RST - LanPower Good Reset only
    PCIE_RST - PCIe asserted reset and all above
    SW_RST - Host software asserted device reset and all above (must be set
             for PHYALD)
  <Comment> - Alphanumeric comment (including space and tab) starting with ';'


EXAMPLES
--------

Example 1:
To run the EEPROM, FIFOS, Link and Network test, call CELO.EXE like this:
  CELO /EEPROM /FIFOS /LINK /NWTEST

Example 2:
To run Diagnostic (EEPROM, FIFOS, IRQ, and REGS) and Network Tests (LINK,
and NWTEST), call CELO.EXE like this:
  CELO /DIAGS /NETWORK

Here are three sample batch files that call CELO with different parameters:

SAMPLE1.BAT is a batch file that does a fast CELO test with few parameters.
  REM *************************************************************************
  REM ** FileName: SAMPLE1.BAT **
  REM ** Description: Sample of CELO command line parameters. **
  REM *************************************************************************
  celo /eeprom /fifos /irq /regs

SAMPLE2.BAT is a batch file that does a more thorough test than SAMPLE.BAT,
but it requires more time to execute.
  REM *************************************************************************
  REM ** FileName: SAMPLE2.BAT **
  REM ** Description: Sample of CELO command line parameters. **
  REM *************************************************************************
  celo /eeprom /fifos /irq /regs /lb

SAMPLE3.BAT is a batch file that does an even more thorough test than
SAMPLE2.BAT, but takes more time to complete.
  REM *************************************************************************
  REM ** FileName: SAMPLE3.BAT **
  REM ** Description: Sample of CELO command line parameters. **
  REM *************************************************************************
  celo /eeprom /fifos /irq /regs /lb /extlb

Notes:
 - If you call CELO without any command line options, CELO will run all of the
   Non-Network diagnostics: Device Registers, EEPROM, Interrupt, and FIFO tests.
 - CELO will test all supported Intel adapters that it finds, unless you specify
   which adapter to test, via the "/CARD=" option.
 - Pressing the <ESC> key while CELO is running will cause CELO to abort all
   tests. Pressing the <ESC> key will invalidate all tests in progress.
INVALID TEST SCENARIOS
----------------------
On operating systems such as Windows or Linux where it is possible to run more
than one instance of CELO in two different command windows, there is a 
restriction on the type of testing that may be done in this scenario. On 
multi-port adapters the EEPROM is shared between each of the ports. If two or
more instances of CELO are testing the ports shared by a single adapter, it is
an invalid test design for the multiple instances of CELO to each be testing
the EEPROM. If the test setup attempts to do this then spurious EEPROM test
failures will result because the multiple instances of CELO are trying to
access the EEPROM at the same time.
Running some diagnostics with manageability components (such as BMCs)
enabled may cause errors. Any diagnostics that send packets and verify data
assume full control of the network adapter. The tests build a specific packet,
send it, receive, then byte compare the sent and received packet. If some
manageability component decides to send a packet in the middle of this test
then the test will fail because the received packet will not match the
transmitted packet. This will trigger a data corruption failure. Examples of
tests that can be impacted by this include loopback, external loopback, peer
sender responder (sendresp), and all network tests.


ERROR CODES
-----------

CELO will return error codes to the DOS command line, upon success or failure
of a diagnostic test.

NOTE: You MUST be using CELO with the /STOPFAIL option set, otherwise these
codes will not be of any use, as CELO will get through all of the diagnostics,
and then return an improper value. These values must be checked, using the
'errorlevel' environment variable from an MS-DOS batch-file or the
'lasterror' special variable from an EFI shell batch script (.nsh extension).

CODE NAME:		    DOS VALUE:	EFI32 VALUE:	EFI64 VALUE:
----------		    ----------	------------	---------------------
TEST SUCCESSFUL			0	0x0		0x0
OPERATOR TERMINATION		1	0x4000 0001	0x4000 0000 0000 0001
INVALID ADAPTER			2	0x4000 0002	0x4000 0000 0000 0002
REGISTER TEST FAILURE		3	0x4000 0003	0x4000 0000 0000 0003
FIFO TEST FAILURE		4	0x4000 0004	0x4000 0000 0000 0004
EEPROM TEST FAILURE		5	0x4000 0005	0x4000 0000 0000 0005
IRQ TEST FAILURE		6	0x4000 0006	0x4000 0000 0000 0006
MAC LOOPBACK FAILURE		7	0x4000 0007	0x4000 0000 0000 0007
PHY LOOPBACK FAILURE		8	0x4000 0008	0x4000 0000 0000 0008
LINK TEST FAILURE		9	0x4000 0009	0x4000 0000 0000 0009
NETWORK TEST FAILURE		10	0x4000 000A	0x4000 0000 0000 000A
EXT LOOPBACK FAILURE		11	0x4000 000B	0x4000 0000 0000 000B
TDR TEST FAILURE		12	0x4000 000C	0x4000 0000 0000 000C
MAC ADDRESS TEST FAILURE	16	0x4000 0010	0x4000 0000 0000 0010
PEER SENDER RESPONDER FAILURE	17	0x4000 0011	0x4000 0000 0000 0011
INVALID COMMAND LINE		18	0x4000 0012	0x4000 0000 0000 0012
INTERNAL LOOPBACK FAILURE	19	0x4000 0013	0x4000 0000 0000 0013
CONFLICT COMMAND LINE		21	0X4000 0015	0X4000 0000 0000 0015
TTL TEST FAILURE		22	0X4000 0016	0X4000 0000 0000 0016
FLASH TEST FAILURE		24	0X4000 0018	0X4000 0000 0000 0018
CIRCUIT BREAKER TEST FAILURE	26	0X4000 001A	0X4000 0000 0000 001A
CIRBRKR TEST UNIMPLEMENTED	27	0X4000 001B	0X4000 0000 0000 001B
CIRBRKR TEST UNSUPPORTED	28	0X4000 001C	0X4000 0000 0000 001C
FAN TEST FAILURE		29	0X4000 001D	0X4000 0000 0000 001D
OTP FUNCTION FAILURE		31	0X4000 001F	0X4000 0000 0000 001F
OTP FUNCTION PARSING ERROR	33	0X4000 0021	0X4000 0000 0000 0021
OTP FUNCTION CANT BE MARGED	34	0X4000 0022	0X4000 0000 0000 0022
NVM SECURITY CHECK FAILED	35	0X4000 0023	0X4000 0000 0000 0023
BYPASS FUNCTION FAILURE		36	0X4000 0024	0X4000 0000 0000 0024
ADAPTER INITIALIZATION FAILED	37	0X4000 0025	0X4000 0000 0000 0025

EXAMPLE USE OF ERROR CODE IN DOS
--------------------------------
REM *** Begin test.bat ***
call celo.exe /card=1 /stopfail /link
if errorlevel 9 goto LinkError
goto end
:LinkError
echo Link Detection failed!!!
goto end
:end
echo Testing DONE.
REM *** End test.bat ***

EXAMPLE USE OF ERROR CODE IN EFI32
----------------------------------
celo32 /card=1 /stopfail /link
if %lasterror% == 4000000A then
echo Network test failed!!!
goto end
endif
:end
echo Testing DONE.


Installation
=============


INSTALLING THE TOOLS ON MICROSOFT* WINDOWS*
===========================================

The tools' driver can be installed on all versions of Microsoft* Windows* since
Windows 7. To install the tools' drivers on Windows, run install.bat from the
appropriate directory on the CD.

Although the tools are not installed with install.bat, the driver that the tools
require is copied into the local machine Windows driver directory. To run the
tools, launch a Command Prompt window from the Windows Start Menu. Go to the
media and directory where the tools are located and run the tools. The readme
files for each tool are found in the same directory as the tools. These tools
can be manually installed on the local hard drive in any directory.

The tool uses its own driver file (not the same as the system network driver).
If the driver sys file already exists in the drivers directory, install.bat may
fail to copy. Using the /y switch with install.bat will override and copy the
driver file regardless. However, this can be dangerous if an older version of
the driver is being used by another application such as Intel(R) PROSet for
Windows Device Manager. If a driver is already present in the drivers directory,
try running the tool from the command prompt. If it runs, then the driver is
fine. The tool will not run if the driver version present does not match the
driver version expected.

Note that you must have access to the %systemroot%\system32\drivers
directory. Only the administrator account has these privileges. You must be
logged in as administrator or the tools must be run as administrator.

Note that on Windows, any device that is disabled in device manager will not be
accessible by tools due to no memory resources. You would get an error code
0xC86A800E. To solve this problem, you can do one of the following:
1) Re-enable the device in device manager. Never disable this device when
   using tools.
2) Install an NDIS device driver for the device and make sure that it does
   not have a yellow or red bang by it in device manager.
3) Delete the device from device manager and restart the system. The install
   new hardware wizard should appear on next reboot. Do not cancel this. Just
   move the window aside and run the tool(s). Generally, you can click "cancel"
   on the wizard but there are some cases where Windows will disable the memory
   resources causing you to get back into the same state.


INSTALLING THE TOOLS ON MICROSOFT* WINDOWS SERVER* NANO SERVER
==============================================================

To install the tools on systems running Nano Server, you must use Microsoft*
Windows PowerShell* to copy the tools and their driver files from a host system
running a version of Windows other than Nano Server to the target system
running Nano Server. The tools and their driver files are available from the
installation media in the \TOOLS\Nanox64\SVTools folder.

This is the installation procedure:
  1. On the host system, open the installation media and copy the folder
     \TOOLS\Nanox64\SVTools to the target system running Nano Server.
  2. Open a Windows PowerShell session to the target system.
  3. Navigate to the location of the files you copied in Step 1 above.
  4. Run install.bat.


INSTALLING THE TOOLS ON EFI
===========================

There is no installation required for EFI tools. The tools can simply be copied
from the appropriate directory to the drive that they will run from. The EFI2
binaries are for use with the UEFI Shell 2.X with the UEFI 2.3 HII protocol.
EFI2 tools will not run on the EFI Shell 1.X or if the UEFI 2.3 HII protocol is
not present.

Note that while EFI supports USB drives, there may be issues running tools
from the USB drive. Whether or not there are issues are BIOS specific. If you
experience issues, run the tool from hard disk instead.


INSTALLING THE TOOLS ON DOS
===========================

The tools support various DOS versions. There is no installation required for
DOS tools. The tools can simply be copied from the DOS directory on the CD to
the drive that they will run from. It is expected that the tools have a clean
boot environment. The tools will not run with memory managers and/or DOS
networking drivers loaded. The tools expect that they have full, unlimited
control of the hardware. The tools *WILL NOT* run properly if EMM386 is present. 
The tools run in protected mode, 32-bit DOS. Therefore, they will not be
compatible with any TSR programs.


INSTALLING THE TOOLS ON LINUX*
==============================

In order to run tools on Linux*, a driver stub must be built and installed on
the system. This driver is not related to the network device driver that is
used to run the network during live traffic. It is a separate driver used
explicitly for tools. Due to the nature of Linux with the number of kernels
that can exist, we provide source for the driver module and an install script
to build/install it.

The tools support Linux distributions based on kernels 2.6.x. Validation is done
randomly on popular distributions such as Red Hat* or Suse*. Configured
kernel source that matches the currently installed kernel is required. A working
GCC is also required. There are some versions of GCC that had a bug which did not
support unnamed structures. These versions of GCC are not supported. If you have
compilation errors, try updating your version of GCC. If you have linker errors
when installing the driver, you should update your kernel - download the latest
stable off www.kernel.org and build/install it.

Note that some distributions such as recent Fedora core versions do not ship
with Kernel source. You must download, install, and configure the source in
order to get the tools' driver built on this OS. Installing the kernel source
RPM does not solve the problem.

This is the installation procedure:
  1. Log in as root and create a temporary directory to build the Intel(R)
     Network Connection Tools driver.
  2. Copy 'install' and 'iqvlinux.tar.gz' to the temporary directory.
     There are 3 versions of Linux supported: Linux32 (x86), Linux_x64 (x64),
     and Linux64 (Itanium). Copies of the above files exist in the appropriate
     directory for your platform.
  3. CD to the temporary directory and run './install.' The driver has been
     installed now, so the files in the temporary directory can be removed.
  4. Copy the tools that you want to use from the appropriate directory of
     the CD.


INSTALLING THE TOOLS ON FreeBSD*
================================

In order to run tools on FreeBSD*, a driver stub must be built and installed on
the system. This driver is not related to the network device driver that is
used to run the network during live traffic. It is a separate driver used
explicitly for tools. Due to the nature of FreeBSD with the number of kernels
that can exist, we provide source for the driver module and an install script
to build/install it.

The tools support FreeBSD distributions version 10.1 and later.

This is the installation procedure:
  1. Log in as root and create a temporary directory to build the Intel(R)
     Network Connection Tools driver.
  2. Copy 'install' and 'iqvfreebsd.tar' to the temporary directory.
     There are 2 versions of FreeBSD supported: FreeBSD32 (x86) and
     FreeBSD64e (x64). Copies of the above files exist in the appropriate
     directory for your platform.
  3. CD to the temporary directory and run './install' The driver has
     been installed now, so the files in the temporary directory can be
     removed.
  4. Copy the tools that you want to use from the appropriate directory of
     the CD.


CUSTOMER SUPPORT
================
- Main Intel web support site: http://support.intel.com

- Network products information: http://www.intel.com/network


Legal / Disclaimers
===================
Copyright (C) 2002-2016, Intel Corporation. All rights reserved.

Intel Corporation assumes no responsibility for errors or omissions in this
document. Nor does Intel make any commitment to update the information
contained herein.

Intel is a trademark of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

This software is furnished under license and may only be used or copied
in accordance with the terms of the license. The information in this
manual is furnished for informational use only, is subject to change
without notice, and should not be construed as a commitment by Intel
Corporation. Intel Corporation assumes no responsibility or liability
for any errors or inaccuracies that may appear in this document or any
software that may be provided in association with this document. Except
as permitted by such license, no part of this document may be reproduced,
stored in a retrieval system, or transmitted in any form or by any means
without the express written consent of Intel Corporation.
