queens release doc fix part 1

More patches might follow

Update 0(pacth 1):
1.remove unnecessary files
2.reorg doc directory

Update 1(patch 2):
add releasenotes and cleanup the internal-api spec

Update 2(patch 3):
1.added a new releasenote for generic-driver
2.fixed errors in the other four earlier releasenotes
3.add comment in cyborg/object/accelerator.py and deployable.py to
let user better know the meanings of the table entries.

Change-Id: I45a104f9f77a0a163008657c681cf109f941dd11
Signed-off-by: zhipengh <huangzhipeng@huawei.com>

cyborg/objects/accelerator.py

@@ -38,11 +38,17 @@ class Accelerator(base.CyborgObject, object_base.VersionedObjectDictCompat):
         'project_id': object_fields.UUIDField(nullable=True),
         'user_id': object_fields.UUIDField(nullable=True),
         'device_type': object_fields.StringField(nullable=False),
+        # The type of the accelerator device, e.g GPU, FPGA, ...
         'acc_type': object_fields.StringField(nullable=False),
+        # acc_type defines the usage of the accelerator, e.g Crypto
         'acc_capability': object_fields.StringField(nullable=False),
+        # acc_capability defines the specific capability, e.g AES
         'vendor_id': object_fields.StringField(nullable=False),
+        # vendor_id refers to ids like NVIDIA, XILINX, INTEL,...
         'product_id': object_fields.StringField(nullable=False),
+        # product_id refers to ids like P100
         'remotable': object_fields.IntegerField(nullable=False),
+        # remotable ids if remote accelerator is supported
     }
 
     def create(self, context):

cyborg/objects/deployable.py

@@ -36,16 +36,23 @@ class Deployable(base.CyborgObject, object_base.VersionedObjectDictCompat):
         'uuid': object_fields.UUIDField(nullable=False),
         'name': object_fields.StringField(nullable=False),
         'parent_uuid': object_fields.UUIDField(nullable=True),
+        # parent_uuid refers to the id of the VF's parent node
         'root_uuid': object_fields.UUIDField(nullable=True),
+        # root_uuid refers to the id of the VF's root which has to be a PF
         'pcie_address': object_fields.StringField(nullable=False),
         'host': object_fields.StringField(nullable=False),
         'board': object_fields.StringField(nullable=False),
+        # board refers to a specific acc board type, e.g P100 GPU card
         'vendor': object_fields.StringField(nullable=False),
         'version': object_fields.StringField(nullable=False),
         'type': object_fields.StringField(nullable=False),
+        # similar to the acc_type in accelerator.py
         'assignable': object_fields.BooleanField(nullable=False),
+        # identify if an accelerator is in use
         'instance_uuid': object_fields.UUIDField(nullable=True),
+        # The id of the virtualized accelerator instance
         'availability': object_fields.StringField(nullable=False),
+        # identify the state of acc, e.g released/claimed/...
     }
 
     def _get_parent_root_uuid(self):

doc/source/index.rst

@@ -14,8 +14,8 @@ Overview
 .. toctree::
     :maxdepth: 1
 
-    introduction
+    user/introduction
-    architecture
+    user/architecture
 
 User Documentation
 ----------
@@ -25,15 +25,14 @@ User Documentation
 .. toctree::
    :maxdepth: 1
 
-   userdoc/installation.rst
+   install/installation.rst
-   userdic/usage.rst
 
 **API**
 
 .. toctree::
    :maxdepth: 1
 
-   userdoc/api.rst
+   admin/api.rst
 
 Developer Documentation
 -----------------
@@ -41,12 +40,8 @@ Developer Documentation
 .. toctree::
    :maxdepth: 1
 
-   devdoc/contributing.rst
+   contributor/contributing.rst
 
-.. toctree::
-   :maxdepth: 2
-
-   devdoc/index
 
 Indices and tables
 ==================

doc/source/user/architecture.rst

