From 5ee1144e75baca71bd273a73c45cc6e4f310ae9c Mon Sep 17 00:00:00 2001 From: zhipengh Date: Wed, 13 Sep 2017 10:43:02 -0600 Subject: [PATCH] Pike doc clean up Several clean up performed in this patch: * remove readme in the doc/source * move installation.rst and usage.rst to the new userdoc/ * add api.rst to userdoc/ * add introduction.rst in doc/source * add index.rst in every folder * add release info in every spec Change-Id: I9ea96993f916b753cc1aa16c2ea2983b93922f23 Signed-off-by: zhipengh --- README.rst | 12 ++--- doc/source/{ => devdoc}/contributing.rst | 0 doc/source/devdoc/specs/index.rst | 14 ++++++ .../specs/pike/approved}/cyborg-agent.rst | 3 ++ .../pike/approved}/cyborg-api-proposal.rst | 0 .../specs/pike/approved}/cyborg-conductor.rst | 3 ++ .../pike/approved}/cyborg-driver-proposal.rst | 14 +++++- .../source/devdoc/specs}/template.rst | 0 doc/source/index.rst | 44 ++++++++++++++++--- doc/source/introduction.rst | 40 +++++++++++++++++ doc/source/readme.rst | 1 - doc/source/userdoc/api.rst | 23 ++++++++++ doc/source/{ => userdoc}/installation.rst | 0 doc/source/{ => userdoc}/usage.rst | 0 14 files changed, 140 insertions(+), 14 deletions(-) rename doc/source/{ => devdoc}/contributing.rst (100%) create mode 100644 doc/source/devdoc/specs/index.rst rename {specs/pike => doc/source/devdoc/specs/pike/approved}/cyborg-agent.rst (99%) rename {specs/pike/proposal => doc/source/devdoc/specs/pike/approved}/cyborg-api-proposal.rst (100%) rename {specs/pike => doc/source/devdoc/specs/pike/approved}/cyborg-conductor.rst (98%) rename {specs/pike => doc/source/devdoc/specs/pike/approved}/cyborg-driver-proposal.rst (96%) rename {specs => doc/source/devdoc/specs}/template.rst (100%) create mode 100644 doc/source/introduction.rst delete mode 100644 doc/source/readme.rst create mode 100644 doc/source/userdoc/api.rst rename doc/source/{ => userdoc}/installation.rst (100%) rename doc/source/{ => userdoc}/usage.rst (100%) diff --git a/README.rst b/README.rst index f264d3ce..2fa45463 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,11 @@ =============================== -cyborg +Cyborg =============================== -Distributed Acceleration Management as a Service +OpenStack Acceleration as a Service -Please feel here a long description which must be at least 3 lines wrapped on -80 cols, so that distribution package maintainers can use it in their packages. -Note that this is a hard requirement. +Cyborg provides a general management framework for accelerators such as +FPGA, GPU, SoCs, NVMe SSDs, CCIX caches, DPDK/SPDK, pmem and so forth. * Free software: Apache license * Source: https://git.openstack.org/cgit/openstack/cyborg @@ -16,4 +15,5 @@ Note that this is a hard requirement. Features -------- -* TODO +* REST API for basic accelerator life cycle management +* Generic driver for common accelerator support diff --git a/doc/source/contributing.rst b/doc/source/devdoc/contributing.rst similarity index 100% rename from doc/source/contributing.rst rename to doc/source/devdoc/contributing.rst diff --git a/doc/source/devdoc/specs/index.rst b/doc/source/devdoc/specs/index.rst new file mode 100644 index 00000000..f4ba1d5e --- /dev/null +++ b/doc/source/devdoc/specs/index.rst @@ -0,0 +1,14 @@ +Cyborg Specs +============ + +Pike +---- + +This section has a list of specs for Pike release. + + +.. toctree:: + :maxdepth: 1 + :glob: + + specs/pike/approved/* diff --git a/specs/pike/cyborg-agent.rst b/doc/source/devdoc/specs/pike/approved/cyborg-agent.rst similarity index 99% rename from specs/pike/cyborg-agent.rst rename to doc/source/devdoc/specs/pike/approved/cyborg-agent.rst index f802dd71..f47ae110 100644 --- a/specs/pike/cyborg-agent.rst +++ b/doc/source/devdoc/specs/pike/approved/cyborg-agent.rst @@ -154,8 +154,11 @@ Other Cyborg Specs History ======= + .. list-table:: Revisions :header-rows: 1 + * - Release + - Description * - Pike - Introduced diff --git a/specs/pike/proposal/cyborg-api-proposal.rst b/doc/source/devdoc/specs/pike/approved/cyborg-api-proposal.rst similarity index 100% rename from specs/pike/proposal/cyborg-api-proposal.rst rename to doc/source/devdoc/specs/pike/approved/cyborg-api-proposal.rst diff --git a/specs/pike/cyborg-conductor.rst b/doc/source/devdoc/specs/pike/approved/cyborg-conductor.rst similarity index 98% rename from specs/pike/cyborg-conductor.rst rename to doc/source/devdoc/specs/pike/approved/cyborg-conductor.rst index 1fc057e7..a1e8ffcb 100644 --- a/specs/pike/cyborg-conductor.rst +++ b/doc/source/devdoc/specs/pike/approved/cyborg-conductor.rst @@ -132,8 +132,11 @@ Cyborg Agent Spec History ======= + .. list-table:: Revisions :header-rows: 1 + * - Release + - Description * - Pike - Introduced diff --git a/specs/pike/cyborg-driver-proposal.rst b/doc/source/devdoc/specs/pike/approved/cyborg-driver-proposal.rst similarity index 96% rename from specs/pike/cyborg-driver-proposal.rst rename to doc/source/devdoc/specs/pike/approved/cyborg-driver-proposal.rst index cd0d31ec..4fabf56d 100644 --- a/specs/pike/cyborg-driver-proposal.rst +++ b/doc/source/devdoc/specs/pike/approved/cyborg-driver-proposal.rst @@ -146,4 +146,16 @@ None References ========== -None \ No newline at end of file +None + +History +======= + + +.. list-table:: Revisions + :header-rows: 1 + + * - Release + - Description + * - Pike + - Introduced diff --git a/specs/template.rst b/doc/source/devdoc/specs/template.rst similarity index 100% rename from specs/template.rst rename to doc/source/devdoc/specs/template.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index dc41c4c4..5addb1b9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,18 +3,50 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to cyborg's documentation! +Welcome to Cyborg's documentation! ======================================================== +Cyborg is a general management framework for accelerators -Contents: + +Overview +-------- + +.. toctree:: + :maxdepth: 1 + + introduction + architecture + +User Documentation +---------- + +**Installation** + +.. toctree:: + :maxdepth: 1 + + userdoc/installation.rst + userdic/usage.rst + +**API** + +.. toctree:: + :maxdepth: 1 + + userdoc/api.rst + +Developer Documentation +----------------- + +.. toctree:: + :maxdepth: 1 + + devdoc/contributing.rst .. toctree:: :maxdepth: 2 - readme - installation - usage - contributing + devdoc/index Indices and tables ================== diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst new file mode 100644 index 00000000..d1a10a74 --- /dev/null +++ b/doc/source/introduction.rst @@ -0,0 +1,40 @@ +Introduction +============ + +Background Story +---------------- + +OpenStack Acceleration Discussion Started from Telco Requirements: + +* High level requirements first drafted in the standard organization ETSI NFV ISG +* High level requirements transformed into detailed requirements in OPNFV DPACC project. +* New project called Nomad established to address the requirements. +* BoF discussions back in OpenStack Austin Summit. + +Transition to Cyborg Project: + +* From a long period of conversation and discussion within the OpenStack community, +we found that the initial goal of Nomad project to address acceleration management +in Telco is too limited. From design summit session in Barcelona Summit, we have +developers from Scientific WG help us understanding the need for acceleration management +in HPC cloud, and we also had a lot of discussion on the Public Cloud support of +accelerated instances. + +* We decide to formally establish a project that will work on the management framework +for dedicated devices in OpenStack, and there comes the Cyborg Project. + +Definition Breakdown +-------------------- + +**General Management Framework:** +* Resource Discovery +* Life Cycle Management + + +**Accelerators:** +* Software: dpdk/spdk, pmem, ... +* Hardware: FPGA, GPU, ARM SoC, NVMe SSD, CCIX based Caches, ... + + + + diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/userdoc/api.rst b/doc/source/userdoc/api.rst new file mode 100644 index 00000000..982a4d12 --- /dev/null +++ b/doc/source/userdoc/api.rst @@ -0,0 +1,23 @@ +Cyborg REST API v1.0 +******************** + +General Information +=================== + +This document describes the basic REST API operation that Cyborg supports +for Pike release. + ++--------+-----------------------+-------------------------------------------------------------------------------+ +| Verb | URI | Description | ++========+=======================+===============================================================================+ +| GET | /accelerators | Return a list of accelerators | ++--------+-----------------------+-------------------------------------------------------------------------------+ +| GET | /accelerators/{uuid} | Retrieve a certain accelerator info identified by `{uuid}` | ++--------+-----------------------+-------------------------------------------------------------------------------+ +| POST | /accelerators | Create a new accelerator. | ++--------+-----------------------+-------------------------------------------------------------------------------+ +| PUT | /accelerators/{uuid} | Update the spec for the accelerator identified by `{uuid}` | ++--------+-----------------------+-------------------------------------------------------------------------------+ +| DELETE | /accelerators/{uuid} | Delete the accelerator identified by `{uuid}` | ++--------+-----------------------+-------------------------------------------------------------------------------+ + diff --git a/doc/source/installation.rst b/doc/source/userdoc/installation.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/userdoc/installation.rst diff --git a/doc/source/usage.rst b/doc/source/userdoc/usage.rst similarity index 100% rename from doc/source/usage.rst rename to doc/source/userdoc/usage.rst