Help Center> Elastic Cloud Server> API Reference> APIs (Recommended)> FPGA Logical File Management> Creating an FPGA Image
View PDF

Creating an FPGA Image

Function

This API is used to create an FPGA image. Currently, only the FPGA images supported by Xilinx VU9P chips can be created.

This function is available in the CN North-Beijing1, CN East-Shanghai2, and CN South-Guangzhou regions only.

Before creating an FPGA image, ensure that the desired Design Checkpoint (DCP) file is available and that the file is stored in an Object Storage Service (OBS) bucket.

After the FPGA image is initialized, this API returns an FPGA image ID to you. Then, the backend Accelerated Engine Image Factory Service (AFS) uses the DCP file to generate an FPGA image file and uploads the log generated during image file generation to a specified directory in the OBS bucket. The log file is named in the format of "{FPGA image ID}_log.tar", for example, 4010a32c5c62bad9015c62dc2290002b_log.tar.

During the creation, the FPGA image status changes. When its status becomes active or error, the creation is complete.

Table 1 Image statuses

Status

Description

initialling

The task of creating an FPGA image is being initialized.

scheduling

The task of creating an FPGA image is waiting for scheduling.

creating

The FPGA image is being created.

active

The FPGA image is available for use.

error

Creating the FPGA image failed.

Quota limitation: A tenant can create only one FPGA image at a time. When a tenant attempts to concurrently create multiple FPGA images, the creation will fail.

URI

POST /v2/{project_id}/cloudservers/fpga_image

Table 2 describes the parameters in the URI.

Table 2 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

Request

Table 3 describes the request parameters.
Table 3 Request parameters

Parameter

Type

Mandatory

Description

fpga_image

Object

Yes

Indicates details about an FPGA image.
Table 4 fpga_image field description

Parameter

Type

Mandatory

Description

dcp_location

String

Yes

Specifies the path in which the DCP file is stored in the OBS bucket. The format of the path is "Bucket name:File name", for example, obs-fpga:fpga-test-dcp.tar.

A bucket name must comply with the following OBS requirements:

  • Consists of lowercase letters, digits, and special characters . and -.
  • Must start and end with a digit or letter.
  • Contains 3 to 63 characters.
  • Cannot be an IP address.
  • Cannot contain .., .-, or -..

A file name must conform to the following rules:

  • Consists of uppercase and lowercase letters, digits, hyphens (-), underscores (_), slashes (/), and periods (.).
  • Cannot start with a slash (/).
  • Must end with .tar.
  • Contains 4 to 128 characters.

If the file name contains the directory structure, for example, vu9p/fpga-test-dcp.tar, each sub-directory must meet the following requirements:

  • Cannot be left blank.
  • Cannot start or end with a period (.).

log_directory

String

No

Specifies the directory in which the log file is stored in the OBS bucket where the DCP file is stored, for example, vu9p/log. If this field is unavailable or empty, the directory is the same as the one in which the DCP file is stored by default.

A directory must comply with the following rules:

  • Consists of uppercase and lowercase letters, digits, hyphens (-), underscores (_), slashes (/), and periods (.).
  • Cannot start or end with a slash (/).
  • If the directory contains multiple sub-directories, neither sub-directory name can be empty nor start/end with a period (.).
  • Contains 0 to 64 characters.

name

String

Yes

Specifies the FPGA image name.

A name must comply with the following rules:

  • Contains only letters, digits, underscores (_), and hyphens (-).
  • Contains 1 to 64 characters.

description

String

No

Describes an FPGA image. The value consists of uppercase and lowercase letters, digits, hyphens (-), underscores (_), periods (.), commas, and spaces. The value consists of 0 to 255 characters.

Response

Table 5 describes the response parameters.

Table 5 Response parameters

Parameter

Type

Description

fpga_image

Object

Indicates details about an FPGA image.
Table 6 fpga_image field description

Parameter

Type

Description

id

String

Specifies the FPGA image ID.

status

String

Specifies the FPGA image status. Options:

  • initialling: indicates that the task of creating an FPGA image is being initialized.
  • scheduling: indicates that the task of creating an FPGA image is waiting for scheduling.
  • creating: indicates that the FPGA image is being created.
  • deleting: indicates that the FPGA image is being deleted.
  • error: indicates that creating the FPGA image failed.
  • active: indicates that the FPGA image is available for use.

Example Request

POST https://{endpoint}/v2/{project_id}/cloudservers/fpga_image
{
  "fpga_image": {
    "dcp_location": "obs-fpga:vu9p/fpga-vu9p-dcp.tar",
    "log_directory": "vu9p/log",
    "name": "fpga-image-test",
    "description": "fpga description"
  }
}

Example Response

{
  "fpga_image": {
    "status": "initialling",
    "id": "4010a32c5c62bad9015c62dc2290002b"
  }
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Code Description.