Syntax for the imgctrl Tool

Handling FPGA Images

Platform
Napatech SmartNIC
Content Type
User Guide
Capture Software Version
Link™ Capture Software 12.11

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.
  • NT400D11
  • The newer version of NT200A02 (see DN-1169 and DN-1200)
  • NT100A01
  • NT50B01
  • NT40A11
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.
  • NT400D11
  • The newer version of NT200A02 (see DN-1169 and DN-1200)
  • NT100A01
  • NT50B01
  • NT40A11
'--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