USB4 Command Verifier
===================

This document defines how to set up and run USB4CV.
USB4CV 1.5.0.0 currently requires Ubuntu 24.04 or later. 
CV is otherwise untested on other distributions. 

This download includes the directory for which USB4CV can be run in.
It can be located anywhere on the machine running CV. By default, the
top level directory of the USB4CV installation is named 'usb4cv-<version>'
where <version> is the four digit USB4CV version number.  In this document,
we will refer it as 'usb4cv'.


USB4CV incorporates a number of third party Open Source licensed software
components. See NOTICES.txt for more information.

Please see ReleaseNotes_USB4CV.txt for details of changes in this Release.

The USB4CV Linux Quick Guide can also be helpful and includes screenshots
regarding how to set up USB4CV. It can be downloaded here:
https://www.usb.org/document-library/usb4cv-linux-quick-guide

Setting Up CV
=========================

To set up USB4CV, run "./setup_usb4cv.sh" while in the usb4cv directory. 

This will copy the required .conf files to the home directory, as well as 
compile and install the driver. 

For more information on the settings configured by the .conf files, please 
read Linux_ConfigurationSettings_USB4CV.txt
You can also modify the .conf files in the usb4cv/config directory, 
and then run "./setup_config.sh" in order to copy them to the 
home directory again. 

For more information on driver installation, please read 
usb4cv/drivers/README.txt

Do the following after installing USB4CV

1) USB4CV requires the use of a USB4 Analyzer, connected through a remote
machine running Windows. Install Teledyne LeCroy USB Protocol Suite on 
the remote machine, and connect it to this machine through an Ethernet or 
WiFi connection. See "ReleaseNotes_USB4CV.txt" for required version number.
The USB4CV Linux Quick Guide includes more information on how to set up the
Remote LeCroy server. 

2) Download the company list file (usbif.json). Go to 
https://cms.usb.org/usb/api/usbif.json. Note that this page may take a 
very long time to download (up to several minutes). When it is fully 
loaded, copy the entire contents of the page into a text file named 
usbif.json. Put the file in the /bin directory containing this application.

3) Certain test suites may require a Vendor Info File (VIF) in order to run 
correctly. The official USB-IF VIF Generator and the current VIF 
Specification may be downloaded from 
http://www.usb.org/developers/tools/#VendorFile.
A Windows machine is required to run the USB-IF VIF Generator.

Running CV
=========================

WARNING
Running USB4CV can make your computer permanently unusable!
This application will take over operation of a selected USB4 Host Interface, 
which renders any devices attached to this inoperable. This will make your 
computer inoperable if your input devices (i.e. mouse and keyboard) 
are attached to it.

Do not run this application unless you can operate this computer without
the selected Host Controller. Possible ways to do this are:
-- Make sure your mouse/keyboard are attached through a second USB host
controller or alternate method. This can be accomplished by installing
and using a second USB Host Controller on this computer. 
-- Run this application through a remote session (Remote Login). 

Before launching USB4CV, the usb4_hi driver would have to be switched in. 
This is done by running "sudo ./drivers/switchUSB4HIDriver.sh usb4_hi"
while in the usb4cv directory. 

When exiting CV, the user will have to switch back in the default OS
thunderbolt driver, which can be done by running 
"sudo ./drivers/switchUSB4HIDriver.sh thunderbolt" in the usb4cv directory. 

In order to run CV, the user needs to be in the usb4cv/bin directory. 
Then the user launches the cv-gui or cv-cli binary.

Arguments:
-app (Required)
Details what application for the user to run. 
For USB4CV, the app must be "USB4CV"

-title (GUI only, Optional)
Gives a title to this instance of USB4CV

-testsuite (CmdLine Only, Required)
Specifies the test suite to run. This must be one of the cvtest files 
in the bin directory. 

-vif (CmdLine Only, Optional)
Specifies the Vendor Info File (VIF) of the Device Under Test. 

-ip (CmdLine Only, Optional)
Specifies the IP of the Remote LeCroy Machine if running an analyzer or 
exerciser test. Defaults to 127.0.0.1

In GuiCV, this must be defined in the USB4CV.conf file. 
See Linux_ConfigurationSettings_USB4CV.txt

-port (CmdLine Only, Optional)
Specifies the Port of the Remote LeCroy Machine if running an analyzer or 
exerciser test. Defaults to 5515
In GuiCV, this must be defined in the USB4CV.conf file. 
See Linux_ConfigurationSettings_USB4CV.txt

Examples:
./cv-gui -app USB4CV -title "USB4 Command Verifier"
./cv-cli -app USB4CV \
    -testsuite "USB4 Summary - All Routers - No Trace.cvtests"
./cv-cli -app USB4CV \
    -testsuite "USB4 Device (AN_DEV_UFP1) [Chapter 4 - Logical] Tests.cvtests" \
    -vif location/to/UUT_VIF.xml -ip 192.168.1.2 -port 5515
./cv-cli -app USB4CV \
    -testsuite "USB4 Device (AN_DEV_UFP1) [Chapter 4 - Logical] Tests.cvtests" \
    -vif location/to/UUT_VIF.xml

PCIe Tunneling Tests
=========================
When running tests that set up PCIe Tunneling, the user must run CV as 
"sudo -E".  All Chapter 11 tests and TD 8.015 use PCIe Tunneling.

Examples:
sudo -E ./cv-gui -app USB4CV -title "USB4 Command Verifier"
sudo -E ./cv-cli -app USB4CV \
    -testsuite "USB4 Device (DC_DEV_UFP1-PCIE_01) [Chapter 11 - PCIe Tunneling] Tests.cvtests" \
    -vif location/to/UUT_VIF.xml
