﻿===========================================================================================
Aquantia Diag Tool Software                                                               =
---------------------------                                                               =
Version: 2.10                                                                              =
===========================================================================================

Purpose: This Diag software enables users to test and configure Aquantia's network interface
         card by running tests that replicate the transmission of packets and read hardware
         memory. Users can also flash the hardware's firmware using the Flash option.

         Tests available include:
	     - Datapath test
             - Read/Update Flash
             - Write/Verify Portion of Flash
             - Read VPD Data
             - IRAM, DRAM, TPB/RPB
             - LSO Test
             - LED Test
	     - MAC Register test
             - IEEE Test

--------------------------------------------------------------------------------------------
Usage and Command Line Options
--------------------------------------------------------------------------------------------
 * Installation: Run install.cmd in Diag64 or Diag32, a Diag folder will be created with a dist 
                 folder inside. Inside the dist folder contains DIAG.exe. Open command prompt as 
                 Administrator and change the current working directory into the dist folder.
 run with the following command:
     DIAG.exe (runs in interactive mode by default)

 ***WINDOWS 10 USERS: Left clicking the command line while tests are running will cause command line
                      to enter mark mode. Program is halted while in mark mode, so users must right
                      click to resume program.
					  
 ***WINDOWS 7 USERS: Visual C++ 2015 redistributable will need to be installed before running.
                     You may encounter error: "DLL load failed: Invalid Access to Memory"  
 
 * Logging is enabled by default in both modes. Users can disable logging in interactive mode. After
   each test run, DiagLog.log is created and contains all output from test runs.

 Optional Arguments:
     -h, --help ............ show this help message and exit
     -? .................... show this help message and exit 
     -i .................... Run diagnostic software in interactive mode. (Can't be
                             combined with -a)                             

     -a testfile [iter]..... Run tests automatically with configuration file (Can't
                             be combined with -i). Iterates specified number of times
                             if option provided, otherwise runs once. 
     
     -f firmwareFile ....... Program flash with specified file and then exit. (Can't be
                             combined with -a, -i, -p)
    
     -p .................... Print device and program information, then exit.
     -c .................... Continue running tests when failure occurs during -a
                             mode. Default behavior exits on first failure. This
                             option is ignored during -i mode. Failure cycles back
                             to menu.
     
     -r .................... Print results at the end of diag program.
     -k .................... Installs diagnostic driver on all Aquantia devices before
                             launching diagnostic menu.(location automatically detected)
                             diagnostic driver remains installed after program exits.
     -s .................... Installs diagnostic driver on all Aquantia devices before
                             launching diagnostic menu.(location automatically detected)
			     diagnostic driver is deleted after program exits unless flash
			     is erased or invalid.
     
     -v <0,1,2> ............ Set verbosity level of standard output
                                 0 = Print nothing
                                 1 = Print test name + status (default)
                                 2 = Print detailed info 

     -d DVC_NUM ............ The device number (an integer index, or X.Y.Z notation) to run 
			     tests on. For N Aquantia devices, starts from index 0 and goes 
			     up to N-1. This software detects devices using pciX.Y.Z notation
                             (where X = bus, Y = device, Z = function) and sorts the list
                             using this notation. Users can also use X.Y.Z format to select
                             pci device.

     -t TestType:Testname[,Testname][ TestType:Testname] ...........Run specified tests by supplying the test type
                             					    and test names following the -t option. (Multiple 
								    tests can be applied)

*Note: All output examples are for verbosity set to 2
--------------------------------------------------------------------------------------------
Datapath Tests
--------------------------------------------------------------------------------------------
 
 In Interactive Mode
 -------------------
 eg: diag.exe [-i]

 output:
  Diag Options
  =======================
  
  1) Select device
  2) Datapath Tests
  3) Flash
  4) Memory
  5) Offloads
  6) Fast Datapath Tests
  7) Misc Tests
  8) Device Info
  9) Enable/Disable Logging
  
  0) Exit
  h) Help


Diag:
--------------------------
 User will input a number, and press enter to make a selection.


 In Automated Mode
 -----------------
