[spp] [PATCH v2 2/2] docs: add spp_mirror API api-reference

[oda@valinux.co.jp]

From: Itsuro Oda <oda@valinux.co.jp>

This patch adds spp_mirror API reference for spp-ctl.

Signed-off-by: Itsuro Oda <oda@valinux.co.jp>
---
 docs/guides/spp-ctl/api-reference.rst | 316 ++++++++++++++++++++++++++
 1 file changed, 316 insertions(+)

diff --git a/docs/guides/spp-ctl/api-reference.rst b/docs/guides/spp-ctl/api-reference.rst
index 70eddd6..b0d367b 100644
--- a/docs/guides/spp-ctl/api-reference.rst
+++ b/docs/guides/spp-ctl/api-reference.rst
@@ -1168,3 +1168,319 @@ type is ``vlan``
 .. code-block:: none
 
     classifier_table {action} vlan {vlan} {mac_address} {port}
+
+
+API for spp_mirror
+------------------
+
+GET /v1/mirrors/{client_id}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the information of the ``spp_mirror`` process.
+
+* Normal response codes: 200
+* Error response codes: 400, 404
+
+Request(path)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_mirrors_get:
+
+.. table:: Request parameter for getting spp_mirror.
+
+    +-----------+---------+--------------------------+
+    | Name      | Type    | Description              |
+    |           |         |                          |
+    +===========+=========+==========================+
+    | client_id | integer | client id.               |
+    +-----------+---------+--------------------------+
+
+Request example
+^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    curl -X GET -H 'application/json' \
+    http://127.0.0.1:7777/v1/mirrors/1
+
+Response
+^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_res:
+
+.. table:: Response params of getting spp_mirror.
+
+    +------------------+---------+-----------------------------------------------+
+    | Name             | Type    | Description                                   |
+    |                  |         |                                               |
+    +==================+=========+===============================================+
+    | client-id        | integer | client id.                                    |
+    +------------------+---------+-----------------------------------------------+
+    | ports            | array   | an array of port ids used by the process.     |
+    +------------------+---------+-----------------------------------------------+
+    | components       | array   | an array of component objects in the process. |
+    +------------------+---------+-----------------------------------------------+
+
+component object:
+
+.. _table_spp_ctl_spp_mirror_res_comp:
+
+.. table:: Component objects of getting spp_mirror.
+
+    +---------+---------+---------------------------------------------------------------------+
+    | Name    | Type    | Description                                                         |
+    |         |         |                                                                     |
+    +=========+=========+=====================================================================+
+    | core    | integer | core id running on the component                                    |
+    +---------+---------+---------------------------------------------------------------------+
+    | name    | string  | an array of port ids used by the process.                           |
+    +---------+---------+---------------------------------------------------------------------+
+    | type    | string  | an array of component objects in the process.                       |
+    +---------+---------+---------------------------------------------------------------------+
+    | rx_port | array   | an array of port objects connected to the rx side of the component. |
+    +---------+---------+---------------------------------------------------------------------+
+    | tx_port | array   | an array of port objects connected to the tx side of the component. |
+    +---------+---------+---------------------------------------------------------------------+
+
+port object:
+
+.. _table_spp_ctl_spp_mirror_res_port:
+
+.. table:: Port objects of getting spp_vf.
+
+    +---------+---------+---------------------------------------------------------------+
+    | Name    | Type    | Description                                                   |
+    |         |         |                                                               |
+    +=========+=========+===============================================================+
+    | port    | string  | port id. port id is the form {interface_type}:{interface_id}. |
+    +---------+---------+---------------------------------------------------------------+
+
+Response example
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+    {
+      "client-id": 1,
+      "ports": [
+        "phy:0", "phy:1", "ring:0", "ring:1", "ring:2"
+      ],
+      "components": [
+        {
+          "core": 2,
+          "name": "mirror_0",
+          "type": "mirror",
+          "rx_port": [
+            {
+            "port": "ring:0"
+            }
+          ],
+          "tx_port": [
+            {
+              "port": "ring:1"
+            },
+            {
+              "port": "ring:2"
+            }
+          ]
+        },
+        {
+          "core": 3,
+          "type": "unuse"
+        }
+      ]
+    }
+
+The component which type is ``unused`` is to indicate unused core.
+
+Equivalent CLI command
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+    sec {client_id};status
+
+
+POST /v1/mirrors/{client_id}/components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Start the component.
+
+* Normal response codes: 204
+* Error response codes: 400, 404
+
+Request(path)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_components:
+
+.. table:: Request params of components of spp_mirror.
+
+    +-----------+---------+-------------+
+    | Name      | Type    | Description |
+    +===========+=========+=============+
+    | client_id | integer | client id.  |
+    +-----------+---------+-------------+
+
+
+Request(body)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_components_res:
+
+.. table:: Response params of components of spp_mirror.
+
+    +-----------+---------+----------------------------------------------------------------------+
+    | Name      | Type    | Description                                                          |
+    |           |         |                                                                      |
+    +===========+=========+======================================================================+
+    | name      | string  | component name. must be unique in the process.                       |
+    +-----------+---------+----------------------------------------------------------------------+
+    | core      | integer | core id.                                                             |
+    +-----------+---------+----------------------------------------------------------------------+
+    | type      | string  | component type. only ``mirror`` is available.                        |
+    +-----------+---------+----------------------------------------------------------------------+
+
+Request example
+^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    curl -X POST -H 'application/json' \
+    -d '{"name": "mirror_1", "core": 12, "type": "mirror"}' \
+    http://127.0.0.1:7777/v1/mirrors/1/components
+
+Response
+^^^^^^^^
+
+There is no body content for the response of a successful ``POST`` request.
+
+Equivalent CLI command
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+    sec {client_id};component start {name} {core} {type}
+
+
+DELETE /v1/mirrors/{client_id}/components/{name}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Stop the component.
+
+* Normal response codes: 204
+* Error response codes: 400, 404
+
+Request(path)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_del:
+
+.. table:: Request params of deleting component of spp_mirror.
+
+    +-----------+---------+---------------------------------+
+    | Name      | Type    | Description                     |
+    |           |         |                                 |
+    +===========+=========+=================================+
+    | client_id | integer | client id.                      |
+    +-----------+---------+---------------------------------+
+    | name      | string  | component name.                 |
+    +-----------+---------+---------------------------------+
+
+Request example
+^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    curl -X DELETE -H 'application/json' \
+    http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1
+
+Response
+^^^^^^^^
+
+There is no body content for the response of a successful ``POST`` request.
+
+Equivalent CLI command
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: none
+
+    sec {client_id};component stop {name}
+
+
+PUT /v1/mirrors/{client_id}/components/{name}/ports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add or Delete port to the component.
+
+* Normal response codes: 204
+* Error response codes: 400, 404
+
+Request(path)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_comp_port:
+
+.. table:: Request params for ports of component of spp_mirror.
+
+    +-----------+---------+---------------------------+
+    | Name      | Type    | Description               |
+    |           |         |                           |
+    +===========+=========+===========================+
+    | client_id | integer | client id.                |
+    +-----------+---------+---------------------------+
+    | name      | string  | component name.           |
+    +-----------+---------+---------------------------+
+
+Request(body)
+^^^^^^^^^^^^^
+
+.. _table_spp_ctl_spp_mirror_comp_port_body:
+
+.. table:: Request body params for ports of component of spp_mirror.
+
+    +---------+---------+-----------------------------------------------------------------+
+    | Name    | Type    | Description                                                     |
+    |         |         |                                                                 |
+    +=========+=========+=================================================================+
+    | action  | string  | ``attach`` or ``detach``.                                       |
+    +---------+---------+-----------------------------------------------------------------+
+    | port    | string  | port id. port id is the form {interface_type}:{interface_id}.   |
+    +---------+---------+-----------------------------------------------------------------+
+    | dir     | string  | ``rx`` or ``tx``.                                               |
+    +---------+---------+-----------------------------------------------------------------+
+
+Request example
+^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    curl -X PUT -H 'application/json' \
+    -d '{"action": "attach", "port": "ring:1", "dir": "rx"}' \
+    http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports
+
+.. code-block:: console
+
+    curl -X PUT -H 'application/json' \
+    -d '{"action": "detach", "port": "ring:0", "dir": "tx"} \
+    http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports
+
+Response
+^^^^^^^^
+
+There is no body content for the response of a successful ``PUT`` request.
+
+Equivalent CLI command
+^^^^^^^^^^^^^^^^^^^^^^
+
+action is ``attach``
+
+.. code-block:: none
+
+    sec {client_id};port add {port} {dir} {name}
+
+action is ``detach``
+
+.. code-block:: none
+
+    sec {client_id};port del {port} {dir} {name}
-- 
2.17.1