[spp] [PATCH] docs: add API refs for cpu_layout and cpu_usage

[spp] [PATCH] docs: add API refs for cpu_layout and cpu_usage

[yasufum.o]

From: Yasufumi Ogawa <yasufum.o@gmail.com>

This update is to add REST APIs for cpu_layout and cpu_usage of a server
on which spp-ctl running.

Signed-off-by: Yasufumi Ogawa <yasufum.o@gmail.com>
---
 docs/guides/api_ref/proc_independ.rst | 218 +++++++++++++++++++++++---
 1 file changed, 193 insertions(+), 25 deletions(-)

diff --git a/docs/guides/api_ref/proc_independ.rst b/docs/guides/api_ref/proc_independ.rst
index 52e3002..c6180fa 100644
--- a/docs/guides/api_ref/proc_independ.rst
+++ b/docs/guides/api_ref/proc_independ.rst
@@ -4,49 +4,60 @@
 
 .. _spp_ctl_rest_api_proc_independ:
 
-API Independent of Process Type
-===============================
+Independent of Process Type
+===========================
+
 
 GET /v1/processes
 -----------------
 
-Show the SPP processes connected to the ``spp-ctl``.
+Show SPP processes connected with ``spp-ctl``.
 
-* Normarl response codes: 200
 
+Response
+~~~~~~~~
 
-Request example
-~~~~~~~~~~~~~~~
+An array of dict of processes in which process type and secondary ID are
+defined. So, primary process does not have this ID.
 
-.. code-block:: console
+.. _table_spp_ctl_processes_codes:
 
-    $ curl -X GET -H 'application/json' \
-    http://127.0.0.1:7777/v1/processes
+.. table:: Response code of getting processes.
 
+    +-------+-----------------------+
+    | Value | Description           |
+    |       |                       |
+    +=======+=======================+
+    | 200   | Normal response code. |
+    +-------+-----------------------+
 
-Response
-~~~~~~~~
+.. _table_spp_ctl_processes:
 
-An array of process objects.
+.. table:: Response params of getting processes.
 
-Process objects:
+    +-----------+---------+--------------------------------------------------+
+    | Name      | Type    | Description                                      |
+    |           |         |                                                  |
+    +===========+=========+==================================================+
+    | type      | string  | Process type such as ``primary``, ``nfv`` or so. |
+    +-----------+---------+--------------------------------------------------+
+    | client-id | integer | Secondary ID, so ``primary`` does not have it.   |
+    +-----------+---------+--------------------------------------------------+
 
-.. _table_spp_ctl_processes:
 
-.. table:: Response params of getting processes info.
+Examples
+~~~~~~~~
 
-    +-----------+---------+-----------------------------------------------------------------+
-    | Name      | Type    | Description                                                     |
-    |           |         |                                                                 |
-    +===========+=========+=================================================================+
-    | type      | string  | process type. one of ``primary``, ``nfv`` or ``vf``.            |
-    +-----------+---------+-----------------------------------------------------------------+
-    | client-id | integer | client id. if type is ``primary`` this member does not exist.   |
-    +-----------+---------+-----------------------------------------------------------------+
+Request
+^^^^^^^
 
+.. code-block:: console
 
-Response example
-~~~~~~~~~~~~~~~~
+    $ curl -X GET -H 'application/json' \
+    http://127.0.0.1:7777/v1/processes
+
+Response
+^^^^^^^^
 
 .. code-block:: json
 
@@ -63,3 +74,160 @@ Response example
         "client-id": 2
       }
     ]
+
+
+GET /v1/cpu_layout
+------------------
+
+Show CPU layout of a server on which ``spp-ctl`` running.
+
+
+Response
+~~~~~~~~
+
+An array of CPU socket params which consists of each of physical core ID and
+logical cores if hyper threading is enabled.
+
+.. _table_spp_ctl_cpu_layout_codes:
+
+.. table:: Response code of CPU layout.
+
+    +-------+-----------------------+
+    | Value | Description           |
+    |       |                       |
+    +=======+=======================+
+    | 200   | Normal response code. |
+    +-------+-----------------------+
+
+
+.. _table_spp_ctl_cpu_layout:
+
+.. table:: Response params of getting CPU layout.
+
+    +-----------+---------+-------------------------------+
+    | Name      | Type    | Description                   |
+    |           |         |                               |
+    +===========+=========+===============================+
+    | cores     | array   | Set of cores on a socket.     |
+    +-----------+---------+-------------------------------+
+    | core_id   | integer | ID of physical core.          |
+    +-----------+---------+-------------------------------+
+    | lcores    | array   | Set of IDs of logical cores.  |
+    +-----------+---------+-------------------------------+
+    | socket_id | integer | Socket ID.                    |
+    +-----------+---------+-------------------------------+
+
+Examples
+~~~~~~~~
+
+Request
+^^^^^^^
+
+.. code-block:: console
+
+    $ curl -X GET -H 'application/json' \
+    http://127.0.0.1:7777/v1/cpu_layout
+
+Response
+^^^^^^^^
+
+.. code-block:: json
+
+    [
+      {
+        "cores": [
+          {
+            "core_id": 1,
+            "lcores": [2, 3]
+          },
+          {
+            "core_id": 0,
+            "lcores": [0, 1]
+          },
+          ...
+          {
+            "core_id": 2,
+            "lcores": [4, 5]
+          }
+        ],
+        "socket_id": 0
+      }
+    ]
+
+
+GET /v1/cpu_usage
+------------------
+
+Show CPU usage of a server on which ``spp-ctl`` running.
+
+
+Response
+~~~~~~~~
+
+An array of CPU usage of each of SPP processes. This usage consists of
+two params, master lcore and lcore set including master and slaves.
+
+.. _table_spp_ctl_cpu_layout_codes:
+
+.. table:: Response code of CPU layout.
+
+    +-------+-----------------------+
+    | Value | Description           |
+    |       |                       |
+    +=======+=======================+
+    | 200   | Normal response code. |
+    +-------+-----------------------+
+
+
+.. _table_spp_ctl_cpu_layout:
+
+.. table:: Response params of getting CPU layout.
+
+    +--------------+---------+-----------------------------------------------+
+    | Name         | Type    | Description                                   |
+    |              |         |                                               |
+    +==============+=========+===============================================+
+    | proc-type    | string  | Proc type such as ``primary``, ``nfv`` or so. |
+    +--------------+---------+-----------------------------------------------+
+    | master-lcore | integer | Lcore ID of master.                           |
+    +--------------+---------+-----------------------------------------------+
+    | lcores       | array   | All of Lcore IDs including master and slaves. |
+    +--------------+---------+-----------------------------------------------+
+
+Examples
+~~~~~~~~
+
+Request
+^^^^^^^
+
+.. code-block:: console
+
+    $ curl -X GET -H 'application/json' \
+    http://127.0.0.1:7777/v1/cpu_usage
+
+Response
+^^^^^^^^
+
+.. code-block:: json
+
+    [
+      {
+        "proc-type": "primary",
+        "master-lcore": 0,
+        "lcores": [
+          0
+        ]
+      },
+      {
+        "proc-type": "nfv",
+        "client-id": 2,
+        "master-lcore": 1,
+        "lcores": [1, 2]
+      },
+      {
+        "proc-type": "vf",
+        "client-id": 3,
+        "master-lcore": 1,
+        "lcores": [1, 3, 4, 5]
+      }
+    ]
-- 
2.17.1