# 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](#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](#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-gbs`argument 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 `--gbs`argument is required. If you do not specify the `--rbf` argument, the command defaults to `

| 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 <key>:<value> 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. |