How do I use faascmd? - FPGA as a Service - Alibaba Cloud Documentation Center

This topic describes how to use faascmd.

Prerequisites

faascmd is configured. For more information, see Configure faascmd.
An Object Storage Service (OSS) bucket is created for FPGA as a Service (FaaS) to upload compiled design checkpoint (DCP) files. For more information, see Create buckets.
A directory named compiling_logs/ is created in the OSS bucket. For more information, see Create a directory.

faascmd command overview

Usage notes

All commands and parameters provided by faascmd are case-sensitive.
In faascmd commands, no spaces are allowed between parameters, equal signs (=), and values.

faascmd commands

The commands supported by faascmd are mainly used to manage permissions, configure environments, and manage FPGA images. The following table describes the supported features.

Feature	References
Manage permissions	Grant permissions to a RAM user Query an authorization policy Delete an authorization policy
Configure environments	Query all objects in an OSS bucket Upload a compiled file Download an object from an OSS bucket Query FPGA-accelerated instances
Manage FPGA images	Create an FPGA image Query FPGA images Delete an FPGA image Download an FPGA image Query the download progress of an FPGA image Publish an FPGA image

Grant permissions to a RAM user

You can run the faascmd auth command to authorize a Resource Access Management (RAM) user to access your OSS bucket as an FaaS administrator.

Command syntax

faascmd auth --bucket=<YourFaasOSSBucketName>

Sample code

Note

If your Alibaba Cloud account has multiple RAM users, we recommend that the RAM users share an OSS bucket. This way, you do not need to repeatedly modify or overwrite authorization policies.

Query an authorization policy

You can run the faascmd list_policy command to check whether the specified OSS bucket is added to the authorization policy named faasPolicy.

Command syntax

faascmd list_policy

Sample code 查看授权策略

Note

Check whether your OSS bucket and the compiling_logs/ directory in the OSS bucket are displayed in the returned policy information.

Delete an authorization policy

You can run the faascmd delete_policy command to delete the authorization policy named faasPolicy that you no longer need.

Command syntax

faascmd delete_policy

Sample code 删除授权策略

Note

If your Alibaba Cloud account has multiple RAM users, we recommend that you perform this operation in the RAM console. This helps prevent policies from being accidentally deleted.

Query all objects in an OSS bucket

You can run the faascmd list_objects command to query all objects in an OSS bucket.

Command syntax

faascmd list_objects

Sample code 查看objects

Note

You can use this command and the grep command together to filter objects. Example: faascmd list_objects | grep "xxx".

Upload a compiled file

You can run the faascmd upload_object command to upload original copies of files compiled on your computer to the specified OSS bucket.

Command syntax

faascmd upload_object --object=<NewFileNameInOSSBucket> --file=<YourFilePath>/<FileNameYouWantToUpload>

Sample code upload_object

Note

If the file to be uploaded is stored in the current directory, you do not need to specify a path.
Locally compiled original files provided by Intel FPGA are in the .gbs format and those provided by Xilinx FPGA are compressed as packages in the .tar format after script processing.

Download an object from an OSS bucket

You can run the faascmd get_object command to download an object from an OSS bucket.

Command syntax

faascmd get_object --object=<YourObjectName> --file=<YourLocalPath>/<YourFileName>

Sample code get_object

Note

If you do not specify a path, the object is downloaded to the current directory.

Create an FPGA image

You can run the faascmd create_image command to submit a request to create an FPGA image. If the request succeeds, FpgaImageUUID is returned.

Command syntax

faascmd create_image --object=<YourObjectName> 
--fpgatype=<intel/xilinx>  --encrypted=<true/false> 
--kmskey=<key/This parameter is required if the encrypted parameter is set to true. Otherwise, this parameter is optional.> 
--shell=<Shell Version/Required> --name=<name/Optional> 
--description=<description/Optional> --tags=<tags/Optional>

Sample code create_image

Query FPGA images

You can run the faascmd list_images command to query the information about all FPGA images that you created.

Command syntax

faascmd list_images

Sample code list_images

Note

Each RAM user can have up to 10 FPGA images.

Delete an FPGA image

You can run the faascmd delete_image command to delete an FPGA image that you no longer need.

Command syntax

faascmd delete_image --imageuuid=<yourImageuuid>

Sample code delete_image

Download an FPGA image

You can run the faascmd download_image command to submit a request to download an FPGA image.

Command syntax

faascmd download_image  --instanceId=<YourInstanceId> 
--fpgauuid=<Yourfpgauuid> --fpgatype=<intel/xilinx> 
--imageuuid=<YourImageuuid> --imagetype=<afu> 
--shell=<YourImageShellVersion>

Sample code

faascmd download_image --instanceId=XXXXX --fpgauuid=XXXX --fpgatype=intel --imageuuid=XXXX

Query the download progress of an FPGA image

You can run the faascmd fpga_status command to query the status of the current FPGA or the download progress of an FPGA image.

Command syntax

faascmd fpga_status --fpgauuid=<Yourfpgauuid> --instanceId=<YourInstanceId>

Sample code fpga_status

Publish an FPGA image

You can run the faascmd publish_image command to submit a request to publish an FPGA image.

Command syntax

faascmd publish_image --imageuuid=<YourImageuuid> --imageid=<YourInstanceImageid>

Note

Set the imageuuid parameter to the ID of the FPGA image that you want to publish to Alibaba Cloud Marketplace. You can run the faascmd list_images command to query this image ID.
Set the imageid parameter to the image ID of the current FPGA-accelerated instance. You can go to the instance details page in the ECS console to view the image ID.

Query FPGA-accelerated instances

You can run the faascmd list_instances command to query the basic information of an FPGA-accelerated instance. The information includes the instance ID, FPGA information, and shell version.

Command syntax

faascmd list_instances --instanceId=<YourInstanceId>

Sample code list_instances