This topic describes how to use faasutil commands. This topic also provides examples for these commands.

Prerequisites

  • faasutil is obtained. For more information, see Obtain faasutil.
  • A raw file is prepared. For more information, see the term description in the Context section in this topic.
  • An Object Storage Service (OSS) bucket is created. The 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.
    Note FaaS supports only the AccessKey pair of RAM users. You can only access Functions as a Service (FaaS) using the Accesskey pair as an RAM user. This minimizes the risk that the AccessKey pair is exposed.

Background information

The following section describes the key terms used in this topic:
  • FPGA-accelerated instance: the FPGA-accelerated instance that you create by using the Alibaba Cloud console or calling API operations. FPGA-accelerated instances include computing resources, Elastic Compute Service (ECS) images, and disks.
  • ECS image: the 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. Each FPGA image has a UUID.
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, errors occur when 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 spaces exist between parameters, equal signs (=), and values. For example, error occurs when 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 (=) of the shell parameter.

View all commands

View the faasutil version and the list of commands.

Definition:
  • faasutil --help
  • faasutil -h
Example:
[root@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 specified commands and their parameters.

Definition:
  • faasutil [command name] --help
  • faasutil [command name] -h
Example:
[root@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. Take note of the following parameters:
  • AccessKey ID and AccessKey secret: required. The AccessKey ID and AccessKey secret are used for authentication.
  • OSS bucket name: optional. 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.
Definition:
faasutil config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]
Note You can run the config command to view information that can be configured.
Example:
[root@i**** ~]# ./faasutil config --id=L**** --key=v**** --bucket=yk****
Your configuration is saved into /root/.faascredentials .
1.057(s) elapsed

Grant the read permissions on OSS buckets

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

Definition:
faasutil auth
Example:
[root@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 granted read permissions on OSS buckets.

Definition:
faasutil list_policy
Example:
[root@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

Delete the read permissions on OSS buckets

Delete the read permissions on OSS buckets to prohibit FPGA-accelerated instances from reading files from OSS buckets.

Definition:
faasutil delete_policy
Example:
[root@i**** ~]# ./faasutil delete_policy
0.210(s) elapsed

Obtain information about FPGA-accelerated instances

Obtain information about FPGA-accelerated instances, such as instance IDs, ECS images, and attached FPGA devices.

Definition:
faasutil list_instances
Example:
[root@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

In this example, an FPGA-accelerated instance is attached with two FPGA devices whose bdf is set to 00:09.0 and 00:08.0.

Obtain the status information of an FPGA device

Obtain the status information based on bdf of an FPGA device. You can run the list_instances command to view bdf of an FPGA device.

Definition:
faasutil fpga_status --bdf=[bdf]
Example:
[root@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

This example shows the status information of an FPGA device whose bdf is set to 00:09.0. imageuuid specifies the UUID of the specified FPGA image. For a newly purchased FPGA-accelerated instance, the value of imageuuid is null.

Upload files to an OSS bucket

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

Definition:
faasutil put_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
  • [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 displayed name of the uploaded file in the OSS bucket.
Example:
[root@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.

Definition:
faasutil list_objects
Example:
[root@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.

Definition:
faasutil get_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
  • [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 displayed name of the downloaded file in the FPGA-accelerated instance.
Example:
[root@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 some 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 is complete.
Definition:
faasutil create_image --object=[object_name] --shell=[shell_ver] --fpgatype=[fpga_type]
  • [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.
  • [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.
Example:
[root@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 parameter is returned for an FPGA image after an FPGA image compilation task is created. In this example, the value of State 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 to which FpgaImageUniqueId corresponds. When State becomes success, the compilation is complete.

Query compilation logs

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

Definition:
faasutil query_log --fpgaImageUniqueId=[fpgaImageUniqueId]
Example:
[root@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.
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. [owner] specifies the image owner. Alibaba Cloud Marketplace images (market) and local images (self) are supported.

Definition:
faasutil list_images --owneralias=[owner]
Example:
[root@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 FPGA image information

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

Definition:
faasutil modify_image --fpgaImageUniqueId=[fpgaImageUniqueId] --name=[name] --description=[description] --tags=[tags]
Example:
[root@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:
[root@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

Bind FPGA images to ECS images

After you bind FPGA images to 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 bound to the ECS images.

Definition:
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.
Example:
[root@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.

Definition:
faasutil copy_fpga_image --fpgaImageUniqueId=[fpgaImageUniqueId] --targetRegion=[target region id]
Example:
[root@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 bdf of an FPGA device. You can run the list_images command to view the UUID of an FPGA image.

Definition:
faasutil download_image --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --instanceId=[instanceId] --owneralias=[owner]
Example:
[root@i**** ~]# ./faasutil download_image --bdf=00:09.0 --fpgaImageUniqueId=xilinx5395ad11-edb9-4d93-964d-12c59a07****
null
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 bdf of an FPGA device or run the list_images command to view the UUID of an FPGA image.

Definition:
faasutil download_status --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
Example:
[root@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 --owneralias=market.
Definition:
faasutil delete_image --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
Example:
[root@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:
[root@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [],
  "RequestId": "30B73A5B-99FC-4920-8B90-4BA08A075040"
}
0.049(s) elapsed