Command line options¶

Definition¶

xbtest supports the following command line options described in next sections:

-v: Display version
-h: Display help
-d: Select card
-g: Display guide
-j: Select test JSON
-c: Select pre-canned test
-l: Select logging directory
-L: Disable logging directory
-m: Display message information
-F: Disable dynamic display
-f: Force an operation
-b: Select verbosity
-t: Select timestamp
-D: Select card configuration JSON (multi cards test)
-i & -e: Select PDI and card definition JSON

-v: Display version ¶

Display xbtest version 1.

$ xbtest -v

-h: Display help ¶

-h¶

Display help message and command line options available 1. There are two help levels:

Command line options and the list of all installed AVED deployment archives supported by xbtest with their respective pre-canned tests.
$ xbtest -h
Command line options for the selected card (-d).
$ xbtest -d <BDF> -h

-d: Select card ¶

-d <BDF>¶

Select the Alveo card identified by its <BDF>.

The command line:

Must start with an option -d. Other options following will be applied for the same group of cards.

Cannot finish with an option -d.

Maximum number of times option -d is present in command line is 100.

See Identifying AVED running on card to find the <BDF> of the card installed in your system.

$ xbtest -d <BDF> -j path/to/my_tests.json

-g: Display guide ¶

-g <test case/task>¶

Display a guide for the given <test case/task> 1.

This guide includes JSON members description, test sequence definition with examples and basic test JSON file examples.

To obtain the list of test cases available, use command line option -h.

Note

This option must be used with command line option -d.

$ xbtest -d <BDF> -g <test case/task>

-j: Select test JSON ¶

-j path/to/my_tests.json¶

Select test JSON file path/to/my_tests.json defining the test cases to run 2.

See Test JSON file structure for more information on the definition of the test JSON file content.

$ xbtest -d <BDF> -j path/to/my_tests.json

-c: Select pre-canned test ¶

-c <pre-canned test>¶

Select a pre-canned test <pre-canned test> to run 2.

To obtain the list of pre-canned tests available and their location in the installation directory use command line option -h.

See Pre-canned tests description for more information on the quantity and content of these card specific tests.

$ xbtest -d <BDF> -c <pre-canned test>

-l: Select logging directory ¶

-l path/to/log_dir¶

Define the name of a directory path/to/log_dir in which all log files will be stored, for example output files of any test case will be stored 3.

When not specified, logging directory is still generated with a default name.

If the provided directory already exists, then the command line option -f must be provided to override the directory: all contents of the directory will be removed.

See Result directory section for more information on the different directories and files generated by xbtest.

$ xbtest -l path/to/log_dir -d <BDF> -j path/to/my_tests.json

-L: Disable logging directory ¶

-L¶

Disable logging directory generation in which all output files of any test case will be stored 3.

No message displayed during the execution will be stored.

$ xbtest -L -d <BDF> -j path/to/my_tests.json

-m: Display message information ¶

-m <message ID>¶

Display message information for the given <message ID>: severity, details or resolution (when applicable) 1.

$ xbtest -d <BDF> -m <message ID>

-F: Disable dynamic display ¶

-F¶

Disable the dynamic display mode.

When not provided, xbtest defaults to the dynamic display mode.

See Display modes section for more information on the messages displayed by xbtest in the console.

$ xbtest -F -d <BDF> -j path/to/my_tests.json

-f: Force an operation ¶

-f¶

When possible, force an operation.

This can be used to override an already existing logging directory provided with option -l: all contents of the directory will be removed.

$ xbtest -f -l <PathTo/LogDirToOverride> -d <BDF> -j path/to/my_tests.json

-b: Select verbosity ¶

-b <verbosity level>¶

Select the verbosity level <verbosity level>;

Range: [-4, 0]; Default: 0.

Setting a negative verbosity level enables display of extra messages with DEBUG severity (see Understanding xbtest messages).

$ xbtest -b <verbosity level> -d <BDF> -j path/to/my_tests.json

The following table describes the different severity levels that can be enabled:

