Cyborg FPGA Bitstream metadata spec¶

Problem description¶

A field-programmable gate array (FPGA) is an integrated circuit designed to be configured by a customer or a designer after manufacturing. Their advantage lies in that they are sometimes significantly faster for some applications because of their parallel nature and optimality in terms of the number of gates used for a certain process. Hence, using FPGA for application acceleration in cloud has become desirable. One of the encountered problems is when it comes to bitstream management, it is difficult to map bitstreams to their appropriate FPGA boards or reconfigurable regions. The aim of this proposal is to provide a standardized set of metadata which should be encapsulated together with bitstream storage.

Proposed change¶

For each metadata, it will be stored as a row in this Glance’s image_properties in key-value pair format: column [name] holds the key whereas column [value] holds the value. Note: no batabase schema change is required. This is a standardization document to guide how to use existing Glance table for FPGA bitstreams.

Given this, Cyborg will standardize the key convention as follows:

Here are the details regarding some definded keys.

[shell_id] This field is optional. If a loading this PR bitstream requires a shell image, this field specifies the shell bitstream’s uuid. If it field is null, it means this bitstream is a shell bitstream.

[driver] This specifies the path to a package of scripts/binaries to be installed in order to use the loaded bitstream(e.g. insmod some kernel driver/git clone some remote source code, etc)

[region_uuid] This value specifies the type of region that is required to load this bitstream. This type is a uuid generated during the shell bitstream synthesis.

[function_uuid] This value specifies the type of function for this bitstream. It helps the upsteam scheduler to match traits with appropriate bitstream.

[topology] This field describes the topology of function structures after the bitstream is loaded on the FPGA. In particular, it uses JSON format to visualize how physical functions, virtual functions are co-related to each other. It is vendor driver’s responsibility to interpret this and prepare the porper report for Cyborg Agent. For instance:

{
  "pf_num": 2,
  "vf_num": 2,
  "pf": [
    {
      "name": "pf_1",
      "capability": "",
      "kpi": "",
      "pci_offset": "0",
      "vf": [
        {
          "name": "vf_1",
          "pci_offset": "1"
        }
      ]
    },
    {
      "name": "pf_2",
      "capability": "",
      "kpi": "",
      "pci_offset": "2",
      "vf": [
        {
          "name": "vf_2",
          "pci_offset": "3"
        }
      ]
    }
  ]
}

This JSON template guides Cyborg Agent to populate vf/pf/deployable list in Cyborg.

Given the above JSON topology, Cyborg Driver should be able to interpret the accelerator structure as follows:

              =============
              =Accelerator=
              =============
                    |
              ============
              =Deployable=
              ============
                   /\
                  /  \
===================  ===================
= Deployable pf_1 =  = Deployable pf_2 =
===================  ===================
               |        |
               |        |
===================  ===================
= Deployable vf_1 =  = Deployable vf_2 =
===================  ===================

Noted: 1. Topology is not mandatory to fill in, as long as vendor driver can figure out what resources to report after the bitstream is loaded. 2. The JSON provided here is only a reference template. It does not have to be PCI-centric etc. and up to vendors how to define it for their products. 3. A root deployable shouldbe created in the graph. In addition, the pfs and vfs here are all instances of deployable. Please refer to the DB objects specs regarding physical_function and virtual_function.

Finnally, all of the FPGA bitstreams should be TAGGED as “FPGA” in Glance. This helps distinguishing between normal VM images and bitstream images during filtering.

Implementation¶

Dependencies¶

Testing¶

Documentation Impact¶

None

References¶

None

History¶