FPGA attestation for Azure NP-Series VMs (Preview)

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets ✔️ Uniform scale sets

The FPGA Attestation service performs a series of validations on a design checkpoint file (called a “netlist”) generated by the Xilinx toolset and produces a file that contains the validated image (called a “bitstream”) that can be loaded onto the Xilinx U250 FPGA card in an NP series VM.

News

The current attestation service is using Vitis 2021.1 from Xilinx, on Sept 26th 2022, we’ll be moving to Vitis 2022.1. The change should be transparent to most users. Once your designs are “attested” using Vitis 2022.1, you should be moving to XRT2022.1. Xilinx published new marketplace images based on XRT 2022.1. Please note that current designs already attested on Vitis 2020.2 or 2021.1, works on the current deployment marketplace images and new images based on XRT2022.1

As part of the move to 2021.1, Xilinx introduced a new DRC that might affect some designs previously working on Vitis 2020.2 regarding BUFCE_LEAF failing attestation, for more details here: Xilinx AR 75980 UltraScale/UltraScale+ BRAM: CLOCK_DOMAIN = Common Mode skew checks.

Prerequisites

You need an Azure subscription and an Azure Storage account. The subscription gives you access to Azure and the storage account is used to hold your netlist and output files of the attestation service.

We provide PowerShell and Bash scripts to submit attestation requests. The scripts use Azure CLI, which can run on Windows and Linux. PowerShell can run on Windows, Linux, and macOS.

Azure CLI download (required)

PowerShell for Windows, Linux, and macOS download (only for PowerShell scripts)

You need to have your tenant and subscription ID authorized to submit to the attestation service. Visit https://aka.ms/AzureFPGAAttestationPreview to request access.

Building your design for attestation

The preferred Xilinx toolset for building designs is Vitis 2022.1. Netlist files that were created with an earlier version of the toolset and are still compatible with 2022.1 can be used. Ensure you've loaded the correct shell to build against. The currently supported version is xilinx_u250_gen3x16_xdma_2_1_202010_1. The support files can be downloaded from the Xilinx Alveo lounge.

You must include the following argument to Vitis (v++ cmd line) to build an xclbin file that contains a netlist instead of a bitstream.

--advanced.param compiler.acceleratorBinaryContent=dcp

Logging into Azure

Before performing any operations with Azure, you must log into Azure and set the subscription that is authorized to call the service. Use the az login and az account set –s <Sub ID or Name> commands for this purpose. Further information about this process is documented here: Sign in with Azure CLI. Use either the sign in interactively or sign in with credentials option on the command line.

Creating a storage account and blob container

Your netlist file must be uploaded to an Azure storage blob container for access by the attestation service.

For more information on creating the account, a container, and uploading your netlist as a blob to that container, see Quickstart: Create, download, and list blobs with Azure CLI.

You can also use the Azure portal for this as well.

Upload your netlist file to Azure blob storage

There are several ways to copy the file; an example using the az storage upload cmdlet is shown below. The az commands run on both Linux and Windows. You can choose any name for the "blob" name but make sure to retain the xclbin extension.

az storage blob upload --account-name <storage account to receive netlist> --container-name <blob container name> --name <blob filename> --file <local file with netlist>

Running the attestation scripts

To run the scripts, you will need to provide the name of your storage account, the name of the blob container where the netlist file is stored and the name of the netlist file. Also, you need to create a Service shared access signature (SAS) that grants read/write access to your container (not the netlist). This SAS is used by the attestation service to make a local copy of your netlist file and to write back the resulting output files of the validation process to your container.

An overview of shared access signatures is available here with specific information about the Service SAS available here. The Service SAS page includes an important caution about protecting the generated SAS. Read the caution to understand the need to keep the SAS protected from malicious or unintended use.

You can generate a SAS for your container using the az storage container generate-sas cmdlet. Specify an expiry time in UTC format that is at least a few hours past the time of submission; around 6 hours should be more than adequate.

If you wish to use virtual directories, you must include the directory hierarchy as part of the container argument. For example, if you have a container named “netlists” and have a virtual directory named “image1” that contains the netlist blob, you would specify “netlists/image1” as the container name. Add any extra directory names to specify a more detailed hierarchy.

PowerShell

$sas=$(az storage container generate-sas --account-name <storage acct name> --name <blob container name> --https-only --permissions rwc --expiry <e.g., 2021-01-07T17:00Z> --output tsv)

.\Validate-FPGAImage.ps1 -StorageAccountName <storage acct name> -Container <blob container name> -BlobContainerSAS $sas -NetlistName <netlist blob filename>

Bash

sas=az storage container generate-sas --account-name <storage acct name> --name <blob container name> --https-only --permissions rwc --expiry <2021-01-07T17:00Z> --output tsv  

validate-fpgaimage.sh --storage-account <storage acct name> --container <blob container name> --netlist-name <netlist blob filename> --blob-container-sas $sas

Checking on the status of your submission

The Attestation service will return the orchestration ID of your submission. The submission scripts automatically start monitoring the submission by polling for completion. The orchestration ID is the primary way for us to review what happened to your submission so please keep that in case you have an issue. As reference points, attestation takes about 30 minutes to complete for a small netlist file (300MB in size); a 1.6GB file took an hour.

You can call the Monitor-Validation.ps1 script at any time to get status and results of attestation, providing the orchestration ID as an argument:

.\Monitor-Validation.ps1 -OrchestrationId <orchestration ID>

Alternatively, you can submit HTTP post request to the attestation service endpoint:

https://fpga-attestation.azurewebsites.net/api/ComputeFPGA_HttpGetStatus

The request body should contain your Subscription ID, Tenant ID, and orchestration ID of your attestation request:

{  
  "OrchestrationId": "<orchestration ID>",  
  "ClientSubscriptionId": "<your subscription ID>",  
  "ClientTenantId": "<your tenant ID>"
}

Post validation steps

The service will write its output back to your container. If the validation pass succeeds, your container will have the original netlist file (abc.xclbin), a file with the bitstream (abc.bit.xclbin), a file that identifies the private location of your stored bitstream (abc.azure.xclbin) and four log files: one for the startup process (abc-log.txt) and one each for the three parallel phases that perform the validation. These are named *logPhaseX.txt where X is a number for the phase. The azure.xclbin is used on your VM to signal the uploading of your validated image to the U250.

If validation failed, an error-*.txt file is written indicating which step failed. Also check the log files if the error log indicates that attestation failed. When contacting us for support, please be sure to include all these files as part of the support request along with the orchestration ID.

You can use the Azure portal to create your container as well as uploading your netlist and downloading the bitstream and log files. Submitting an attestation request and monitoring its progress through the portal is not supported at this time and must be done through scripts as described above.