Syntax for the imgctrl Tool

Handling FPGA Images

product_line_custom
Napatech SmartNIC
category
User Guide

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']]
[('-s'|'--switch') ('-a'|'--adapter') <adapter identifier> ['--confirm']
                   ['--discard'] ['--pcirst'] ['--reload'] ['--pcix8'] ['--pcix8x8']]
[('-p'|'--program') ('-a'|'--adapter') <adapter identifier> ['-g'|'--group']
                    '--ini' '"'<string>'"' '--ntimg' <filename>
                    ['--force-bank' <image location>]]
['-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 products that this version can handle.

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.

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.
'--pcix8' Only applies to NT200A01, and only to servers without PCI bifurcation support or to servers with bifurcation support where ×8×8 bifurcation mode is not enabled for the slot in question. Configures the SmartNIC to use only one 8-lane end point. This reduces the PCI bandwidth. The server must be rebooted to assert the new PCIe configuration.
'--pcix8x8' Only applies to NT200A01, and only to servers with PCI bifurcation support. Configures the SmartNIC to use two 8-lane end points. This is the default setting. Two PCI 8-lane devices (×8×8) must be enabled in the server, and the server must be rebooted to assert the new PCIe configuration.

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.

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.

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