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-gbsargument 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> --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.

.. note::

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-no (to be deprecated)| Integer | Magic no. Associated with the FPGA Interface Manager. | No Per-AFU | platform-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 | interface-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-frequency-low | Float | Clock frequency for 1st PLL (Clock network)1 in MHz. | No Per-AFU | clock-frequency-high | Float | Clock frequency for 2nd PLL (0 if absent) in MHz. | No Per-AFC Cluster | total-contexts | Integer | Number of AFCs in this cluster. Always be 1 in current architectures. | Yes Per-AFC Cluster | afc-type-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.05.21| DCP 1.1 Beta (works with Quartus Prime Pro 17.1.1) | Fixed typos. |