@@ -3,7 +3,7 @@ Cyborg architecture
 
 Cyborg design can be described by following diagram:
 
-.. image:: images/cyborg-architecture.png
+.. image:: figures/cyborg-architecture.png
     :width: 700 px
     :scale: 99 %
     :align: left

doc/specs/index.rst

@@ -12,3 +12,4 @@ This section has a list of specs for Pike release.
    :glob:
 
    specs/pike/approved/*
+   specs/queens/approved/*

doc/specs/queens/approved/cyborg-fpga-driver-proposal.rst

@@ -176,14 +176,13 @@ References
 
 History
 =======
-c
 
 .. list-table:: Revisions
    :header-rows: 1
 
    * - Release
      - Description
-   * - Pike
+   * - Queens
      - Introduced
 
 References

doc/specs/queens/approved/cyborg-fpga-model-proposal.rst

@@ -332,4 +332,7 @@ History
 .. list-table:: Revisions
    :header-rows: 1
 
-
+   * - Release
+     - Description
+   * - Queens
+     - Introduced

doc/specs/queens/approved/cyborg-internal-api.rst

@@ -176,11 +176,7 @@ N/A
 Other end user impact
 ---------------------
 
-Aside from the API, are there other ways a user will interact with this
+This change might have an impact on python-cyborgclient
-feature?
-
-* Does this change have an impact on python-cyborgclient? What does the user
-  interface there look like?
 
 Performance Impact
 ------------------
@@ -213,100 +209,49 @@ Implementation
 Assignee(s)
 -----------
 
-Who is leading the writing of the code? Or is this a blueprint where you're
-throwing it out there to see who picks it up?
-
-If more than one person is working on the implementation, please designate the
-primary author and contact.
 
 Primary assignee:
-  <launchpad-id or None>
+  jkilpatr
 
 Other contributors:
-  <launchpad-id or None>
+  zhuli
 
 Work Items
 ----------
 
-Work items or tasks -- break the feature up into the things that need to be
+N/A
-done to implement it. Those parts might end up being done by different people,
-but we're mostly trying to understand the timeline for implementation.
 
 
 Dependencies
 ============
 
-* Include specific references to specs and/or blueprints in cyborg, or in other
+N/A
-  projects, that this one either depends on or is related to.
-
-* If this requires functionality of another project that is not currently used
-  by Cyborg, document that fact.
-
-* Does this feature require any new library dependencies or code otherwise not
-  included in OpenStack? Or does it depend on a specific version of library?
 
 
 Testing
 =======
 
-Please discuss the important scenarios needed to test here, as well as
+N/A
-specific edge cases we should be ensuring work correctly. For each
-scenario please specify if this requires specialized hardware, a full
-OpenStack environment, or can be simulated inside the Cyborg tree.
-
-Please discuss how the change will be tested. We especially want to know what
-tempest tests will be added. It is assumed that unit test coverage will be
-added so that doesn't need to be mentioned explicitly, but discussion of why
-you think unit tests are sufficient and we don't need to add more tempest
-tests would need to be included.
-
-Is this untestable in gate given current limitations (specific hardware /
-software configurations available)? If so, are there mitigation plans (3rd
-party testing, gate enhancements, etc).
 
 
 Documentation Impact
 ====================
 
-Which audiences are affected most by this change, and which documentation
+N/A
-titles on docs.openstack.org should be updated because of this change? Don't
-repeat details discussed above, but reference them here in the context of
-documentation for multiple audiences. For example, the Operations Guide targets
-cloud operators, and the End User Guide would need to be updated if the change
-offers a new feature available through the CLI or dashboard. If a config option
-changes or is deprecated, note here that the documentation needs to be updated
-to reflect this specification's change.
 
 References
 ==========
 
-Please add any useful references here. You are not required to have any
+N/A
-reference. Moreover, this specification should still make sense when your
-references are unavailable. Examples of what you could include are:
-
-* Links to mailing list or IRC discussions
-
-* Links to notes from a summit session
-
-* Links to relevant research, if appropriate
-
-* Related specifications as appropriate (e.g.  if it's an EC2 thing, link the
-  EC2 docs)
-
-* Anything else you feel it is worthwhile to refer to
 
 
 History
 =======
 
-Optional section intended to be used each time the spec is updated to describe
-new design, API or any database schema updated. Useful to let reader understand
-what's happened along the time.
-
 .. list-table:: Revisions
    :header-rows: 1
 
    * - Release Name
      - Description
-   * - Pike
+   * - Queens
      - Introduced

doc/specs/queens/approved/cyborg-nova-interaction.rst

@@ -179,5 +179,5 @@ History
 
    * - Release Name
      - Description
-   * - Pike
+   * - Queens
      - Introduced

doc/specs/queens/approved/cyborg-spdk-driver-proposal.rst

@@ -210,12 +210,11 @@ References
 
 History
 =======
-c
 
 .. list-table:: Revisions
    :header-rows: 1
 
    * - Release
      - Description
-   * - Pike
+   * - Queens
      - Introduced

releasenotes/notes/basic-framework-28d6b42d9bf684af.yaml

@@ -1,9 +1,11 @@
 ---
 features:
   - |
-    The Cyborg framework consists of three core services:Api, Conductor
+    The cyborg framework consists of three core services - API, Conductor
     and Agent.
-    Cyborg Api supports GET/POST/PUT/DELETE operations for accelerators.
+    cyborg-api supports GET/POST/PUT/DELETE operations for accelerators.
-    Cyborg conductor is responsible for handling all API requests that come in
+    cyborg-conductor is responsible for handling all API requests that come in
     via the API service.
-    Cyborg Agent is responsible for all the Nova Cyborg interaction.
+    cyborg-agent is responsible for all the Nova Cyborg interaction.
+    It should be noted that for operations that are not associated with DB change,
+    the cyborg-api could directly call cyborg-agent.

releasenotes/notes/cyborg-nova-interaction-8fe4e49e3c9b3b7b.yaml

@@ -0,0 +1,14 @@
+---
+features:
+  - |
+    Cyborg-Nova interaction was completed in Queens via three specs.
+    The cyborg-nova-interaction spec serves as the main spec defines the interaction
+    mechanism between Cyborg and Nova is via Placement to which cyborg-conductor
+    will periodically report the accelerator resource info, which is acquired via
+    resource tracker functionality in the agent.
+    The cyborg-internal-api spec defines the internal api that is mainly used for
+    internal communication between conductor/agent and driver.
+    The cyborg-fpga-model-proposal spec defines the first tryout of data modeling of
+    accelerator resources via resource provider. Two types of tables (accelerator
+    for base PF and deployable for VF) are defined there and nested resource
+    provider will be utilized in Rocky release.

releasenotes/notes/fpga-driver-8b1635e92b1297c1.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    The cyborg-fpga-driver-proposal spec provides the first proposal of a cyborg
+    fpga driver. Two operations are supported - discover and program, although the
+    latter was not finished in Queens and will be in Rocky. The code implementation
+    starts with an Intel QAT card, but more vendor card support should be
+    added later and the driver support should be generalized.

releasenotes/notes/generic-driver-88427acd7c7c12df.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    The cyborg generic driver provide a full implementation of CRUD operations,
+    for testing purpose only. This is only an examplary implementation of a driver
+    which specific accelerator driver could refer to.

releasenotes/notes/spdk-driver-89b178e1a2db29c0.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    The cyborg-spdk-driver-proposal spec defines the first software accelerator
+    driver managed by Cyborg. SPDK is widely used in NVMe SSD user space driver
+    to have a high performance. In Queens only basic operations on SPDK (discover,
+    list, construct/delete subsystem for NVMeOF devices, add/delete ip address
+    for vhost) are supported, more completed operation support should be expected
+    in the next couple releases.