How to use faasutil - FPGA as a Service - Alibaba Cloud Documentation Center

This topic describes faasutil commands, and provides examples on how to use these commands.

Prerequisites

faasutil is obtained. For more information, see Obtain faasutil.
A raw file is available. The raw file is the acceleration program that you developed for field programmable gate array (FPGA) devices and is used to compile and generate FPGA images.
An Object Storage Service (OSS) bucket is created. The OSS bucket is used to upload raw files. For more information, see Create buckets.
An AccessKey pair is created for a Resource Access Management (RAM) user. For more information, see Create an AccessKey pair.
Warning
You can only access FPGA as a Service (FaaS) by using the AccessKey pair as a RAM user. This minimizes the risk of leaking the AccessKey pair. We recommend that you do not save your AccessKey pair in plaintext in the code of your project and keep your AccessKey pair confidential. Otherwise, the AccessKey pair may be leaked and the security of resources that belong to your account may be compromised.

Terms

The following table describes the main terms mentioned in this topic.

Term	Description
FPGA-accelerated instance	You can create an FPGA-accelerated instance in the Alibaba Cloud Management Console or by calling API operations. FPGA-accelerated instances include computing resources, Elastic Compute Service (ECS) images, and disks.
ECS image	The ECS image used by an FPGA-accelerated instance. FPGA-accelerated instances provide FPGA acceleration capabilities and the same user experience as regular ECS instances.
raw file	The acceleration program that you developed for FPGA devices and is used to compile and generate FPGA images. For example, the raw file of an Intel FPGA is in the .gbs format. The raw file of a Xilinx FPGA is a TAR package that is generated from processed scripts.
FPGA image	The image used by an FPGA device. A raw file is compiled to generate an FPGA image. After you load the FPGA image to an FPGA device, the FPGA device can provide acceleration services based on your design. Note Each FPGA image has a UUID.

Usage notes

When you use faasutil, take note of the following items:

Use the following method to run faasutil commands: ./faasutil [command].
faasutil commands and their parameters are case-sensitive.
For example, an error occurs if you run the ./faasutil Create_Image --Object=faasutiltest-forcompiling.tar.gz --Shell=f30010 --FPGAType=xilinx --Name=faasutiltest-image command. The command and its parameters must be spelled in the same way as they are defined.
Make sure that no space exists between each pair of parameter name, equal sign (=), and parameter value.
For example, an error occurs if you run the ./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell = f30010 --fpgatype=xilinx --name=faasutiltest-image command. You must remove the spaces before and after the equal sign (=) next to the shell parameter.
If you want to perform operations as a regular user, contact an administrator and apply for the permissions to use the /dev/virtio-ports/FaaS.agent directory.

faasutil commands

You can run commands provided by faasutil to obtain the help information, configure the environment, and manage FPGA images. The following table describes the operations.

View all commands

View the faasutil version and all faasutil commands.

Command syntax

faasutil --help
faasutil -h

Sample code

[user1@i**** ~]# ./faasutil -h
faasutil [command] [optons]...
  DESCRIPTION
    faasutil is a fpga image management tool.
    version : 2.0.3a
    date    : 2020-07-08-11:04
  command list(use "faasutil [command] --help" for more infomation):
    config                  Config faasutil enviroment.
    list_instances          Print the instances base infomation.
    fpga_status             Check pointed fpga status.
    auth                    Authorize FAAS to read the oss bucket your specified.
    list_objects            List objects of the bucket you specified.
    put_object              Put local file to the bucket object, FAAS need download it from oss.
    get_object              Get object from oss bucket.
    list_policy             List the detailed information about oss policy authorize to FAAS.
    delete_policy           Delete the oss policy authorize to FAAS.
    list_images             List the fpga images
    create_image            Create fpga image.
    modify_image            Modify fpga image.
    delete_image            Delete fpga image.
    bind_image              Bind the FPGA image to ECS image.
    download_image          Download FPGA image to faas instance.
    download_status         The status of download image operation.
    copy_fpga_image         Copying images across regions.
    query_log               Get compiler log.

View specified commands

View the description of the specified commands and their parameters.

Command syntax

faasutil [command name] --help
faasutil [command name] -h

Sample code