usage : diag.exe -a path2autofile [-iter]
eg:     diag.exe -a config/auto.cfg

 When running in automated mode, user must specify relative path to automation file containing
 tests to run. The user may also supply an optional argument, which indicates the number of
 iterations to run tests included in automation file.The automation file specifies which tests 
 the user wants to run in sequence. The automation file contains the lines:
    tests:
	datapath_tests: ["Mac", "Phy", "External Loopback"]
	memory_tests: ["IRAM Memory", "DRAM Memory", "TPB/RPB Memory"]
	offload_tests: ["LSO"]
	flash_tests: ["Flash Write Read"]
	misc_tests: ["VPD Read", "MAC Registers", "LED Test"]

 to indicate no datapath tests to be run, use the following:
	datapath_tests: []
        memory_tests: ["IRAM Memory", "DRAM Memory", "TPB/RPB Memory"]
        offload_tests: [] 
	flash_tests: ["Flash Write Read"]
	misc_tests: ["VPD Read", "MAC Registers", "LED Test"]

 three memory tests, one flash test, and 2 miscellaneous tests. If users provide a number option, 
 ie: 'diag.exe -a config/auto.cfg 5', the tests specified in auto.cfg will run 5 times.

	Speed List In auto.cfg
	----------------------
	There are two variables in auto.cfg:
	Phy_Speed: ['10G', '5G', '2.5G', '1G', '100M']
	Ethernet_Speed: ['10G', '5G', '2.5G', '100M']

	If fast_datapath_tests list contains 'Phy Loopback' or 'External Loopback', then these tests
        will run at the speeds specified in the speed list.

--------------------------------------------------------------------------------------------
Flash Options
--------------------------------------------------------------------------------------------
 In Interactive Mode
 -------------------

output:

  Flash Options
 =======================

 1) Read Flash NCB Block
 2) Update Flash Image
 3) Save Flash contents to file
 
 5) Go back to main menu
--------------------------------------
 Description:
 
 1) User can read contents of NCB Block
 2) Program specified file to firmware. Must provide path to clx file
 3) Save contents to a .clx file. *Note: Each flash structure is unique, so using
                                         this .clx file to program another card will
                                         not produce the intended results.
 
 
*Details on write/verify test: The diag tool writes a predetermined pattern/formula of dwords
                               to a small portion of flash memory. Before the test is run, that
			       small portion is filled with all 1's. Then that portion is written
			       with the pattern, and then the flash memory address is read back to
			       verify the write occurred.
 
 In Automated Mode
 -----------------
usage: diag.exe -f pathToFile.clx
 
 Users can flash the firmware on the network interface card from the diagnostic tool. The
 -f option requires an additional parameter, which is the relative path to the firmware
 file. The firmware file is a clx file. Flashing the firmware will erase the previous version
 installed. The specified firmware will then be installed and verified. User must restart
 for hardware to recognize changes.

--------------------------------------------------------------------------------------------
Memory Options
--------------------------------------------------------------------------------------------

 Running memory tests is similar to running datapath tests. Users can specify which memory
 tests will run. There are three available memory test options: IRAM, DRAM, and TBP/RPB.

 In Interactive Mode
 -------------------

output:

 Memory Options
 =======================

 1) Change Memory Tests
 2) Run Memory Tests
 3) Go back to main menu

Memory:
----------------------------
 Users can input 2(Run Memory Tests) and press enter to run the default memory tests, which 
 include all 4 tests. Another option is to select specific memory tests to be run by inputting 
 1(Change Memory Tests) and pressing enter. Input the number corresponding to the selected test, 
 separated by a space. To run IRAM and TPB/RPB tests, users should input "1 3" (omitting quotations) 
 and pressing enter. To finally run test, users can input 2(Run Memory Tests) and press enter.

 In Automated Mode
 -----------------
 Running in automated mode is identical to datapath test automated mode. User must specify in the
 auto.cfg which memory tests to run, then run diag tool from cmd with the following command:
 diag.exe -a pathToAutoFile [iter]

--------------------------------------------------------------------------------------------
Offload tests
--------------------------------------------------------------------------------------------

 There is currently one offload test available for the user to run. The large segment offload
 test sends large packets in 10 iterations(20 for B0). To run this test:

 In Interactive Mode
 -------------------

 output:
 
 Offload Options
 =======================

 1) Run Large Segment Offload Test
 2) Go back to main menu

 Offload:
