# super-rsu #
## SYNOPSIS ##
```console
super-rsu [-h] [-n] [--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 can be used for flashing image files and commanding an
Intel PAC device to perform RSU (remote system update - or a board reboot).
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.
At the core of super-rsu is its configuration file (referred to in this
document as 'rsu_config') which is essentially a manifest file for
identifying both the target device and the binary images (and their versions)
to be flashed.
At a high level, the flow of super-rsu should be:
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 fpgaflash 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 fpgaflash 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 fpgaflash 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)
## OPTIONAL ARGUMENTS ##
`-h, --help`
Print usage information.
`--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.
```JSON
{
"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": [
"nvmupdate",
],
"properties": {
"product": {
"$id": "#/properties/product",
"type": "string",
"title": "The Product Schema",
"default": "",
"examples": [
"n3000"
],
"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"]
},
"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/nvmupdate/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\\.]+)$"
}
}
}
}
}
}
```