[user1@i**** ~]# ./faasutil config --help
  COMMAND
    config
  SYNOPSIS
    config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]
  DESCRIPTION
    Config faasutil enviroment.
    /*Using config to save the value of these follow options.*/
    /*You can also set these options' value follow any command which need to specify.*/
  OPTIONS
    required
    --id
        User access id , using config to save this information.
    --key
        User access key, using config to save this information.
    optional
    --token
        User ststoken  , using config to save this information.
    --bucket
        Bucket used for upload image.
    --regionId
        The region of pop endpoint and oss endpoint.
        Default using ecs region of public network.
    --ossEndpoint
        Oss endpoint info.
        Specify the oss endpoint if you want to get/put files in different region or vpc network.
    --popEndpoint
        Pop endpoint info.
    --instanceId
        ECS instance ID.
        Default using the local ECS ID.
    --ecsImageId
        ECS image ID.
        Default using the image ID of the local ECS ID.
    --shell
        Specify the shell version you used.
        Default using the shell version of the ECS fpga card.
    --fpgatype
        Specify the FPGA device type.
        Default using the FPGA device type of belong to the local ECS.

Configure user information

Write user information to the default configuration file. The following table describes the parameters for configuring user information.

Information item	Description
AccessKey ID	Required. An AccessKey pair is used for authentication.
AccessKey secret	Required. An AccessKey pair is used for authentication.
OSS bucket name	The name of the OSS bucket to which raw files are uploaded. We recommend that you specify this parameter. This way, you do not need to enter the OSS bucket name when you run commands that require this parameter.

Command syntax

Note

You can run the config command to view the information that can be configured.

faasutil config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]

The following table describes the parameters in the command syntax.

Parameter	Description
`token`	The Security Token Service (STS) token. This parameter is compatible with the previous features of faascmd. We recommend that you do not specify this parameter.
`regionId`	The ID of the region in which the ECS instance resides. The value of this parameter is automatically generated from the ECS instance. You do not need to specify this parameter.
`ossEndpoint`	The endpoint of the OSS bucket. The value of this parameter is automatically generated from the ECS instance. You do not need to specify this parameter.
`popEndpoint`	The endpoint of the point of presence (POP). The value of this parameter is automatically generated from the ECS instance. You do not need to specify this parameter.

Sample code

[user1@i**** ~]# ./faasutil config --id=L**** --key=v**** --bucket=yk****
Your configuration is saved into /home/user1/.faascredentials.
1.057(s) elapsed

Grant the read permissions on OSS buckets

Grant the read permissions on OSS buckets to FPGA-accelerated instances to read files from OSS buckets.

Command syntax

faasutil auth

Sample code

[user1@i**** ~]# ./faasutil auth
{
  "Statement": [
    {
      "Action": [
        "oss:GetObject",
        "oss:GetObjectMeta",
        "oss:ListObjects"
      ],
      "Effect": "Allow",
      "Principal": [
        "26143530338319****"
      ],
      "Resource": [
        "acs:oss:*:*:yk****/*"
      ]
    }
  ],
  "Version": "1"
}

0.223(s) elapsed

View the read permissions on OSS buckets

View the read permissions on OSS buckets that are granted to FPGA-accelerated instances.

Command syntax

faasutil list_policy

Sample code

[user1@i**** ~]# ./faasutil list_policy
Get policy text:
{
  "Statement": [
    {
      "Action": [
        "oss:GetObject",
        "oss:GetObjectMeta",
        "oss:ListObjects"
      ],
      "Effect": "Allow",
      "Principal": [
        "26143530338319****"
      ],
      "Resource": [
        "acs:oss:*:*:yk****/*"
      ]
    }
  ],
  "Version": "1"
}
0.203(s) elapsed

Remove the read permissions on OSS buckets

Remove the read permissions on OSS buckets from FPGA-accelerated instances to prevent the FPGA-accelerated instances from reading files from OSS buckets.

Command syntax

faasutil delete_policy

Sample code

[user1@i**** ~]# ./faasutil delete_policy
0.210(s) elapsed

Query the information about FPGA-accelerated instances

Query the information about FPGA-accelerated instances, such as instance IDs, ECS images, and FPGA devices that are attached to FPGA-accelerated instances.