-----------------------------------
 Since there is only one available test to run, users do not have an option to change tests in
 LSO menu. The output of the test should be the Iteration count, Status, Rx expected head value,
 Rx actual head value, Result, pass count, and fail count.

 In Automated Mode
 -----------------

 Similar to the datapath and memory tests. Users can specify if LSO tests should be run in the
 auto.cfg file. offload_test: ["LSO"] indicates that LSO test will be included in auto run,
 while offload_test: [] does not include large segement offset test to be ran.

--------------------------------------------------------------------------------------------
Device Information
--------------------------------------------------------------------------------------------

 Device information can be obtained in two ways with the diagnostic tool

 In Interactive Mode
 -------------------
 
 Diag Options
 =======================

  1) Select device
  2) Datapath Tests
  3) Flash
  4) Memory
  5) Offloads
  6) Fast Datapath Tests
  7) Misc Tests
  8) Device Info
  9) Enable/Disable Logging
  
  0) Exit
  h) Help
 
 Selecting option 8 will print the device info and return to the main menu of the diagnostic tool

 In Automated Mode
 -----------------
 
 usage: diag.exe -p

The device information will output the following:
====================================================  /// 
Aquantia Diagnostics Version = versionNo (Date)       /// In Automated Mode
====================================================  ///
    - MAC Aaddress
    - Firmware Version
    - Chip ID
    - Chip Rev
    - Vendor ID
    - Device ID
    - Subsystem Vendor ID
    - Subsystem Device ID
    - Max Payload Supported
    - PCIe Link Speed
    - PCIe Link Width
    - MAC Temperature in Celsius
    - Ethernet Link Status: 
    - System TX: | System RX:

--------------------------------------------------------------------------------------------
Miscellaneous Tests
--------------------------------------------------------------------------------------------

 Miscellaneous Options
 =======================

 1) Read VPD
 2) LED Tests
 3) MAC Register Test
 4) IEEE Test

	--------------------------------------------------------------------------------------------
	VPD (Vital Product Data) Options
	--------------------------------------------------------------------------------------------
 
 	Reading VPD data is available with two options. Users can enter option "7)
 	Reading the VPD data will output the
 	following information:
     
     	-Product Name
     	-PN = Part Number
     	-EC = Engineering Change
     	-FG = Fabric Geography
     	-LC = Location
     	-MN = Manufacture ID
     	-PG = PCI Geography
     	-SN = Serial Number
     	-Vx = Vendor Specific
     	-RV = Checksum and Reserved
     	-YA = Asset Tag Identifier
     	-Yx = System Specific
     	-RW = Remaining Read/Write Area

	--------------------------------------------------------------------------------------------
	LED Test
	--------------------------------------------------------------------------------------------
 	*NOTE: Make sure nothing is plugged into the ethernet port, as traffic activity will override
               tests led activation. Leds may blink due to activity, and disrupt LED visual test.

	LED Options
	=======================

	1) Toggle Bottom Green LED
	2) Toggle Top Yellow LED
	3) Toggle Top Green LED
	4) Go back to main menu

	LED: 1

	LED is toggled on.
	Press Enter key to toggle off: 

 	With the LED test, users can visually test if LEDs are functioning correctly. Users can
 	select which LED to toggle on, and the LED remains lit until the user presses Enter key.
 	User is then in LED Options menu where they are able to toggle another LED or return to
 	the main menu.

	--------------------------------------------------------------------------------------------
	MAC Register Test
	--------------------------------------------------------------------------------------------

	Writes patterns to mac registers to test if register modifications conform to read/write
        restrictions. Bits with read only status should not be able to be modified by manual
        register write commands, so an error indicates that a read only bit is being set.

	======================================================================
	Starting MAC Registers...
	======================================================================

	0 Errors in A Pattern
	0 Errors in F Pattern
	0 Errors in 987 Pattern
	0 Errors in 0 Pattern
	0 Errors in 123 Pattern
	0 Errors in 5 Pattern

	======================================================================
	Ending MAC Registers... RESULT = PASS
 	(TIME = 3.721000 sec)
	======================================================================

	--------------------------------------------------------------------------------------------
	IEEE Tests
	--------------------------------------------------------------------------------------------

	Sets PHY Register values for IEEE Tests. Users can select the speed, then select the test in which
        they would like to run. After selection is made, the register is set until the user presses enter.
        Measurements are taken, and then the user presses enter to revert back to the original state.
 
        1) 10G 
	2) 5G 
	3) 2.5G 
	4) 1G 
	5) 100M
        0) Exit
     
	10G-2.5G					1G				100M
        1) Test Mode 1				1) Test Mode 1			1) Test Mode 1
	2) Test Mode 2				2) Test Mode 2			2) Test Mode 2 (Jitter)
	3) Test Mode 3				3) Test Mode 3			3) Test Mode 3 (Droop)
	4) Test Mode 4 Linearity_tone1		4) Test Mode 4			0) Exit
	5) Test Mode 4 Linearity_tone2		0) Exit		
	6) Test Mode 4 Linearity_tone3
	7) Test Mode 4 Linearity_tone4
	8) Test Mode 4 Linearity_tone5
	9) Test Mode 5 (PSD)
	10) Test Mode 6 (Droop)
	11) Test Mode 7
        0) Exit
