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.05.21 | DCP 1.1 Beta (works with Quartus Prime Pro 17.1.1) | Fixed typos. |