本文介绍faasutil命令的用法和示例。

前提条件

背景信息

本文涉及的重点概念解释如下：
  • FPGA实例：您在阿里云控制台或者通过OpenAPI创建的FPGA实例，包括计算资源、ECS镜像、云盘等功能组件。
  • ECS镜像：FPGA实例使用的镜像。FPGA实例在提供FPGA加速能力的同时，保留了与普通ECS实例一致的使用体验。
  • 原始文件：您为FPGA设备开发的加速程序，用于编译生成FPGA镜像。例如，Intel FPGA的原始文件为.gbs格式，Xilinx FPGA的原始文件为脚本处理后得到的tar包。
  • FPGA镜像：FPGA设备使用的镜像。原始文件编译后得到FPGA镜像，将FPGA镜像加载到FPGA设备后，FPGA设备即可按照您的设计提供加速服务。每个FPGA镜像拥有唯一的识别码UUID，不同FPGA镜像的UUID不会重复。
使用faasutil时请注意：
  • 运行命令的方式：./faasutil [command]。
  • faasutil命令及其参数严格区分大小写。例如，./faasutil Create_Image --Object=faasutiltest-forcompiling.tar.gz --Shell=f30010 --FPGAType=xilinx --Name=faasutiltest-image会执行出错，命令及其参数的大小写必须和定义完全一致。
  • 参数、=、取值间不能有多余空格。例如，./faasutil create_image --object=faasutiltest-forcompiling.tar.gz --shell = f30010 --fpgatype=xilinx --name=faasutiltest-image会执行出错，必须去掉shell参数=前后的空格。

查看所有命令

查看faasutil版本、所有命令的列表等信息。

定义：
  • faasutil --help
  • faasutil -h
