Combined End of Line Tool for the Intel(R) Adapters
===================================================
February 03, 2015


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.

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

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:
   /EEPROM        - Test EEPROM Checksum.
   /FIFOS         - Test FIFOS on Network Adapter.
   /IRQ           - Test Network Adapter IRQ.
   /REGS          - Perform Read/Write tests on network adapter.
   /DIAGS         - Run Non-Network diagnostic tests: EEPROM, FIFOS, REGS
                    and internal loopback.
   /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.
   /FLASH 	      - Tests for a working flash.
   /AMT		      - Tests Intel(R) AMT functionality. The test will return:
		            Pass - AMT is configured and working correctly.
                    Fail - AMT is configured and enabled but not working.
                    Unsupported - AMT is not configured on this adapter or this adapter
                                  is incapable of running AMT.
   /IOAT          - Tests Intel(R) I/O Acceleration Technology. Tests will return:
                    Pass - I/O Acceleration Technology is working correctly.
                    Fail - I/O Acceleration Technology is not working.
                    Unsupported - Adapter does not support I/O Acceleration Technology.

   Network Diagnostics:
   /LINK          - Check for network Adapter Link.  Note:  This test is 
                    supported in auto-negotiation mode. The TTL test is recommended 
                    over the LINK test.
   /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.
   /LB            - Runs the Internal Loopback Test. It runs the best loopback test 
		    that the adapter supports.
   /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>
   /TIMEOUT [n]   - When used with the /EXTLB command, the /TIMEOUT option will 
                    cause the test to fail after the specified 'n' number of seconds.
   /TDR           - Run TDR Test.
   /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.
   /NETWORK       - Run Network specific diagnostic tests: LINK,NWTEST.
   /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.  
   /MAXSPEED      - Deprecated. Peer responder now fails if it cannot link at
                    the max common speed supported by *both* sender and
                    responder.
   /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).
   /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.
  
   Bypass configuration:
   /BYPASS_DEVICES                - Shows available adapters and bypass support.
   /BYPASS_FORCE=forceMode        - Force requested state on switching matrix.
   /BYPASS_STATUS                 - Display status of the relays.
   /BYPASS_AUX_ON=mode            - Determines what action the microcontroller
                                     should take on first power on when aux
                                     supply is applied.
   /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_AUX_OF=mode            - Determines what action the microcontroller
                                     should take if a power failure is detected.
   /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.                    
   /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.
   /STOPFAIL      - CELO will stop testing and exit, if a test fails 
                    (by default, CELO does not exit upon failure).
   /LOGFILE=(<[path\]filename> | OFF)
                  - By default output is logged to CELO.LOG.
                    LOGFILE is use to specify an alternate path and filename
                    or to turn logging off.
   /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.
   /SILENT        - Causes CELO to suppress output to the screen.
   /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.
   /EEPROMVER     - Displays the version of the EERPOM image on screen.
   /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.
   /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.
   /DEVICES       - Displays the device list and quits.
   /VERSION       - Displays CELO version information and the diagnostic
                    library version information.
   /RESPONDER	  - Puts the adapter into responder mode for /nwtest.
   /INVMVERIFY /FILE=<config_file>
                  -  Compares autoload configuration stored in OTP memory
                     with the configuration defined in configuration <config_file> file.
   /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.
   /NVMSECURITY   -  Checks if appropriate NVM image has been loaded
                     during manufacturing and NVM security is enabled.
   /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.


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

NOTE:
* 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

* 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.

* Hitting the <ESC> key while CELO is running will cause CELO to abort all tests.  
  Hitting 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 AMT, 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
AMT TEST FAILURE		20       0x4000 0014     0x4000 0000 0000 0014
CONFLICT COMMAND LINE		21       0X4000 0015     0X4000 0000 0000 0015
TTL TEST FAILURE		22       0X4000 0016     0X4000 0000 0000 0016
IOAT TEST FAILURE		23       0X4000 0017     0X4000 0000 0000 0017
FLASH TEST FAILURE		24       0X4000 0018     0X4000 0000 0000 0018
NO IOAT DEVICE FOUND		25       0X4000 0019     0X4000 0000 0000 0019
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 
appropriatedirectory 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 for Windows 7 (and later), the user must have access to the 
%systemroot%\system32\drivers directory. Only the administrator account has these
privileges. The user 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 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 issues are experienced,
the tool should be run 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), Linux64e (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.



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

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


Legal / Disclaimers
===================
Copyright (C) 2002-2015, 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.