--------------------------
-c option
--------------------------

 The -c option is only used during automated mode. The default behavior of the diagnostic tool in
 automated mode exits on first failure encountered. With the -c option, the sequence continues
 after a test fails.
 
 ex: diag.exe -a config/auto.cfg -c
  current auto.cfg file: 
              tests:
                    datapath_tests: ["External Loopback"]
                    memory_tests: []
                    offload_tests: ["LSO"]

 Indicating that datapath tests for External Loopback will run, then LSO test. The ethernet cable was
 disconnected during this test, which resulted in the current output:

======================================================================
Starting External Loopback...
======================================================================


======================================================================
Ending External Loopback... RESULT = FAIL  (TIME = 7.111000 sec)
======================================================================


======================================================================
Starting LSO...
======================================================================
...

Indicating that the LSO test was started. During default execution, the diagnostic tool would exit
after the failed Ethernet test.

--------------------------
-r option
--------------------------
 The -r option outputs a summary at the end of the test run, showing the number of passes and fails
 
 In Interactive Mode
 -------------------
 
 If specifying -r and -i, the summary will be printed when the user exits the program. Multiple
 tests can be run and a list of the tests will be shown before returning to the command prompt

 In Automated Mode
 -----------------

 The summary will be output after the specified tests in auto.cfg is ran. Users will be presented
 with an output indicating the test that was ran, the number of times it passed out of the total
 number of runs, and the percentage of success.

 example output:
 **********************************************************************
 Test Results
 **********************************************************************

 System DMA                =  1 out of  1 passed (100.00%)
 System Packet             =  1 out of  1 passed (100.00%)
 External Loopback             =  0 out of  1 passed (0.00%)

--------------------------
-s option
--------------------------
 
 *NOTE: The driver will not be uninstalled if flash is currently erased! The following will
        output when -s is attempted during an empty flash:
	    'Flash is not present, or both ncbs are invalid! Preventing driver uninstall...'  

 This option installs the diagnostic driver before launching diagnostic menu. The diagnostic
 driver is required for the diagnostic to run. If another driver is installed prior to the
 diagnostic driver, the diagnostic driver will overwrite the previous driver. The diagnostic
 driver is uninstalled at the termination of the program. In Windows, the driver prior to the
 diagnostic driver is installed. Users should not expect extra output when using this option.
 If the flash is erased, or invalid, the diagnostic driver will remain installed to prevent
 any unpredictable behavior occuring from the production driver.

--------------------------
-k option
--------------------------
 Similar to the -s option, but the diagnostic driver remains on the system following the end
 of the diagnostic program.

--------------------------
-v <0|1|2> option
--------------------------
 This option specifies the verbosity of output. 
 - -v 0 indicates that no output will be printed when running tests
 - -v 1 indicates that a simple output will be printed when running tests
      example output:
         Running System DMA . . . . PASS
         Running System Packet . . . PASS
         Running LSO . . . PASS
 
 - -v 2 indicates that the output will print the most detail
      example output:
         ======================================================================
         Starting System DMA...
         ======================================================================

         Chorus Iteration 0 - packet matching result: True , pkts filled: 2890
         Chorus Iteration 1 - packet matching result: True , pkts filled: 2890
         Chorus Iteration 2 - packet matching result: True , pkts filled: 2890
         Chorus Iteration 3 - packet matching result: True , pkts filled: 2890
         Chorus Iteration 4 - packet matching result: True , pkts filled: 2890
         Total packets filled =  14450
         Stream compare result =  True
         TX/RX Head result =  True

         ======================================================================
         Ending System DMA... RESULT = PASS  (TIME = 16.470000 sec)
         ======================================================================

