Browse Source

Added bitstream metadata standardization spec

Change-Id: I14cfd85e946be1a8a653f14b3ae3b8421c01544c
Li Liu 3 years ago
1 changed files with 221 additions and 0 deletions
  1. +221

+ 221
- 0
doc/specs/rocky/cyborg-fpga-bitstream-spec.rst View File

@ -0,0 +1,221 @@
This work is licensed under a Creative Commons Attribution 3.0 Unported
Cyborg FPGA Bitstream metadata spec
Blueprint url:
This spec proposes the FPGA Bitstream metadata specifications for bitstream
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.
Use Cases
When user requests to reprogram a FPGA board with certain functionality in the
cloud environment, he or she will need to retrieve a suitable bitstream from the
storage. In order to find the suitable one, bitstreams need to be categorized
based on some properties defined in metadata.
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::
| name | value(example) | nullable | description |
| bs-name | aes-128 | False | name of the bitstream(not unique) |
| bs-uuid | {uuid} | False | The uuid generated during synthesis |
| vendor | Xilinx | False | Vendor of the card |
| board | KU115 | False | Board type for this bitstream to load |
| shell_id | {uuid} | True | Required shell bs-uuid for this bitstream|
| version | 1.0 | False | Device version number |
| driver | SDX | True | Type of driver for this bitstream |
| driver_ver | 1.0 | False | Driver version |
| driver_path | /path/to/driver| False | Where to retrieve the driver binary |
| topology | {CLOB} | False | Function Topology |
| description | description | True | Description |
Here are the details regarding some definded keys.
This field is a uuid pointing to the required shell image uuid for loading this
pr bitstream. If it is null, this bitstream is a shell bitstream.
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)
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::
/ \
=================== ===================
= 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
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.
Data model impact
RPC API impact
REST API impact
Security impact
Notifications impact
Other end user impact
Performance Impact
Other deployer impact
Developer impact
Accelerator vendors should implement the logic in program() api to populate the loaded
Primary assignee:
Li Liu <>
Shaohe Feng <>
Work Items
* Provide example JSON format for bitstream
* Provide example implementation of vendor driver
Documentation Impact
.. list-table:: Revisions
:header-rows: 1