Command syntax

faasutil list_instances

Sample code

In this example, two FPGA devices are attached to an FPGA-accelerated instance. The fpga bdf parameter of the FPGA devices is set to 00:09.0 and 00:08.0, respectively.

[user1@i**** ~]# ./faasutil list_instances
instance_id          : i-uf616ov8zzwmiijb****
image_id             : centos_7_8_x64_20G_alibase_20200914.vhd
regionId             : cn-shanghai
fpga bdf             : ['00:09.0', '00:08.0']
shell version        : f30010
requestId            : x-7762368991973****
fpga type            : xilinx
1.054(s) elapsed

Query the status of an FPGA device

Query the status of an FPGA device based on the bdf value of the FPGA device. You can run the list_instances command to view the value of the bdf parameter of an FPGA device. For more information, see the Query the information about FPGA-accelerated instances section of this topic.

Command syntax

faasutil fpga_status --bdf=[bdf]

Note

Replace [bdf] in the command with the bdf value of the FPGA device. For example, replace [bdf] with 00:09.0.

Sample code

The following sample code provides an example on how to query the status of an FPGA device whose bdf value is set to 00:09.0.

The imageuuid parameter indicates the UUID of the specified FPGA image. For a newly purchased FPGA-accelerated instance, the value of the imageuuid parameter is NULL.

[user1@i**** ~]# ./faasutil fpga_status --bdf=00:09.0
clock0               : 240
clock1               : 189
fpgaStatus           : valid
requestId            : x-1093970844245****
shellUUID            : f30010
imageuuid            : NULL
firewall             : ['mgmt : GOOD', 'user : GOOD', 'xdma : GOOD', 'dma : GOOD']
ddr                  : ['ddr0 : online', 'ddr1 : online', 'ddr2 : online', 'ddr3 : online']
message              : FPGA is working.
1.025(s) elapsed

Upload files to an OSS bucket

Upload files such as raw files on an FPGA-accelerated instance to an OSS bucket.

Command syntax

faasutil put_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]

The following table describes the parameters in the command syntax.

[bucket_name]: the name of the OSS bucket.
Note
If you have run the config command to specify an OSS bucket in the default configuration file, you do not need to specify the bucket parameter.
[file_name]: the name of the file to be uploaded.
[object_name]: the display name of the uploaded file in the OSS bucket.

Sample code

[user1@i**** ~]# ./faasutil put_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest.tar.gz
100%

539.171(s) elapsed

View files in an OSS bucket

View files in an OSS bucket.

Command syntax

faasutil list_objects

Sample code

[user1@i**** ~]# ./faasutil list_objects
faasutiltest-forcompiling.tar.gz
0.288(s) elapsed

Download files to an FPGA-accelerated instance

Download files from an OSS bucket to an FPGA-accelerated instance.

Command syntax

faasutil get_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]

The following table describes the parameters in the command syntax.

[bucket_name]: the name of the OSS bucket.
Note
If you have run the config command to specify an OSS bucket in the default configuration file, you do not need to specify the bucket parameter.
[file_name]: the name of the file to be downloaded.
[object_name]: the display name of the downloaded file in the FPGA-accelerated instance.

Sample code

[user1@i**** ~]# ./faasutil get_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest-fordeveloping.tar.gz
100%

179.909(s) elapsed

Create tasks to compile FPGA images

Use raw files to compile and generate FPGA images.

Note

Compilation takes a period of time. Wait until the compilation is complete. If you have already created a compilation task, you must wait at least 30 minutes before you can create another compilation task, regardless of whether the compilation task is successful.

Command syntax

faasutil create_image --object=[object_name] --shell=[shell_ver] --fpgatype=[fpga_type]

The following table describes the parameters in the command syntax.

[object_name]: the name of the raw file used for compilation. Make sure that the raw file has been uploaded to the OSS bucket.
[shell_ver]: the shell version of the FPGA device. You can run the fpga_status command to view the shell version of the FPGA device. For more information, see the Query the status of an FPGA device section of this topic.
[fpga_type]: the type of the FPGA device. Xilinx FPGAs (xilinx) and Intel FPGAs (intel) are supported. Specify this parameter based on the type of your FPGA device.

Sample code

