The developer can build their own Custom Logic (CL) and deploy it on AWS. The CL must comply with the AWS Shell specifications, and pass through the build scripts.
The CL Examples directory is provided to assist developers in creating a functional CL implementation. Each example includes:
- The design source code for the example under the
/designdirectory. - The timing, clock and placement constraints files, scripts for compiling the example design. (This requires running in an instance/server that have Xilinx tools and license installed. Developers are recommended to use the "FPGA Development AMI" available free of charge on AWS Marketplace.
- The final build, called Design CheckPoint (DCP) that can be submitted for AWS to generate the AFI.
- An AFI-ID for a pre-generated AFI that matches the example design.
- Software source code required on the FPGA-enabled instance to run the example.
- Software binary that can be loaded on an FPGA-enabled instance to test the AFI.
In summary:
- An AFI can be created using the files in 1, 2, and 3. The AFI creation can take place on any EC2 instance or on premise.
- The AFI can be used in an EC2 F1 instance by using the files in 4, 5 and 6.
By following the example CLs, a developer should learn how to interface to the AWS Shell of the FPGA, compile the source code to create an AFI, and load an AFI from the F1 instance for use.
As a pre-requisite to building the AFI, the developer should have an instance/server with Xilinx Vivado Tools and the necessary Licenses. The "FPGA Developer AMI" provided free of charge on AWS Marketplace will be an ideal place to start an instance from. See the README.md on the AMI for the details how to launch the FPGA Developer's AMI, install the tools and set up the license.
NOTE: steps 1 through 3 can be done on any server or EC2 instance, C4/C5 instances are recommended for fastest build time
NOTE: You can skip steps 0 through 3 if you are not interested in the build process. Step 4 through 6 will show you how to use one of the predesigned AFI
$ git clone https://github.com/aws/aws-fpga
$ cd aws-fpga
$ source hdk_shell.sh
To install the AWS CLI, please follow the instructions here: (http://docs.aws.amazon.com/cli/latest/userguide/installing.html).
$ aws configure # to set your credentials (found in your console.aws.amazon.com page) and region (typically us-east-1)
NOTE: During the F1 preview, not all FPGA-specific AWS CLI commands are available to the public. To extend your AWS CLI installation, please execute the following:
$ aws configure add-model --service-model file://$(pwd)/sdk/aws-cli-preview/ec2_preview_model.json
There are couple of ways to start a new CL: one option is to copy one of the examples provided in the HDK and modify the design files, scripts and constrains directory.
Alternatively, by creating a new directory, setup the environment variables, and prepare the project datastructure:
$ cd $HDK_DIR/cl/examples/cl_hello_world # you can change cl_hello_world to any other example
$ export CL_DIR=$(pwd)
Setting up the CL_DIR environment variable is crucial as the build scripts rely on that value. Each one of the examples following the recommended directory structure to match what's expected by the HDK simulation and build scripts.
If you like to start your own CL, check out the How to create your own CL Readme
NOTE This step requires you to have Xilinx Vivado Tools and Licenses installed
$ vivado -mode batch # Run this command to see if vivado is installed
The next script two steps will go through the entire implementation process converting the CL design into a completed Design Checkpoint that meets timing and placement constrains of the target FPGA
$ cd $CL_DIR/build/scripts
$ ./aws_build_dcp_from_cl.tcl
NOTE: The DCP generation can take up to several hours to complete.
We recommend that you initiate the generation in a way that prevents interruption.
For example, if working on a remote machine, we recommend using window management tools such as screen to mitigate potential network disconnects.
To submit the DCP, create an S3 bucket for submitting the design and upload the tar-zipped archive into that bucket. You need to prepare the following information:
- Name of the logic design.
- Generic description of the logic design.
- PCI IDs: Device, Vendor, Subsystem, SubsystemVendor (these IDs should be found in the README files in the respective CL example directory).
- Location of the DCP object (S3 bucket name and key).
- Location of the directory to write logs (S3 bucket name and key).
- Version of the AWS Shell.
To upload your DCP to S3,
$ aws s3 mb s3://<bucket-name> # Create an S3 bucket (choose a unique bucket name)
$ aws s3 cp *.SH_CL_routed.dcp \ # Upload the DCP file to S3
s3://<bucket-name>/cl_simple.dcp
To generate the AFI, follow one of the two methods listed below. After the AFI generation is complete, AWS will put the logs into the bucket location provided by the developer and notify them by email.
To check whether you have access to the create-fpga-image command, simply try executing the command as follows.
If you get an "Invalid choice" error, then move to Method 2.
$ aws ec2 create-fpga-image
To create an AFI from the generated DCP, you need to upload the tar-zipped DCP file to an S3 bucket, and execute the aws ec2 create-fpga-image command as follows:
$ aws ec2 create-fpga-image \
--fpga-image-architecture xvu9p \
--shell-version <shell_version> \
--fpga-pci-id deviceId=<device_id>,vendorId=<vendor_id>,subsystemId=<subsystem_id>,subsystemVendorId=<subsystem_vendor_id> \
--input-storage-location Bucket=<bucket-name>,Key=cl_simple.dcp
--name MyCL
--logs-storage-location Bucket=<bucket-name>,Key=logs/
The output of this command includes two identifiers that refer to your AFI:
- FPGA Image Identifier or AFI ID: this is the main ID used to manage your AFI through the AWS EC2 CLI commands and AWS SDK APIs.
This ID is regional, i.e., if an AFI is copied across multiple regions, it will have a different unique AFI ID in each region.
An example AFI ID is
afi-01234567890abcdef. - Glogal FPGA Image Identifier or AGFI ID: this is a global ID that is used to refer to an AFI from within an F1 instance.
For example, to load or clear an AFI from an FPGA slot, you use the AGFI ID.
Since the AGFI IDs is global (by design), it allows you to copy a combination of AFI/AMI to multiple regions, and they will work without requiring any extra setup.
An example AGFI ID is
agfi-01234567890abcdef.
Add a policy to the created S3 bucket granting read/write permissions to our team's account (Account ID: 371834676912). A sample policy is shown below.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Bucket level permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::371834676912:root"
},
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::<bucket_name>"
},
{
"Sid": "Object read permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::371834676912:root"
},
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::<dcp_bucket_name>/<dcp_filename>"
},
{
"Sid": "Folder write permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::371834676912:root"
},
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::<log_bucket_name>/*"
}
]
}
Then, send an email to AWS (email TBD) providing the information listed earlier (numbered 1-6), in addition to your AWS Account ID number.
To follow the next steps, you have to run an instance on F1. AWS recommends that you run an instance with latest Amazon Linux that has the FPGA management tools included, or alternatively the FPGA Developer AMI with both the HDK and SDK.
Execute the following:
$ git clone https://github.com/aws/aws-fpga # Not needed if you have installed the HDK as in Step 0.
$ cd aws-fpga
$ source sdk_setup.sh
-
To start using the AFI, you need to associate it with an AMI (Amazon Machine Image) that you own.
-
Association means that any instance launched using this AMI will be able to load the AFIs to FPGAs as described in the next section.
-
You can associate multiple AFIs with your AMI.
-
There is a default limit of eight AFIs per AMI, if you need more, please reach out to AWS with your use case and we can adjust your limit.
-
FPGA Developer AMI's are owned by AWS and you can not associate your AFI with them.
- If you are developing using the FPGA Developer AMI's, just create a new image of your instance after you are done developing and that will create an AMI of your instance that you own. $ aws create-image --instance-id --name
- This will create a new AMI of the current state of your instance and you would be able to associate an AFI with this AMI.
- You would have to start your F1 Instance with this new image as that load commands would only work on associated AMI's
-
To associate, simply invoke the following AWS EC2 CLI command.
$ aws ec2 associate-fpga-image --fpga-image-id <AFI_ID> --image-id <AMI_ID>
NOTE: The AWS CLI commands use the AFI ID (not the AGFI ID).
Run the fpga-describe-local-image on slot 0 to confirm that the FPGA is cleared, and you should see similar output to the 4 lines below:
$ sudo fpga-describe-local-image -S 0 -H
Type FpgaImageSlot FpgaImageId StatusName StatusCode
AFI 0 none cleared 1
Type VendorId DeviceId DBDF
AFIDEVICE 0x1d0f 0x1042 0000:00:17.0
Then loading the example AFI to FPGA slot 0 (you should have the AGFI ID from Step 3 above):
$ sudo fpga-load-local-image -S 0 -I <AGFI_ID>
NOTE: The FPGA Management tools use the AGFI ID (not the AFI ID).
Now, you can verify the status of the previous load command:
$ sudo fpga-describe-local-image -S 0 -H