In this chapter
This chapter explains the syntax for the imgctrl tool.
Backus-Naur form
The syntax for the tools is specified using Backus-Naur form (BNF) notation. The BNF semantics used are explained in this table.
Symbol | Meaning |
---|---|
<...> | Syntactic category (nonterminal) |
'...' | As is (literal word – terminal) |
[...] | Optional, can appear zero or 1 time |
| | Or (separates alternatives) |
() | Used for grouping |
Syntax
The syntax for imgctrl is as shown below.
'imgctrl' [('-q'|'--query') [('-a'|'--adapter') <adapter identifier>] ['-b'|'--brief'] ['-l'|'--log']] ['-u'|'--upgrade']] ['-*'|'--any']] [('-s'|'--switch') ('-a'|'--adapter') <adapter identifier> ['--confirm'] ['--discard'] ['--pcirst'] ['--reload'] ['--pcix8'] ['--pcix8x8']] ['--any']] [('-p'|'--program') ('-a'|'--adapter') <adapter identifier> ['-g'|'--group'] '--ini' '"'<string>'"' '--ntimg' <filename> '--ntimg2' <filename> ['--force-bank' <image location>]] ['--psu'] ['--smb-adr'] ['--any'] ['-v'|'--verbose'] ['-?'|'--help'] ['-V'|'--version'] ['--known-products']
Optional overall parameters
This table explains the optional overall parameters.
Parameter | Description |
---|---|
'-q'|'--query' | Specifies the query mode (see Query Mode), which queries Napatech SmartNICs. |
'-s'|'--switch' | Specifies the switch mode (see Switch Mode), which switches the image of a SmartNIC. |
'-p'|'--program' | Specifies the program mode (see Program Mode), which upgrades or downgrades the flash of a SmartNIC. |
'-v'|'--verbose' | Displays a more verbose output, that is an output
containing more detailed information. This parameter is stackable, that is –v provides extended output, -vv includes debugging info, -vvv includes more information, and -vvvv includes even more. |
'-?'|'--help' | Displays a help message describing the tool including syntax and parameters. |
'-V'|'--version' | Displays the version of the imgctrl tool. |
'--known-products' | Lists known FPGA IDs that this version can handle for a specific SmartNIC. |
Optional query mode parameters
This table explains the optional query mode parameters.
Parameter | Description |
---|---|
('-a'|'--adapter') <adapter identifier> | Specifies that the tool only displays information for SmartNIC <adapter identifier>. <adapter identifier> can take the values 0, 1, 2, ..., or can be written as a PCI ID in the format [<domain>:]<bus>:<slot>:<func>, where [<domain>:] is optional and where ‘:’ can also be another separator, such as comma (,) or period (.). |
'-b'|'--brief' | Displays one line of information for each SmartNIC. |
'-l'|'--log' | Reads and displays the entries in the hardware log. |
'-u'|'--upgrade' | Displays a list of the FPGAs that are supported for the SmartNIC in question. |
'-*'|'--any' | Enables display of information from SmartNICs where the running FPGA ID or major version is not supported. |
Mandatory switch mode parameters
This table explains the mandatory switch mode parameters.
Parameter | Description |
---|---|
('-a'|'--adapter') <adapter identifier> | Specifies the SmartNIC on which the tool switches the image. <adapter identifier> can take the values 0, 1, 2, ..., or can be written as a PCI ID in the format [<domain>:]<bus>:<slot>:<func>, where [<domain>:] is optional and where ‘:’ can also be another separator, such as comma (,) or period (.). |
Optional switch mode parameters
This table explains the optional switch mode parameters.
Parameter | Description |
---|---|
'--confirm' | Updates the primary image to reflect the currently running image. This parameter can only be used when the SmartNIC is in the IMAGE SWITCH EVENT IN PROGRESS state (see IMAGE SWITCH EVENT IN PROGRESS state). |
'--discard' | Discards the current switch attempt. This parameter can be used if a quick switch has failed, or to cancel an attempt to switch after the next reboot (using --pcirst). |
'--pcirst' | Forces the switch not to take place until after the next reboot. |
'--reload' | Performs an FPGA reload from the primary image bank. The SmartNIC must be in the NEUTRAL state (see NEUTRAL state) before the reload. After the reload, the SmartNIC remains in the NEUTRAL state. If the reload fails, --discard must be used. |
'--any' | Enables a switch from a running FPGA ID or major version that is not supported. |
Mandatory program mode parameters
This table explains the mandatory program mode parameters.
Parameter | Description |
---|---|
('-a'|'--adapter') <adapter identifier> | Specifies the SmartNIC in which the tool upgrades or downgrades the flash. <adapter identifier> can take the values 0, 1, 2, ..., or can be written as a PCI ID in the format [<domain>:]<bus>:<slot>:<func>, where [<domain>:] is optional and where ‘:’ can also be another separator, such as comma (,) or period (.). |
'--ini' '"'<string>'"' | Specifies the string in question, for instance the initials of the operator or a tag to identify the upload. |
'--ntimg' <filename> | Specifies the .ntimg FPGA image file to be uploaded to the flash. If two images are uploaded in one command by also applying the '--ntimg2' parameter, the '--ntimg' is always uploaded to bank 0, and the '--ntimg2' is always uploaded to bank 1. |
Optional program mode parameters
This table explains the optional program mode parameters.
Parameter | Description |
---|---|
'-g'|'--group' | Specifies that the tool upgrades or downgrades the flash for the
entire group of SmartNICs that can be upgraded or downgraded with the FPGA image
specified by the mandatory --ntimg parameter. Note: To save time
when -g or --group is used, no verification is
performed unless the optional overall -v or
--verbose parameter is also used.
|
'--force-bank' <image location> | Forces a specific image location (0 or 1) to be upgraded/downgraded. |
'--ntimg2' <filename> | Specifies a second .ntimg FPGA image file to be uploaded. This image is always uploaded to bank 1. |
'--psu | Programs the PSU (power supply) configuration of the SmartNIC. Only
applies to the following SmartNICs.
Note: '--psu must be used only when
instructed to by Napatech.
|
'--smb-adr' | Programs the NVM (nonvolatile memory) SMB (System Management Bus)
slave address. The address must be an even number in the range [64, …,
192]. Note: The value 254 removes any previously set NVM SMB slave
address.
Only applies to the following SmartNICs.
|
'--any' | Upgrades or downgrades the flash to any major version of a known FPGA ID also on SmartNICs running on an FPGA ID or major version that is not supported. |
Command example
This is an example of how to execute imgctrl.
$ imgctrl --program --adapter 1 --ntimg path/to/ntimg/file --ini "my string"
Output example
This is an example of an output from the imgctrl tool when the command example in Command example has been executed.
imgctrl v2.3.4.29185 (Oct 20 2014 17:32:43) (Logfile: /tmp/imgctrl.log) Scanning for Napatech adapters.. Adapter upgrade commencing.. Writing FPGA bank 1 Erasing................... 100% done Writing................... 100% done Verifying................. 100% done Done writing FPGA bank 1 Note: You can inspect the upload result through the Bank1 Contents section using the --query mode. To try the new image, remember to switch bank using the --switch mode. See --help for more information. Upgrade process complete