[user1@i**** ~]# ./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell=f30010 --fpgatype=xilinx --name=faasutiltest-image
{
  "CreateTime": "2020-12-04 14:48:13",
  "Description": "",
  "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
  "Name": "faasutiltest-image",
  "RequestId": "2E996CE5-F550-43E7-8016-DAF0D32A96BF",
  "ShellUniqueId": "f30010",
  "State": "queueing"
}
0.555(s) elapsed

This example shows that the FpgaImageUniqueId and State parameters are returned for an FPGA image after an FPGA image compilation task is created.

In this example, the value of the State parameter is queueing, which indicates that the task is waiting for compilation. You can run the list_images command and view the status of the task corresponding to the returned FpgaImageUniqueId value. For more information, see the View FPGA images section of this topic.
If the value of the State parameter becomes success, the compilation task is successful.

Query compilation logs

Query the logs generated when the specified FPGA image compilation task is executed. The [fpgaImageUniqueId] parameter specifies the UUID of an FPGA image returned after an FPGA image compilation task is created.

Command syntax

faasutil query_log --fpgaImageUniqueId=[fpgaImageUniqueId]

Sample code

[user1@i**** ~]# ./faasutil query_log --fpgaImageUniqueId=xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****
{
  "Log": "http://aliyun-faas-images-cn-shanghai.oss-cn-shanghai-internal.aliyuncs.com/27095692903785****%2Fxilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****_log?Expires=160706****&OSSAccessKeyId=L****&Signature=1****",
  "RequestId": "07A744F5-422D-49AA-B69B-1AD898BBD1D8"
}
0.194(s) elapsed

In this example, a URL is displayed in the command output. You can access the URL to obtain logs. Sample URL: http://aliyun-faas-images****-internal.aliyuncs****&Signature=1****.

Note

If you do not want to view logs in an FPGA-accelerated instance, remove -internal from the URL.

View FPGA images

View existing FPGA images. You can filter images by image owner. The [owner] parameter specifies the image owner. Alibaba Cloud Marketplace images (market) and local images (self) are supported.

Command syntax

faasutil list_images --owneralias=[owner]

Sample code

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [
    {
      "CreateTime": "2020-12-04 14:48:14",
      "Description": "faasutil test round 1",
      "Encryption": false,
      "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
      "Name": "faasutiltest-image",
      "OwnerId": "27095692903785****",
      "ShellUniqueId": "f30010",
      "State": "success",
      "Tags": "",
      "UpdateTime": "2020-12-04 15:02:05"
    }
  ],
  "RequestId": "C85DD548-9B3D-463E-BE25-316FF7288CEB"
}
0.087(s) elapsed

Modify the information about an FPGA image

Modify the information about an existing FPGA image, such as the name and description.

Command syntax

faasutil modify_image --fpgaImageUniqueId=[fpgaImageUniqueId] --name=[name] --description=[description] --tags=[tags]

Sample code

[user1@i**** ~]# ./faasutil modify_image --fpgaImageUniqueId=xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b*** --name="faasutiltest-image" --description="faasutil test round 2"
{
  "Description": "faasutil test round 2",
  "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
  "Name": "faasutiltest-image",
  "RequestId": "AED50829-B84A-42F9-9891-E1EE9821DA33",
  "Tags": ""
}

View the modified information

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [
    {
      "CreateTime": "2020-12-04 14:48:14",
      "Description": "faasutil test round 2",
      "Encryption": false,
      "FpgaImageUniqueId": "xilinxb80832c9-1cd1-49a2-a7b4-7d3a5a4b****",
      "Name": "faasutiltest-image",
      "OwnerId": "27095692903785****",
      "ShellUniqueId": "f30010",
      "State": "success",
      "Tags": "",
      "UpdateTime": "2020-12-04 15:02:05"
    }
  ],
  "RequestId": "C85DD548-9B3D-463E-BE25-316FF7288CEB"
}
0.087(s) elapsed

Associate FPGA images with ECS images

After you associate FPGA images with ECS images, you can publish the ECS images to Alibaba Cloud Marketplace. When your ECS images are used by another user, the user can also use the FPFA images associated with the ECS images.

Command syntax