Extra verbosity level¶
Level	Details
0	No debug information is reported by default.
-1	This level allows to reports debug information for test cases and tasks (intermediate results/measurements/test steps). The handiest one to debug a tricky situation and have more information about the ongoing test.
-2	Use this level for more information regarding the host application setup phase.
-3	Reports debug information for xbtIP access related calls. This may be used for example if the board/SW hangs.
-4	This level activates the debug messages of the host application parsers (e.g. JSON files, command line).

These DEBUG messages are not supported by command line option -m.

There are no details, nor resolution available. There are no rules about their content or even their accuracy (the best way to understand them is to have access to the SW source code to follow their generation).

-t: Select timestamp ¶

-t <timestamp>¶

Select the timestamp mode <timestamp>;

Possible values: none, absolute and differential.

Defaults to none when not specified.

$ xbtest -t <timestamp> -d <BDF> -j path/to/my_tests.json

The following table described the supported timestamp modes.

Timestamp modes¶
Mode	Details	Example
`none`	By default, no timestamp is used in the log messages.	STATUS :: CMN_032 :: POWER :: Start Test 1: [300, 49]
`absolute`	The absolute elapsed wall-clock time since some arbitrary, fixed point in the past (typically since reboot of the server). This is handy to link `dmesg` file with `xbtest.log` file as it uses the same format (second with 6 decimal digits precision).	[263445.141868] STATUS :: CMN_032 :: POWER :: Start Test 1: [300, 49]
`differential`	Elapsed time since the previous message displayed.	[+0.000076] STATUS :: CMN_032 :: POWER :: Start Test 1: [300, 49]

Warning

This will slow down the software as each message requests a timestamp to the OS (clock monotonic). The slow down shouldn’t be noticeable if only 1 xbtest instance is running or if the processors are not heavily loaded. With multi-cards or CPU stress test running, the behaviour of xbtest cannot be guaranteed.

-D: Select card configuration JSON (multi cards test)¶

-D path/to/card_cfg.json¶

Provide a card configuration JSON file path/to/card_cfg.json.

This file can be used, instead of the command line, to select cards, test JSON files and pre-canned tests.

This option can be provided only once and cannot be combined with the -d, -c, -j options.

See Complex multi cards test section for more information on the parameters supported in this file.

$ xbtest -D path/to/card_cfg.json

-i & -e: Select PDI and card definition JSON ¶

-i <pdi>¶: Select the PDI <pdi>. This is used to find the xbtest metadata JSON files.

-e <card definition>¶: Select the Card definition JSON file <card definition>.

These options -i and -e are used internally by xbtest application software (xbtSW) while dispatching the test run.

Note

1(1,2,3,4): Prevents any test being launched.
2(1,2): The maximum number of tests (number of times options -c and -j are present in command line) for each card configuration is 999.
3(1,2): -l and -L cannot be combined.

Single card examples¶

Single test on a single card¶

The following example shows how to run only one test, Test JSON files (-j) or pre-canned test (-c), on a single card.

$ xbtest -d 0000:5e:00.1 -j path/to/my_tests.json
$ xbtest -d 0000:5e:00.1 -c verify

In the below example, the verbosity has been increase to include more debug messages and by disabling the dynamic console, all messages are printed in the console.

$ xbtest -d 0000:5e:00.1 -j path/to/my_tests.json -F -b -1

Multiple tests on a single card¶

Test JSON files (-j) and pre-canned test (-c) options can be mixed.

Each test provided is run one after the other for the specified BDF.

An error in one test on one card does not stop any other tests.

For example:

$ xbtest -d 0000:5e:00.1 -c verify -c stress -j path/to/my_tests.json

Multi card support¶

xbtest supports natively the dispatch of test across various cards. You don’t need to open various terminals.

This can be done via the command line or a card configuration json

Command line: for quick and easy multiple card tests.

Multiple tests on a single card.

Same tests over multiple cards.

Multiple tests over multiple cards.

Card configuration json file: for complex test sequence and card selection with support for individual option per test and card.

Same tests on multiple cards¶

Different cards can be targeted simultaneously.

Each test provided is run one after the other for all selected cards.

For example:

$ xbtest -d 0000:5e:00.1 -d 0000:d9:00.1 -d 0000:86:00.1 -c dma -j path/to/my_tests.json -c memory -j path/to/another_test.json -b -1

In this example, the card configurations for all cards (0000:5e:00.1 & 0000:d9:00.1 & 0000:86:00.1) are:

