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-g bs --rbf=<RBF_PATH > --afu=<AFU_JS ON_PATH> --gbs=<GBS_PA TH> --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_P ATH> 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>.<valu e> pairs.
modify-g bs --gbs=<gbs_PATH > Modifies the AF file. The --input-gbs ``\ argument is required. If you do not provide the ``--output-gb s 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>.<valu e> pairs.
``gbs-info `` --input-gbs=<gb s_PATH> Prints information about the AF file. The ``–input-gbs `` argument is required.
``get-rbf` ` --gbs=<GBS_PATH > --rbf=<RBF_PA TH> Creates the RBF by extracting it from the AF file. The --gbsar gument is required. If you do not specify the --rbf argument, the command defaults to <gbs_name.r bf .
None, or any <CMD> --help Summarizes the <CMD> options. Typing packager -- help gives a list of <CMD> values. Typing packager <C MD> --help 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 version Integer Version of the metadata format. Yes
Per-AFU magic-n o (to be depreca ted) Integer Magic no. Associated with the FPGA Interface Manager. No
Per-AFU platfor m-name 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 interfa ce-uuid UUID Interface id associated with the FPGA Interface Manager. Yes
Per-AFU power Integer Accelerator Function power consumption, in watts. Set to 0 for Intel Acceleration Stack for FPGAs platforms. Yes
Per-AFU clock-f requenc y-low Float Clock frequency for 1st PLL (Clock network)1 in MHz. No
Per-AFU clock-f requenc y-high Float Clock frequency for 2nd PLL (0 if absent) in MHz. No
Per-AFC Cluster total-c ontexts Integer Number of AFCs in this cluster. Always be 1 in current architectures. Yes
Per-AFC Cluster afc-typ e-uuid 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.10. 15 1.2. (Supported with Intel Quartus Prime Pro Edition 17.1.1.) No changes from previous release.
2018.05. 21 DCP 1.1 Beta (works with Quartus Prime Pro 17.1.1) Fixed typos.