faasutil bind_image --fpgaImageUniqueId=[fpgaImageUniqueId] --ecsImageId=[ecsImageId]

[fpgaImageUniqueId]: the UUID of the FPGA image.
[ecsImageId]: the ID of the ECS image. By default, the ID of the ECS image on the current FPGA-accelerated instance is used.

Sample code

[user1@i**** ~]# ./faasutil bind_image --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
{
  "FpgaImageUniqueId": "xilinx5395ad11-edb9-4d93-964d-12c59a07****",
  "ImageId": "",
  "Message": "publish succeed!",
  "RequestId": "966883DD-6A6F-456A-8894-8FB7FA8A321C"
}
0.119(s) elapsed

Copy FPGA images across regions

If you want to use an existing FPGA image in a new region, you do not need to create a new image compilation task in this region. You can copy the existing FPGA image to this region.

Command syntax

faasutil copy_fpga_image --fpgaImageUniqueId=[fpgaImageUniqueId] --targetRegion=[target region id]

Sample code

[user1@i**** ~]# ./faasutil copy_fpga_image --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07**** --targetRegion=cn-hangzhou
{
  "CreateTime": "2020-12-04 17:46:04",
  "Description": "",
  "FpgaImageUniqueId": "xilinx5395ad11-edb9-4d93-964d-12c59a07****",
  "Name": "faasutiltest-image",
  "RequestId": "3AAEC35C-2FB2-4DBA-A982-7A8219055D60",
  "ShellUniqueId": "f30010",
  "State": "committed"
}
0.309(s) elapsed

Load FPGA images

Load FPGA images to FPGA devices. You can run the list_instances command to view the ID of an FPGA-accelerated instance and the bdf value of an FPGA device. You can run the list_images command to view the UUID of an FPGA image.

Command syntax

faasutil download_image --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --instanceId=[instanceId] --owneralias=[owner]

Sample code

[user1@i**** ~]# ./faasutil download_image --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
{"TaskId":45331,"RequestId":"073431C2-857A-470D-9543-D1D89FC10D54","FpgaImageUniqueId":"xilinx5395ad11-edb9-4d93-964d-12c59a07****","InstanceId":"i-uf616ov8zzwmiijb****","BDFInECS":"","TaskStatus":"committed"}
status               : operating
info                 : download task is operating
requestId            : x-84128618168241720
1.165(s) elapsed

Query the loading status of FPGA images

Query the loading status of FPGA images on FPGA devices. You can run the list_instances command to view the bdf value of an FPGA device or run the list_images command to view the UUID of an FPGA image.

Command syntax

faasutil download_status --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]

Sample code

[user1@iZ**** ~]# ./faasutil download_status --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
status               : done
info                 : download task finish
requestId            : x-42850294908763910
time                 : 2020-12-04 17:50:48
1.026(s) elapsed

Delete FPGA images

Delete FPGA images that are no longer needed.

Note

If the FPGA images have been published to Alibaba Cloud Marketplace, you must specify the --owneralias=market parameter.

Command syntax

faasutil delete_image --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]

Sample code

[user1@i**** ~]# ./faasutil delete_image --fpgaImageUniqueId=xilinxe27832a0-7c1c-4d6d-80b8-435253e9****
{
  "FpgaImageUniqueId": "xilinxe27832a0-7c1c-4d6d-80b8-435253e9****",
  "RequestId": "F2F481F5-B0E3-4009-9AF4-CF4BFC00458A"
}
0.157(s) elapsed

View the deletion result

[user1@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [],
  "RequestId": "30B73A5B-99FC-4920-8B90-4BA08A075040"
}
0.049(s) elapsed

Operation	References
Obtain help information	View all commands View specified commands
Configure the environment	Configure user information Grant the read permissions on OSS buckets View the read permissions on OSS buckets Remove the read permissions on OSS buckets Query the information about FPGA-accelerated instances Query the status of an FPGA device Upload files to an OSS bucket View files in an OSS bucket Download files to an FPGA-accelerated instance
Manage FPGA images	Create tasks to compile FPGA images Query compilation logs View FPGA images Modify the information about an FPGA image Associate FPGA images with ECS images Copy FPGA images across regions Load FPGA images Query the loading status of FPGA images Delete FPGA images