packager

SYNOPSIS

packager <cmd> [arguments]

Description

The packager provides tools that Accelerator Functional Unit (AFU) developers use to create Accelerator Function (AF) files. The AF file is the programming file for an AFU on Intel® FPGA platforms. The packager tool concatenates the metadata from the JSON file to a raw binary file (.rbf) that the Intel Quartus® Prime software generates.

The packager’s only function is to create an AF file. Refer to Packager Command Syntax for more information about invoking the packager. The packager depends on a JSON file to describe AFU metadata. Refer to Accelerator Description File for more information about the JSON file.

The packager requires Python 2.7.1 and Python 2.7.3. The tool indicates if it is being called with a compatible of Python.

Packager Command Syntax

The packager is a command line tool with the following syntax:

$ packager <cmd> [arguments]

The following table describes the <CMD> arguments:

Command	Arguments	Description
create-gbs	--rbf=<RBF_PATH> --afu=<AFU_JSON_PATH> --gbs=<GBS_PATH> --set-value=<key>.<value >	Creates the AF file. The engineering name for this file is the green bit stream, abbreviated gbs. The --rbf and --afu arguments are required. <RBF_PATH> is the path to the RBF file for the AFU. The Quartus® Prime software generates this RBF by compiling the AFU design. <AFU_JSON_PATH> is the path to the Accelerator Description file. This is a JSON file that describes the metadata that create-gbs appends to the RBF. <GBS_PATH> is the path to the RBF file for the FPGA Interface Manager (FIM) that contains the FPGA interface unit and other interfaces. If you do not specify the --gbs, the command defaults to <rbf_name>.gbs. You can use the optional --set-value=<key>. <value> argument to set values for JSON metadata. To set more than one JSON value, list a series of <key>.<value> pairs.
modify-gbs	--gbs=<gbs_PATH>	Modifies the AF file. The --input-gbsarg ument is required. If you do not provide the --output-gbs argument, modify-gbs overwrites the --input-gbs file. Use the --set-value=<key>. <value> argument to set values for JSON metadata. To set more than one JSON value, list a series of <key>.<value> pairs.
gbs-info	--input-gbs=<gbs_PATH>	Prints information about the AF file. The --input-gbs argument is required.
get-rbf	--gbs=<GBS_PATH> --rbf=<RBF_PATH>	Creates the RBF by extracting it from the AF file. The --gbsargument is required. If you do not specify the --rbf argument, the command defaults to <gbs_name.rbf .
None, or any <CMD>	--help	Summarizes the <CMD> options. Typing packager --help gives a list of <CMD> values. Typing packager <CMD> --h elp provides detailed help for <CMD>

Examples

To generate an AF file, run:

$ packager create-gbs --rbf=<RBF_PATH> --afu=<AFU_JSON_PATH> --gbs=<GBS_PATH>

TIP: JSON files are very particular about syntax such as trailing commas. If you are getting errors, use jsonlint.com to validate that your JSON is formatted correctly.

To modify metadata in an existing AF, run the following command:

$ packager modify-gbs --input-gbs=<PATH_TO_GBS_TO_BE_MODIFIED> --outputgbs=<NAME_FOR_NEW_GBS> --set-value <key>:<value>

You can pass in a number of : pairs with –set-value to update values in an AF.

To print the metadata of an existing AF:

$ packager get-info --gbs=<GBS_PATH>

To extract the RBF from the AF:

$ packager get-rbf --gbs=<GBS_PATH> --rbf=<NAME_FOR_RBF>

Accelerator Description File

The Accelerator Description File is a JSON file that describes the metadata associated with an AFU. The Open Progammable Accelerator Engine (OPAE) uses this metadata during reconfiguration. Here is an example file:

{
   "version": 1,
   "platform-name": "DCP",
   "afu-image": {
      "magic-no": 488605312,
      "interface-uuid": "01234567-89AB-CDEF-0123-456789ABCDEF",
      "power": 0,
      "accelerator-clusters": [{
         "name": "dma_test_afu",
         "total-contexts": 1,
         "accelerator-type-uuid": "331DB30C-9885-41EA-9081-F88B8F655CAA"
      }
      ]
   }
}

The packager stores these parameter values in the resultant AF. After reprogramming the AFU using partial reconfiguration (PR), the software driver reconfigures the PLLs by writing the clock-frequency-high and clock-frequency-low values (if present) over the PCIe® and CCI interfaces.

The JSON file format may change as the architecture evolves. Any changes to the current format trigger an update
to the version number.

CATEGORY	NAME	TYPE	DESCRIPTION	MANDATORY
Per-AFU	versio n	Intege r	Version of the metadata format.	Yes
Per-AFU	magic- no (to be deprec ated)	Intege r	Magic no. Associated with the FPGA Interface Manager.	No
Per-AFU	platfo rm-nam e	String	Name of the platform for which the metadata is intended. The field value is “DCP” for Intel Acceleration Stack for FPGAs.	No
Per-AFU	interf ace-uu id	UUID	Interface id associated with the FPGA Interface Manager.	Yes
Per-AFU	power	Intege r	Accelerator Function power consumption, in watts. Set to 0 for Intel Acceleration Stack for FPGAs platforms.	Yes
Per-AFU	clock- freque ncy-lo w	Float	Clock frequency for 1st PLL (Clock network)1 in MHz.	No
Per-AFU	clock- freque ncy-hi gh	Float	Clock frequency for 2nd PLL (0 if absent) in MHz.	No
Per-AFC Cluster	total- contex ts	Intege r	Number of AFCs in this cluster. Always be 1 in current architectures.	Yes
Per-AFC Cluster	afc-ty pe-uui d	UUID	AFC type = AFU ID in current architectures.	Yes
Per-AFC Cluster	name	string	AFC name = AFU name in current architectures.	Yes

Date	Intel Acceleration Stack Version	Changes Made
2018.05.21	DCP 1.1 Beta (works with Quartus Prime Pro 17.1.1)	Fixed typos.