From 2e78e10e5a673d481e9613d74da4b6cf72b4a77e Mon Sep 17 00:00:00 2001 From: zhipengh Date: Tue, 6 Feb 2018 00:23:58 +0800 Subject: [PATCH] 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 --- .idea/workspace.xml | 1352 ----------------- cyborg/objects/accelerator.py | 6 + cyborg/objects/deployable.py | 7 + doc/source/{userdoc => admin}/api.rst | 0 .../{devdoc => contributor}/contributing.rst | 0 .../cyborg-architecture.png | Bin doc/source/index.rst | 15 +- .../{userdoc => install}/installation.rst | 0 doc/source/{ => user}/architecture.rst | 2 +- doc/source/{ => user}/introduction.rst | 0 doc/source/{userdoc => user}/usage.rst | 0 doc/{source/devdoc => }/specs/index.rst | 1 + .../specs/pike/approved/cyborg-agent.rst | 0 .../pike/approved/cyborg-api-proposal.rst | 0 .../specs/pike/approved/cyborg-conductor.rst | 0 .../pike/approved/cyborg-driver-proposal.rst | 0 .../approved}/cyborg-fpga-driver-proposal.rst | 3 +- .../approved}/cyborg-fpga-model-proposal.rst | 5 +- .../queens/approved/cyborg-internal-api.rst} | 73 +- .../approved}/cyborg-nova-interaction.rst | 2 +- .../approved}/cyborg-spdk-driver-proposal.rst | 3 +- doc/{source/devdoc => }/specs/template.rst | 0 .../basic-framework-28d6b42d9bf684af.yaml | 10 +- ...org-nova-interaction-8fe4e49e3c9b3b7b.yaml | 14 + .../notes/fpga-driver-8b1635e92b1297c1.yaml | 8 + .../generic-driver-88427acd7c7c12df.yaml | 6 + .../notes/spdk-driver-89b178e1a2db29c0.yaml | 9 + 27 files changed, 79 insertions(+), 1437 deletions(-) delete mode 100644 .idea/workspace.xml rename doc/source/{userdoc => admin}/api.rst (100%) rename doc/source/{devdoc => contributor}/contributing.rst (100%) rename doc/source/{images => figures}/cyborg-architecture.png (100%) rename doc/source/{userdoc => install}/installation.rst (100%) rename doc/source/{ => user}/architecture.rst (95%) rename doc/source/{ => user}/introduction.rst (100%) rename doc/source/{userdoc => user}/usage.rst (100%) rename doc/{source/devdoc => }/specs/index.rst (85%) rename doc/{source/devdoc => }/specs/pike/approved/cyborg-agent.rst (100%) rename doc/{source/devdoc => }/specs/pike/approved/cyborg-api-proposal.rst (100%) rename doc/{source/devdoc => }/specs/pike/approved/cyborg-conductor.rst (100%) rename doc/{source/devdoc => }/specs/pike/approved/cyborg-driver-proposal.rst (100%) rename {specs/queens => doc/specs/queens/approved}/cyborg-fpga-driver-proposal.rst (99%) rename {specs/proposal => doc/specs/queens/approved}/cyborg-fpga-model-proposal.rst (99%) rename doc/{source/devdoc/specs/internal-api.rst => specs/queens/approved/cyborg-internal-api.rst} (61%) rename {specs/proposal => doc/specs/queens/approved}/cyborg-nova-interaction.rst (99%) rename {specs/queens => doc/specs/queens/approved}/cyborg-spdk-driver-proposal.rst (99%) rename doc/{source/devdoc => }/specs/template.rst (100%) create mode 100644 releasenotes/notes/cyborg-nova-interaction-8fe4e49e3c9b3b7b.yaml create mode 100644 releasenotes/notes/fpga-driver-8b1635e92b1297c1.yaml create mode 100644 releasenotes/notes/generic-driver-88427acd7c7c12df.yaml create mode 100644 releasenotes/notes/spdk-driver-89b178e1a2db29c0.yaml diff --git a/.idea/workspace.xml b/.idea/workspace.xml deleted file mode 100644 index e242b0f7..00000000 --- a/.idea/workspace.xml +++ /dev/null @@ -1,1352 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - true - DEFINITION_ORDER - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - project - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1517396357849 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - file://$PROJECT_DIR$/cyborg/accelerator/drivers/spdk/util/pyspdk/proto/spdk_pb2.py - 1066 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/cyborg/objects/accelerator.py b/cyborg/objects/accelerator.py index 93d5a990..32513320 100644 --- a/cyborg/objects/accelerator.py +++ b/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): diff --git a/cyborg/objects/deployable.py b/cyborg/objects/deployable.py index 8db1cdf4..a283bafd 100644 --- a/cyborg/objects/deployable.py +++ b/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): diff --git a/doc/source/userdoc/api.rst b/doc/source/admin/api.rst similarity index 100% rename from doc/source/userdoc/api.rst rename to doc/source/admin/api.rst diff --git a/doc/source/devdoc/contributing.rst b/doc/source/contributor/contributing.rst similarity index 100% rename from doc/source/devdoc/contributing.rst rename to doc/source/contributor/contributing.rst diff --git a/doc/source/images/cyborg-architecture.png b/doc/source/figures/cyborg-architecture.png similarity index 100% rename from doc/source/images/cyborg-architecture.png rename to doc/source/figures/cyborg-architecture.png diff --git a/doc/source/index.rst b/doc/source/index.rst index 5addb1b9..3f2bf706 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,8 +14,8 @@ Overview .. toctree:: :maxdepth: 1 - introduction - architecture + user/introduction + user/architecture User Documentation ---------- @@ -25,15 +25,14 @@ User Documentation .. toctree:: :maxdepth: 1 - userdoc/installation.rst - userdic/usage.rst + install/installation.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 ================== diff --git a/doc/source/userdoc/installation.rst b/doc/source/install/installation.rst similarity index 100% rename from doc/source/userdoc/installation.rst rename to doc/source/install/installation.rst diff --git a/doc/source/architecture.rst b/doc/source/user/architecture.rst similarity index 95% rename from doc/source/architecture.rst rename to doc/source/user/architecture.rst index ac14cc51..c0011594 100644 --- a/doc/source/architecture.rst +++ b/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 diff --git a/doc/source/introduction.rst b/doc/source/user/introduction.rst similarity index 100% rename from doc/source/introduction.rst rename to doc/source/user/introduction.rst diff --git a/doc/source/userdoc/usage.rst b/doc/source/user/usage.rst similarity index 100% rename from doc/source/userdoc/usage.rst rename to doc/source/user/usage.rst diff --git a/doc/source/devdoc/specs/index.rst b/doc/specs/index.rst similarity index 85% rename from doc/source/devdoc/specs/index.rst rename to doc/specs/index.rst index f4ba1d5e..c6eeffd0 100644 --- a/doc/source/devdoc/specs/index.rst +++ b/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/* diff --git a/doc/source/devdoc/specs/pike/approved/cyborg-agent.rst b/doc/specs/pike/approved/cyborg-agent.rst similarity index 100% rename from doc/source/devdoc/specs/pike/approved/cyborg-agent.rst rename to doc/specs/pike/approved/cyborg-agent.rst diff --git a/doc/source/devdoc/specs/pike/approved/cyborg-api-proposal.rst b/doc/specs/pike/approved/cyborg-api-proposal.rst similarity index 100% rename from doc/source/devdoc/specs/pike/approved/cyborg-api-proposal.rst rename to doc/specs/pike/approved/cyborg-api-proposal.rst diff --git a/doc/source/devdoc/specs/pike/approved/cyborg-conductor.rst b/doc/specs/pike/approved/cyborg-conductor.rst similarity index 100% rename from doc/source/devdoc/specs/pike/approved/cyborg-conductor.rst rename to doc/specs/pike/approved/cyborg-conductor.rst diff --git a/doc/source/devdoc/specs/pike/approved/cyborg-driver-proposal.rst b/doc/specs/pike/approved/cyborg-driver-proposal.rst similarity index 100% rename from doc/source/devdoc/specs/pike/approved/cyborg-driver-proposal.rst rename to doc/specs/pike/approved/cyborg-driver-proposal.rst diff --git a/specs/queens/cyborg-fpga-driver-proposal.rst b/doc/specs/queens/approved/cyborg-fpga-driver-proposal.rst similarity index 99% rename from specs/queens/cyborg-fpga-driver-proposal.rst rename to doc/specs/queens/approved/cyborg-fpga-driver-proposal.rst index 0226fc52..4f01da33 100755 --- a/specs/queens/cyborg-fpga-driver-proposal.rst +++ b/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 diff --git a/specs/proposal/cyborg-fpga-model-proposal.rst b/doc/specs/queens/approved/cyborg-fpga-model-proposal.rst similarity index 99% rename from specs/proposal/cyborg-fpga-model-proposal.rst rename to doc/specs/queens/approved/cyborg-fpga-model-proposal.rst index 0d146ad0..3a911c16 100644 --- a/specs/proposal/cyborg-fpga-model-proposal.rst +++ b/doc/specs/queens/approved/cyborg-fpga-model-proposal.rst @@ -332,4 +332,7 @@ History .. list-table:: Revisions :header-rows: 1 - + * - Release + - Description + * - Queens + - Introduced diff --git a/doc/source/devdoc/specs/internal-api.rst b/doc/specs/queens/approved/cyborg-internal-api.rst similarity index 61% rename from doc/source/devdoc/specs/internal-api.rst rename to doc/specs/queens/approved/cyborg-internal-api.rst index dc5cff83..09662c2d 100644 --- a/doc/source/devdoc/specs/internal-api.rst +++ b/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 -feature? - -* Does this change have an impact on python-cyborgclient? What does the user - interface there look like? +This change might have an impact on python-cyborgclient 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: - + jkilpatr Other contributors: - + zhuli Work Items ---------- -Work items or tasks -- break the feature up into the things that need to be -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. +N/A Dependencies ============ -* Include specific references to specs and/or blueprints in cyborg, or in other - 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? +N/A Testing ======= -Please discuss the important scenarios needed to test here, as well as -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). +N/A Documentation Impact ==================== -Which audiences are affected most by this change, and which documentation -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. +N/A References ========== -Please add any useful references here. You are not required to have any -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 +N/A 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 diff --git a/specs/proposal/cyborg-nova-interaction.rst b/doc/specs/queens/approved/cyborg-nova-interaction.rst similarity index 99% rename from specs/proposal/cyborg-nova-interaction.rst rename to doc/specs/queens/approved/cyborg-nova-interaction.rst index f98101e9..57cc781e 100644 --- a/specs/proposal/cyborg-nova-interaction.rst +++ b/doc/specs/queens/approved/cyborg-nova-interaction.rst @@ -179,5 +179,5 @@ History * - Release Name - Description - * - Pike + * - Queens - Introduced diff --git a/specs/queens/cyborg-spdk-driver-proposal.rst b/doc/specs/queens/approved/cyborg-spdk-driver-proposal.rst similarity index 99% rename from specs/queens/cyborg-spdk-driver-proposal.rst rename to doc/specs/queens/approved/cyborg-spdk-driver-proposal.rst index 6b26fbaf..3d51f661 100755 --- a/specs/queens/cyborg-spdk-driver-proposal.rst +++ b/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 diff --git a/doc/source/devdoc/specs/template.rst b/doc/specs/template.rst similarity index 100% rename from doc/source/devdoc/specs/template.rst rename to doc/specs/template.rst diff --git a/releasenotes/notes/basic-framework-28d6b42d9bf684af.yaml b/releasenotes/notes/basic-framework-28d6b42d9bf684af.yaml index b38c7822..4ad9fc3d 100644 --- a/releasenotes/notes/basic-framework-28d6b42d9bf684af.yaml +++ b/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 conductor is responsible for handling all API requests that come in + cyborg-api supports GET/POST/PUT/DELETE operations for accelerators. + 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. diff --git a/releasenotes/notes/cyborg-nova-interaction-8fe4e49e3c9b3b7b.yaml b/releasenotes/notes/cyborg-nova-interaction-8fe4e49e3c9b3b7b.yaml new file mode 100644 index 00000000..87ebc837 --- /dev/null +++ b/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. diff --git a/releasenotes/notes/fpga-driver-8b1635e92b1297c1.yaml b/releasenotes/notes/fpga-driver-8b1635e92b1297c1.yaml new file mode 100644 index 00000000..a53c3461 --- /dev/null +++ b/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. diff --git a/releasenotes/notes/generic-driver-88427acd7c7c12df.yaml b/releasenotes/notes/generic-driver-88427acd7c7c12df.yaml new file mode 100644 index 00000000..f82f82df --- /dev/null +++ b/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. diff --git a/releasenotes/notes/spdk-driver-89b178e1a2db29c0.yaml b/releasenotes/notes/spdk-driver-89b178e1a2db29c0.yaml new file mode 100644 index 00000000..2bc50d07 --- /dev/null +++ b/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.