--------------------------
-d devNum option
--------------------------
 If users have multiple devices connected to the pci ports, users can select which device to run
 tests on. Indexing starts at index 0 and ends at N-1. Index 0 specifies the device with the
 lowest bus.device.function number. Each pci slot is assigned a 0.0.0 format, which is specified
 by the board manufacturers.
 
Example: if user has a device in pci slot 4.0.0 and 1.0.0, "diag.exe -d 0" will select the the device
         in slot 1.0.0.
	
	 If users know the X.Y.Z notation that corresponds to each slot, users can also select the
         device with the following command "diag.exe -d [pci]4.0.0" (Note that 'pci' is optional)

--------------------------
-t TestType:Testname[,Testname][ TestType:Testname]
--------------------------
Users have the option to specify tests to be run in the command line. Multiple tests can be run
by supplying the corresponding test type and test name. To run System DMA, System Packet IRAM 
memory and large segment offload tests, use the following:

ie: Diag.exe -t datapath:System_DMA,System_Packet mem:IRAM_Memory offload:LSO

Available Test Types and Test Names:
datapath:Mac,Phy,Ethernet_Plug
mem:IRAM_Memory,DRAM_Memory,TPB/RPB_Memory
offload:LSO
misc:VPD_Read,MAC_Registers,LED_Test

IMPORTANT: Enter commas between test names, spaces between test types and semicolon between test type and test list.

CLX2 Diag (2.x version) testplan
============================================
"Old image" with CLX 1.0 structure to use can be 1.5.58
CLX 2.0 image can be fw after 1.5.80

Images to use:

1)	Burn old image with this diagTool (with conversion to CLX 2.0), then perform Windows Upgrade – on normal and swapped Nikki (you may use Jasmine instead of swapped Nikki)
2)	Burn CLX 2.0 with this diagTool, then perform Windows Upgrade – on normal and swapped Nikki (you may use Jasmine instead of swapped Nikki)
3)	Burn old image with old diagTool, perform conversion from CLX1.0 to CLX2.0, then perform Windows Upgrade – on normal and swapped Nikki (you may use Jasmine instead of swapped Nikki)
4)	After Windows Upgrade, perform one more FW update with DiagTool – on normal and swapped Nikki (you may use Jasmine instead of swapped Nikki)

Conditions that should be preserved after updating flash:
	* Whatever overrides (PCIe, mac address, etc) were in flash should be preserved
	* FWs should stay the same
	* Assuming valid MAC and PHY FW were programmed, device should link up with production driver installed
	* Flash update process in production driver ("Windows Upgrade") should still work

Tests to perform:

1) Prompt to upgrade appears when working with FW CLX1.0
	- if FW has been burned with older diag (1.x version), this will appear when user uses interactive menu (-i)
	- user can answer either yes or no
		* if answer yes, update should complete in less than a minute and finish without issues
		* if answer no, menu should still open, but any flash commands should not work (should print warning mesg, but not exit)
			- user should still have the option to type "update_fw_struct" from the menu to initiate upgrade process

2) Warning appears when flash is still CLX 1.0 and user attempts flash commands (-f, --aqc, --flash_fields, --mac_addr_input)
	- if FW has been burned with older diag (1.x version), these commands won't work
	- should print warning mesg and exit with non-zero error code

3) Possibility to upgrade using CLI option (--update_fw_struct)
	- if FW has been burned with older diag (1.x version), this option can be used to automatically upgrade fw structure to clx 2.0
	- update should complete in less than a minute and finish without issues (zero exit code)

4) Updating flash afterwards
	- after initial upgrade to CLX2 has happened, every flash command should now work without complaints
	- if user updates using clx file, this is what should happen
		* BDP in flash AND clx file --> prompt user for decision
		* BDP NOT in flash, but in clx file --> write BDP from clx
		* BDP in flash, but NOT in clx --> leave BDP in flash alone
		* BDP NOT in flash, NOT in clx --> leave BDP alone (nothing there, so doesn't matter)
