Update api-ref: Add accelerator requests(ARQs) section

This patch added api v2 api-ref ARQs section

Depends-On: https://review.opendev.org/#/c/690539/
Change-Id: I132de9b76e1cff9e5fe6edb44ed78457f28c2092

api-ref/source/v2/arqs.inc

@@ -0,0 +1,115 @@
+.. -*- rst -*-
+.. needs:body_verification
+
+Accelerator Requests
+++++++++++++++++++++
+
+Lists, creates, shows details for, updates and deletes accelerator requests.
+
+An accelerator request (ARQ) represents a request for a single accelerator
+to be assigned to an instance. ARQs are created in accordance with the
+resource_groups defined in a `device_profile 
+<http://specs.openstack.org/openstack/cyborg-specs/specs/train/approved/device-profiles.html>`_
+by the operator. The accelerator request in the user request may have N
+request groups, each asking for M accelerators; then N * M ARQs will be
+created for that accelerator request.
+
+List Accelerator Requests
+-------------------------
+
+.. rest_method:: GET /v2/accelerator_requests
+
+Lists host_name, device_rp_uuid, instance_uuid and device_profile_group_id
+for all accelerator_requests.
+
+**Example response: list all accelerator requests**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json
+   :language: javascript
+
+Get One Accelerator Request
+---------------------------
+
+.. rest_method:: GET /v2/accelerator_requests/{accelerator_request_uuid}
+
+Gets host_name, device’s_RP_UUID, instance UUID and device_profile_group_ID
+for one accelerator request with the specified UUID.
+
+Request
+=======
+.. rest_parameters:: parameters.yaml
+
+  - accelerator_request_uuid: accelerator_request_uuid 
+
+**Example response: get details of a specific accelerator request**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json
+
+Create Accelerator Requests
+---------------------------
+
+.. rest_method:: POST /v2/accelerator_requests
+
+Creates an accelerator request. The payload should have the following field:
+
+Request
+=======
+.. rest_parameters:: parameters.yaml
+
+  - device_profile_name: device_profile_name
+
+**Example post curl**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json
+
+**Example response: create an accelerator request**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json
+
+Update Accelerator Requests
+---------------------------
+
+The Nova compute manager calls the Cyborg API PATCH /v2/accelerator_requests
+to bind and unbind the ARQ with the host name, device’s RP UUID and instance UUID. This
+is an asynchronous call which prepares or reconfigures the device in the
+background.
+
+.. rest_method:: PATCH /v2/accelerator_requests/{accelerator_request_uuid}
+
+Updates:an accelerator request. The payload should have these fields:
+
+Request
+=======
+.. rest_parameters:: parameters.yaml
+
+  - accelerator_request_uuid: accelerator_request_uuid
+  - hostname: hostname_bind_unbind_req
+  - device_rp_uuid: device_rp_uuid_bind_unbind_req 
+  - instance_uuid: instance_uuid_bind_unbind_req
+
+**Example patch curl**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json
+
+**Example response: update an accelerator request**
+
+.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json
+
+Delete Accelerator Requests by ARQ uuid
+---------------------------------------
+
+.. rest_method:: DELETE /v2/accelerator_requests?arqs={accelerator_request_uuid}
+
+Delete Accelerator Requests by instance uuid
+--------------------------------------------
+
+.. rest_method:: DELETE /v2/accelerator_requests?instance={instance_uuid}
+
+Delete an accelerator request. No query parameters required.
+
+Response
+========
+
+Normal response codes: 204
+
+There is no body content for the response of a successful DELETE query

api-ref/source/v2/index.rst

@@ -10,3 +10,5 @@ in Ussuri.
 .. rest_expand_all::
 
 .. include:: device_profile.inc
+
+.. include:: arqs.inc

api-ref/source/v2/parameters.yaml

@@ -1,3 +1,16 @@
+# variables in path
+accelerator_request_uuid:
+  description: |
+    The UUID of one accelerator request.
+  in: path
+  required: true
+  type: string
+device_profile_name:
+  description: |
+    The display name of a device profile.
+  in: path
+  required: true
+  type: string
 device_profile_uuid:
   description: |
     The UUID of the device_profile for your accelerator request.
@@ -5,6 +18,7 @@ device_profile_uuid:
   in: path
   required: true
   type: string
+# variables in body
 device_prof_groups_req:
   description: |
     This is a list of dictionaries to describe requested accelerator resource
@@ -24,3 +38,22 @@ device_prof_name_req:
   in: body
   required: true
   type: string
+device_rp_uuid_bind_unbind_req:
+  description: |
+    UUID of the target accelerator (resource provider) for bind or unbind of
+    one accelerator request.
+  in: body
+  required: true
+  type: string
+hostname_bind_unbind_req:
+  description: |
+    The name of the target host for bind or unbind of one accelerator request.
+  in: body
+  required: true
+  type: string
+instance_uuid_bind_unbind_req:
+  description: |
+    UUID of the target instance for bind or unbind of one accelerator request.
+  in: body
+  required: true
+  type: string

doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json

@@ -0,0 +1,25 @@
+{
+   "arqs":[
+      {
+         "instance_uuid":null,
+         "hostname":null,
+         "uuid":"89ec9c4d-73b2-4aaf-9225-485945aa7162",
+         "links":[
+            {
+               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/89ec9c4d-73b2-4aaf-9225-485945aa7162",
+               "rel":"self"
+            }
+         ],
+         "created_at":"2019-10-25T12:01:05.896464+00:00",
+         "device_profile_group_id":0,
+         "attach_handle_type":"",
+         "updated_at":null,
+         "state":"Initial",
+         "device_rp_uuid":null,
+         "device_profile_name":"tmp-dp1",
+         "attach_handle_info":{
+
+         }
+      }
+   ]
+}

doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json

@@ -0,0 +1,20 @@
+{
+   "instance_uuid":null,
+   "hostname":null,
+   "uuid":"234c1acf-beca-47b2-9532-6bea61630936",
+   "links":[
+      {
+         "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/234c1acf-beca-47b2-9532-6bea61630936",
+         "rel":"self"
+      }
+   ],
+   "created_at":"2019-10-25T07:58:49+00:00",
+   "device_profile_group_id":0,
+   "attach_handle_type":"",
+   "updated_at":null,
+   "state":"Initial",
+   "device_rp_uuid":null,
+   "device_profile_name":"tmp-dp1",
+   "attach_handle_info":{
+   }
+}

doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json

@@ -0,0 +1,49 @@
+{
+   "arqs":[
+      {
+         "instance_uuid":"d1e3ff56-feef-4495-8e4f-1cf6ea59ffbc",
+         "hostname":"ubuntu-80",
+         "uuid":"7e88a0a5-6dd9-497e-a7e0-fa2d75728a3b",
+         "links":[
+            {
+               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/7e88a0a5-6dd9-497e-a7e0-fa2d75728a3b",
+               "rel":"self"
+            }
+         ],
+         "created_at":"2019-10-25T07:58:23+00:00",
+         "device_profile_group_id":0,
+         "attach_handle_type":"TEST_PCI",
+         "updated_at":"2019-10-25T08:27:46+00:00",
+         "state":"Bound",
+         "device_rp_uuid":"03631f82-20a9-3f67-a29d-dc1abe4041bf",
+         "device_profile_name":"temp-dp1",
+         "attach_handle_info":{
+            "device":"00",
+            "bus":"0c",
+            "domain":"0000",
+            "function":"0"
+         }
+      },
+      {
+         "instance_uuid":null,
+         "hostname":null,
+         "uuid":"234c1acf-beca-47b2-9532-6bea61630936",
+         "links":[
+            {
+               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/234c1acf-beca-47b2-9532-6bea61630936",
+               "rel":"self"
+            }
+         ],
+         "created_at":"2019-10-25T07:58:49+00:00",
+         "device_profile_group_id":0,
+         "attach_handle_type":"",
+         "updated_at":null,
+         "state":"Initial",
+         "device_rp_uuid":null,
+         "device_profile_name":"temp-dp1",
+         "attach_handle_info":{
+
+         }
+      }
+   ]
+}

doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json

@@ -0,0 +1,12 @@
+curl -g -i -X PATCH http://192.168.23.138/accelerator/v2/accelerator_requests \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: None" \
+  -H "X-Auth-Token: yourtoken" \
+  -d '
+{"89ec9c4d-73b2-4aaf-9225-485945aa7162":
+    [{"op": "add", "path": "/instance_uuid",
+        "value": "506220bc-18f2-4294-9b29-80267a021dc0"},
+     {"op": "add", "path": "/hostname", "value": "centos-80"},
+     {"op": "add", "path": "/device_rp_uuid",
+        "value": "03631f82-20a9-3f67-a29d-dc1abe4042bf"}]}'

doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json

@@ -0,0 +1,6 @@
+curl -g -i -X POST http://192.168.23.138/accelerator/v2/accelerator_requests \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: None" \
+  -H "X-Auth-Token: yourtoken" \
+  -d '{"device_profile_name": "tmp-dp1"}'

doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json

@@ -0,0 +1,51 @@
+Before PATCH
+
+{
+   "instance_uuid":null,
+   "hostname":null,
+   "uuid":"89ec9c4d-73b2-4aaf-9225-485945aa7162",
+   "links":[
+      {
+         "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/89ec9c4d-73b2-4aaf-9225-485945aa7162",
+         "rel":"self"
+      }
+   ],
+   "created_at":"2019-10-25T12:01:05+00:00",
+   "device_profile_group_id":0,
+   "attach_handle_type":"",
+   "updated_at":null,
+   "state":"Initial",
+   "device_rp_uuid":null,
+   "device_profile_name":"chenke-dp1",
+   "attach_handle_info":{
+
+   }
+}
+
+After PATCH
+
+{
+   "instance_uuid":"506220bc-18f2-4294-9b29-80267a021dc0",
+   "hostname":"centos-80",
+   "uuid":"89ec9c4d-73b2-4aaf-9225-485945aa7162",
+   "links":[
+      {
+         "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/89ec9c4d-73b2-4aaf-9225-485945aa7162",
+         "rel":"self"
+      }
+   ],
+   "created_at":"2019-10-25T12:01:05+00:00",
+   "device_profile_group_id":0,
+   "attach_handle_type":"TEST_PCI",
+   "updated_at":"2019-10-25T12:49:49+00:00",
+   "state":"Bound",
+   "device_rp_uuid":"03631f82-20a9-3f67-a29d-dc1abe4042bf",
+   "device_profile_name":"chenke-dp1",
+   "attach_handle_info":{
+      "device":"00",
+      "bus":"0c",
+      "domain":"0000",
+      "function":"0"
+   }
+}
+