示例：
[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.

查看指定命令

查看指定命令的描述、参数说明等信息。

定义：
  • faasutil [command name] --help
  • faasutil [command name] -h
查看指定命令示例：
[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.

配置用户信息

将用户信息写入默认配置文件。其中：
  • AccessKey ID、AccessKey Secret：必填，用于身份认证。
  • OSS Bucket名称：建议填写，用于指定上传原始文件的OSS Bucket，避免在运行某些命令时重复输入OSS Bucket名称。
定义：
faasutil config --id=[accessid] --key=[accesskey] --token=[sts-token] --bucket=[bucket] --regionId=[regionId] --ossEndpoint=[ossEndpoint] --popEndpoint=[popEndpoint]
说明 您可以运行config命令查看支持配置的信息。
示例：
[root@i**** ~]# ./faasutil config --id=L**** --key=v**** --bucket=yk****
Your configuration is saved into /root/.faascredentials .
1.057(s) elapsed

添加OSS Bucket读权限

添加OSS Bucket读权限，用于FPGA实例读取OSS Bucket中的文件。

定义：
faasutil auth
示例：
[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

查看OSS Bucket读权限

查看已添加的OSS Bucket读权限。

定义：
faasutil list_policy
示例：
[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

删除OSS Bucket读权限

删除OSS Bucket读权限，禁止FPGA实例读取OSS Bucket中的文件。

定义：
faasutil delete_policy
示例：
[root@i**** ~]# ./faasutil delete_policy
0.210(s) elapsed

获取FPGA实例的信息

获取FPGA实例的实例ID、ECS镜像、挂载的FPGA设备等信息。

定义：
faasutil list_instances
示例：
[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

该示例中显示FPGA实例挂载了2个FPGA设备，对应的bdf分别为00:09.0、00:08.0。

获取FPGA设备的状态信息

根据FPGA设备的bdf获取状态信息。您可以运行list_instances命令查看FPGA设备的bdf。

定义：
faasutil fpga_status --bdf=[bdf]
示例：
[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

该示例中查看bdf为00:09.0的FPGA设备的状态信息。其中imageuuid对应指定FPGA镜像的UUID，初次购买的FPGA实例imageuuid取值显示为null。

上传文件至OSS Bucket

将FPGA实例上的文件上传至OSS Bucket，例如上传原始文件。

定义：
faasutil put_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
  • [bucket_name]：OSS Bucket的名称。
    说明 如果已经运行config命令在默认配置文件中指定了OSS Bucket，则可以不指定bucket参数。
  • [file_name]：待上传文件的名称。
  • [object_name]：上传文件后在OSS Bucket中的显示名称。
示例：
[root@i**** ~]# ./faasutil put_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest.tar.gz
100%

539.171(s) elapsed

查看OSS Bucket中的文件

查看OSS Bucket中的文件。

定义：
faasutil list_objects
示例：
[root@i**** ~]# ./faasutil list_objects
faasutiltest-forcompiling.tar.gz
0.288(s) elapsed

下载文件到FPGA实例

从OSS Bucket下载文件到FPGA实例。

定义：
faasutil get_object --bucket=[bucket_name] --object=[object_name] --file=[file_name]
  • [bucket_name]：OSS Bucket的名称。
    说明 如果已经运行config命令在默认配置文件中指定了OSS Bucket，则可以不指定bucket参数。
  • [file_name]：待下载文件的名称。
  • [object_name]：下载文件后在FPGA实例中的显示名称。
示例：
[root@i**** ~]# ./faasutil get_object --object=faasutiltest-forcompiling.tar.gz --file=faasutiltest-fordeveloping.tar.gz
100%

179.909(s) elapsed

创建FPGA镜像编译任务

使用原始文件编译生成FPGA镜像。
说明 编译需要一定时间，请耐心等待。如果已经创建了编译任务，无论是否编译成功，至少30分钟后才可以创建下个编译任务。
定义：
faasutil create_image --object=[object_name] --shell=[shell_ver] --fpgatype=[fpga_type]
  • [object_name]：用于编译的原始文件的名称，请确保已将原始文件上传至OSS Bucket。
  • [shell_ver]：FPGA设备的shell版本信息，您可以运行fpga_status命令查看FPGA设备的shell版本信息。
  • [fpga_type]：FPGA设备的类型，目前支持Xilinx FPGA（xilinx）、Intel FPGA（intel），请根据FPGA设备的类型设置。
示例：
[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

如示例所示，创建FPGA镜像编译任务后会返回FPGA镜像的FpgaImageUniqueId，且State显示为queueing，表示等待编译中。您可以运行list_images命令并查看FpgaImageUniqueId对应任务的状态，待State显示为success时表示编译成功。

查询编译Log

查询指定FPGA镜像编译任务过程中记录的Log。其中，[fpgaImageUniqueId]为创建FPGA镜像编译任务后返回的FPGA镜像UUID。

定义：
faasutil query_log --fpgaImageUniqueId=[fpgaImageUniqueId]
示例：
[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
如示例所示，访问返回结果中的链接即可获取到Log。
说明 如果您不在FPGA实例中查看Log，请去掉链接中的-internal。

查看FPGA镜像

查看已有的FPGA镜像，支持按镜像所有者过滤结果。其中，[owner]为镜像所有者，目前支持市场镜像（market）、本地自制镜像（self）。

定义：
faasutil list_images --owneralias=[owner]
示例：
[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

修改FPGA镜像的信息

修改已有FPGA镜像的名称、描述等信息。

定义：
faasutil modify_image --fpgaImageUniqueId=[fpgaImageUniqueId] --name=[name] --description=[description] --tags=[tags]
示例：
[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": ""
}
查看修改后的信息：
[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

绑定FPGA镜像和ECS镜像

绑定FPGA镜像和ECS镜像后，您可以将ECS镜像发布至镜像市场，第三方在使用您发布的ECS镜像时即可使用与之绑定的FPGA镜像。

定义：
faasutil bind_image --fpgaImageUniqueId=[fpgaImageUniqueId] --ecsImageId=[ecsImageId]
  • [fpgaImageUniqueId]：FPGA镜像的UUID。
  • [ecsImageId]：ECS镜像的ID，默认使用当前FPGA实例所用ECS镜像的ID。
示例：
[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

跨地域拷贝FPGA镜像

如果您需要在新的地域使用一个其他地域已有的FPGA镜像，无需在目标地域重新创建镜像编译任务，将已有的FPGA镜像拷贝至目标地域即可。

定义：
faasutil copy_fpga_image --fpgaImageUniqueId=[fpgaImageUniqueId] --targetRegion=[target region id]
示例：
[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

加载FPGA镜像

将FPGA镜像加载至FPGA设备。您可以运行list_instances命令查看FPGA实例的ID、FPGA设备的bdf，运行list_images命令查看FPGA镜像的UUID。

定义：
faasutil download_image --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --instanceId=[instanceId] --owneralias=[owner]
示例：
[root@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

查询FPGA镜像加载状态

查询FPGA镜像在FPGA设备上的加载状态。您可以运行list_instances命令查看FPGA设备的bdf，运行list_images命令查看FPGA镜像的UUID。

定义：
faasutil download_status --bdf=[bdf] --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
示例：
[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

删除FPGA镜像

删除不再需要的FPGA镜像。
说明 如果FPGA镜像已发布至镜像市场，必须指定--owneralias=market。
定义：
faasutil delete_image --fpgaImageUniqueId=[fpgaImageUniqueId] --owneralias=[owner]
示例：
[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
查看删除结果：
[root@i**** ~]# ./faasutil list_images
{
  "FpgaImages": [],
  "RequestId": "30B73A5B-99FC-4920-8B90-4BA08A075040"
}
0.049(s) elapsed