Test 1: pre-canned dma

Test 2: path/to/my_tests.json

Test 3: pre-canned memory

Test 4: path/to/another_test.json

-b -1 for all tests

Different tests on multiple cards¶

The tests run can differs between each card.

$ xbtest -d 0000:5e:00.1 -d 0000:d9:00.1 -c dma -j path/to/my_tests.json -c memory -b -1 \
         -d 0000:86:00.1                 -j path/to/my_card_specific_test.json

In this example, the card configurations are:

0000:5e:00.1 & 0000:d9:00.1:

Test 1: pre-canned dma

Test 2: path/to/my_tests.json

Test 3: pre-canned memory

-b -1 is used for all tests

0000:86:00.1:

Test 1: path/to/my_card_specific_test.json

Complex multi cards test¶

For complex test sequence, the card configuration JSON file will offer more flexibility and configuration.

The card configuration JSON file is used to define:

List of BDF.

List of tests:

Test JSON file or pre-canned test.

Possibly add other options for each test individually.

Possibly overwrite tests definition per BDF.

Comments supported at any level of the JSON file.

The card configuration JSON file is selected using command line option -D:

$ xbtest -D card_config.json

Card configuration JSON definition¶

The following table defines the parameters supported in the card configuration JSON file:

Card configuration JSON file parameter definition¶
Node name				Node type	Example	Command line equivalent	Mandatory / Optional	Default	Description
Level 0	Level 1	Level 2	Level 3	Node type	Example	Command line equivalent	Mandatory / Optional	Default	Description
global_config	args			string	“-b -1”	-b -1	Optional		Specify the other command line options to be passed to xbtest SW for all cards. These options and options defined in command line must be different.
	cards			List<string>	[“0000:86:00.1”, “0000:5e:00.1”]	-d 0000:86:00.1 -d 0000:5e:00.1	Mandatory		List of card BDFs. Maximum number of cards in this list is 100.
	tests			List<object>			Mandatory		List of objects. Each object defines a test. Tests are run in the same order as specified in the list. Maximum number of tests in this list is 999.
		args		string	“-b -1”	-b -1	Optional	global_config.args	Overwrites `global_config.args` for this test, for all cards.
		test_json		string	“path/to/my_tests.json”	-j path/to/my_tests.json	Mandatory when `pre_canned` not defined		Test JSON file.
		pre_canned		string	“stress”	-c stress	Optional when `test_json` not defined		Pre-canned test.
card_config	`<BDF>`			object			Optional		Overwrite for card identified by `<BDF>` Valid `<BDF>` nodes are values provided in `global_config.cards` list.
		args		string	“-b -1”	-b -1	Optional	global_config.args	Overwrites `global_config.args` for all tests for card identified by `<BDF>`.
		tests		List<object>			Mandatory	gloabal_config.tests	Overwrites `global_config.tests` for card identified by `<BDF>`. Number of tests in `card_config.<BDF>.tests` does not necessarily equal number of tests in `global_config.tests` and can be different for each card. Maximum number of tests in this list is 999.
			args	string	“-b -1”	-b -1	Optional	card_config.<BDF>.args	Overwrites `card_config.<BDF>.args` for this test.
			test_json	string	“path/to/my_tests.json”	-j path/to/my_tests.json	Mandatory when `pre_canned` not defined		Test JSON file for card identified by `<BDF>`.
			pre_canned	string	“stress”	-c stress	Optional when `test_json` not defined		Pre-canned test for card identified by `<BDF>`.

Here are some examples:

{
    "comment": "First define all tests and all targeted cards",
    "global_config": {
        "args" : "-b -1",
        "cards": ["0000:86:00.1", "0000:5e:00.1", "0000:d9:00.1"],
        "tests": [
            {   "pre_canned": "verify"                                  },
            {   "test_json" : "path/to/my_tests.json",  "args": "-b -2" }
        ]
    },
    "comment": "Then override tests for some cards if needed",
    "card_config": {
        "0000:5e:00.1": {
            "tests": [
                {   "pre_canned": "power", "args": "-b 0"     },
                {   "test_json" : "path/to/another_test.json" },
            ]
        }
    }
}