super-rsu¶
SYNOPSIS¶
super-rsu [-h] [--program <program name>] [-n | --dry-run] [--verify]
| [ [--log-level {trace,debug,error,warn,info,notset}]
[--log-file <filename>] [--rsu-only] [--with-rsu] [--force-flash] ]
rsu_config
DESCRIPTION¶
super-rsu is a tool that manages the execution of updates to an Intel PAC device based on an rsu config or manifest file. This file contains a list of files (relative to the config file), the type of image contained in those files and the versions of the update. Additionally, super-rsu can perform an RSU (remote system update) operation on the devices that support RSU. Performing an RSU on an Intel PAC device will cause it to reload any firmware or programmable logic and restart its execution, a requirement for any updated firmware or programmable logic to take effect. Using the information provided in the rsu config file, super-rsu will run programs like ‘fpgasupdate’, ‘fpgaflash’, or ‘nvmupdate64e’ to load the image onto the device. ‘fpgasupdate’ is the standard program to load signed IP onto the device. ‘fpgaflash’ is for legacy IP used on devices that haven’t been updgraded for authenticating signed IP. ‘nvmupdate64e’ is the program used to load firmware onto Intel Ethernet devices.
At the core of super-rsu is its configuration file (referred to in this document as ‘rsu_config’) which is a manifest file for identifying both the target device and the binary images (and their versions) to be flashed.
The flow of super-rsu is as follows: 1. Read and parse rsu_config file 2. Use product identifiers (like vendor, device and any additional vendor, device pairs that may be present in the PCIe bus) to locate all compatible devices on the PCIe bus. 3. For every device found on the system, update the device using the flash images defined in the “flash” section in the rsu_config data (or nvmupdate section). Each item in the “flash” section is a “flash spec” that contains: * The flash type (“user”, “bmc_fw”, “bmc_img”, …) * The filename of the image to flash. super-rsu will look for this file first in the same directory of the rsu_config file, and then look in the current working directory. * The version of the image. * An optional “force” indicator * An optional “requires” indicator The “nvmupdate” section is used to describe an Ethernet firmware file and its version. 4. Using the data in the “nvmupdate” and “flash” sections, the update routine involves: * If an “nvmupdate” section is present: 1. Locate the file on the file system to use to flash the Ethernet device. 2. Call nvmupdate to get an “inventory” of devices matching the vendor and device id in this section. 3. Use this data to dynamically generate an nvmupdate compatible configuration file. 4. Call nvmupdate with the generated configuration file to flash the Ethernet interfaces in the Vista Creek card (if version reported by system does not match the version in this section). * For each spec in the “flash” section: 1. Locate the file on the file system to use to flash. 2. Compare the version listed in the “flash spec” to version reported by the target component. 3. Create a task to call fpgasupdate if either of the following conditions is met (and the revision specified is compatible): * The “force” indicator is present and set to true. * The version in the spec does not match the version reported by the system OR the flash type is factory type. * For each task created from the “flash” section: 1. Call fpgasupdate with the command line arguments that correspond to the flash type and the file name in the spec used to create the task. This opens and controls the execution of fpgasupdate in another process.
NOTE: If the system reports a revision for one of the components being flashed, this revision must be in the set of revisions listed in the manifest. Example: if the system reports ‘a’ for bmc_img and the manifest includes ‘ab’, then the image will be flashed.
NOTE: Each update routine is run in a thread specific to a device
located on the PCIe bus. Every task in an update routine involves
opening a new process that is controlled and managed by its update
routine thread. If a task includes a timeout and the timeout is reached,
a termination request will be sent to its process and it will be counted
as a failure. If a global timeout is reached in the main thread, a
termination request will be sent to each thread performing the update.
Consequently, the update routine will give the current task extra time
before terminating the process. The RSU operation will only be performed
if requested with either --with-rsu command line argument or with
the --rsu-only command line argument. The former will perform the
RSU command upon successful completion of flash operations. The latter
will skip the process of version matching and flashing images and will
only perform the RSU command. It is recommended that super-rsu be
executed again if any flash operation is interrupted.
POSITIONAL ARGUMENTS¶
rsu config
Specifies the name of the file containing the RSU configuration (in JSON format). If omitted, super-rsu will look in well known locations (/usr/share/opae) for .json files that can be used for flashing.
OPTIONAL ARGUMENTS¶
-h, --help
Print usage information.
--program
Program to look for in rsu config. This can be used in place of the `rsu
config` positional argument. Default value is 'super-rsu'.
--verify
Compare versions of flashable components on the system against the manifest.
Return non-zero exit if compatible components are not up to date.
-n, --dry-run
Don't perform any updates, just a dry run.
This will print out commands that can be executed
in a Linux shell.
--log-level {trace,debug,error,warn,info,notset}
Log level to use. Default is 'info'.
--log-file <filename> (default: /tmp/super-rsu.log)
Emit log messages (with DEBUG level) to filename
_NOTE_: The default log file (/tmp/super-rsu.log) is set to rollover every
time super-rsu is executed. This will create numbered backups before
truncating the log file. The maximum number of backups is 50.
--rsu-only
Only perform the RSU command.
--with-rsu
Perform RSU after updating flash components(experimental)
--force-flash
Flash all images regardless of versions matching or not.
CONFIGURATION¶
The following is the JSON schema expected by super-rsu. Any deviance from this schema may result in errors executing super-rsu.
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/root.json",
"type": "object",
"title": "The Root Schema",
"required": [
"product",
"vendor",
"device",
"flash"
],
"optional": [
"configuration",
"program",
"nvmupdate",
],
"properties": {
"product": {
"$id": "#/properties/product",
"type": "string",
"title": "The Product Schema",
"default": "",
"examples": [
"n3000"
],
"pattern": "^(.*)$"
},
"properties": {
"program": {
"$id": "#/properties/configuration",
"type": "string",
"title": "The Product Schema",
"default": "",
"examples": [
"2x1x25"
],
"pattern": "^(.*)$"
},
"properties": {
"program": {
"$id": "#/properties/program",
"type": "string",
"title": "The Product Schema",
"default": "super-rsu",
"examples": [
"super-rsu"
],
"pattern": "^(.*)$"
},
"vendor": {
"$id": "#/properties/vendor",
"type": "string",
"title": "The Vendor Schema",
"default": "",
"examples": [
"0x8086"
],
"pattern": "^((0x)?[A-Fa-f0-9]{4})$"
},
"device": {
"$id": "#/properties/device",
"type": "string",
"title": "The Device Schema",
"default": "",
"examples": [
"0x0b30"
],
"pattern": "^((0x)?[A-Fa-f0-9]{4})$"
},
"nvmupdate": {
"$id": "#/properties/nvmupdate",
"type": "object",
"title": "The nvmupdate Schema",
"required": [
"vendor",
"device",
"filename",
"version"
],
"optional": [
"interfaces"
],
"properties": {
"vendor": {
"$id": "#/properties/nvmupdate/vendor",
"type": "string",
"title": "The nvmupdate Vendor Schema",
"default": "",
"examples": [
"0x8086"
],
"pattern": "^((0x)?[A-Fa-f0-9]{4})$"
},
"device": {
"$id": "#/properties/nvmupdate/device",
"type": "string",
"title": "The nvmupdate Device Schema",
"default": "",
"examples": [
"0x0d58"
],
"pattern": "^((0x)?[A-Fa-f0-9]{4})$"
},
"interfaces": {
"$id": "#/properties/nvmupdate/interfaces",
"type": "number",
"title": "The nvmupdate Interfaces Schema",
"default": "1",
"examples": [
2, 4
]
},
"filename": {
"$id": "#/properties/nvmupdate/filename",
"type": "string",
"title": "The nvmupdate Filename Schema",
"default": "",
"examples": [
"PSG_XL710_6p80_XLAUI_NCSI_CFGID2p61_Dual_DID_0D58_800049C6.bin"
],
"pattern": "^(.*)$"
},
"version": {
"$id": "#/properties/nvmupdate/version",
"type": "string",
"title": "The nvmupdate Version Schema",
"default": "",
"examples": [
"800049C6"
],
"pattern": "^((0x)?[A-Fa-f0-9]{8})$"
},
"timeout": {
"$id": "#/properties/nvmupdate/timeout",
"type": "string",
"title": "The Timeout Schema",
"default": "",
"examples": [
"10m"
],
"pattern": "^([0-9]+(\\.[0-9]+)?([dhms]))+$"
}
}
},
"flash": {
"$id": "#/properties/flash",
"type": "array",
"title": "The Flash Schema",
"items": {
"$id": "#/properties/flash/items",
"type": "object",
"title": "The Items Schema",
"required": [
"filename",
"type",
"version",
"revision"
],
"optional": [
"enabled",
"force",
"timeout",
"requires"
],
"properties": {
"enabled": {
"$id": "#/properties/flash/items/properties/enabled",
"type": "boolean",
"title": "The Enabled Schema",
"default": "true"
},
"filename": {
"$id": "#/properties/flash/items/properties/filename",
"type": "string",
"title": "The Filename Schema",
"default": "",
"examples": [
"vista_creek_qspi_xip_v1.0.6.ihex"
],
"pattern": "^(.*)$"
},
"type": {
"$id": "#/properties/flash/items/properties/type",
"type": "string",
"title": "The Type Schema",
"default": "",
"examples": [
"bmc_fw"
],
"enum": ["user", "bmc_fw", "bmc_img", "dtb", "factory_only",
"phy_eeprom", "bmc_pkg"]
},
"version": {
"$id": "#/properties/flash/items/properties/version",
"type": "string",
"title": "The Version Schema",
"default": "",
"examples": [
"1.0.6"
],
"pattern": "^\\d+\\.\\d+\\.\\d+$"
},
"force": {
"$id": "#/properties/flash/items/properties/force",
"type": "boolean",
"title": "The Force Schema",
"default": false,
"examples": [
true
]
},
"revision": {
"$id": "#/properties/flash/items/properties/revision",
"type": "string",
"title": "The Revision Schema",
"default": "",
"examples": [
"C"
],
"pattern": "^([A-Za-z])$"
},
"timeout": {
"$id": "#/properties/flash/items/properties/timeout",
"type": "string",
"title": "The Timeout Schema",
"default": "",
"examples": [
"10m"
],
"pattern": "^([0-9]+(\.[0-9]+)?([dhms]))+$"
},
"requires": {
"$id": "#/properties/flash/items/properties/requires",
"type": "string",
"title": "The Requires Schema",
"default": "",
"examples": [
"bmc_img >= 1.0.12"
],
"pattern": "^(([a-z_]+) ((<>!=)?=) ([0-9a-z\\.]+)$"
}
}
}
}
}
}