From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from tama500.ecl.ntt.co.jp (tama500.ecl.ntt.co.jp [129.60.39.148]) by dpdk.org (Postfix) with ESMTP id 9A4391B4B6 for ; Thu, 29 Nov 2018 13:30:44 +0100 (CET) Received: from vc1.ecl.ntt.co.jp (vc1.ecl.ntt.co.jp [129.60.86.153]) by tama500.ecl.ntt.co.jp (8.13.8/8.13.8) with ESMTP id wATCUh49015109; Thu, 29 Nov 2018 21:30:43 +0900 Received: from vc1.ecl.ntt.co.jp (localhost [127.0.0.1]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id CA04DEA85CB; Thu, 29 Nov 2018 21:30:43 +0900 (JST) Received: from localhost.localdomain (lobster.nslab.ecl.ntt.co.jp [129.60.13.95]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id B0F06EA860D; Thu, 29 Nov 2018 21:30:43 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: ferruh.yigit@intel.com, spp@dpdk.org, ogawa.yasufumi@lab.ntt.co.jp Date: Thu, 29 Nov 2018 21:28:29 +0900 Message-Id: <1543494509-26537-4-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1543494509-26537-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> References: <1543494509-26537-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-TM-AS-MML: disable Subject: [spp] [PATCH 3/3] docs: add spp_mirror command reference X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 29 Nov 2018 12:30:46 -0000 From: Yasufumi Ogawa This patch is to add spp_mirror commands to `Secondary Commands` section. Signed-off-by: Yasufumi Ogawa --- docs/guides/commands/secondary/index.rst | 1 + docs/guides/commands/secondary/spp_mirror.rst | 220 ++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 docs/guides/commands/secondary/spp_mirror.rst diff --git a/docs/guides/commands/secondary/index.rst b/docs/guides/commands/secondary/index.rst index 81daf70..5c09d57 100644 --- a/docs/guides/commands/secondary/index.rst +++ b/docs/guides/commands/secondary/index.rst @@ -10,3 +10,4 @@ Secondary Commands spp_nfv spp_vf + spp_mirror diff --git a/docs/guides/commands/secondary/spp_mirror.rst b/docs/guides/commands/secondary/spp_mirror.rst new file mode 100644 index 0000000..7aab9d1 --- /dev/null +++ b/docs/guides/commands/secondary/spp_mirror.rst @@ -0,0 +1,220 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation + +.. _commands_spp_mirror: + +spp_mirror +========== + +``spp_mirror`` is an implementation of TaaS feature as a SPP secondary process +for port mirroring. + +Each of ``spp_mirror`` processes is managed with ``mirror`` command. Because +basic design of ``spp_mirror`` is derived from ``spp_vf``, its commands are +almost similar to ``spp_vf``. + +Secondary ID is referred as ``--client-id`` which is given as an argument +while launching ``spp_mirror``. It should be unique among all of secondary +processes including ``spp_nfv`` and others. + +``mirror`` command takes an secondary ID and one of sub commands. Secondary ID +and sub command should be separated with delimiter ``;``, or failed to a +command error. Some of sub commands take additional arguments for +configuration of the process or its resource management. + +.. code-block:: console + + spp > mirror SEC_ID; SUB_CMD + +In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the +following sub commands. Details of each of sub commands are described in the +next sections. + +* status +* component +* port + +``spp_mirror`` supports TAB completion. You can complete all of the name +of commands and its arguments. For instance, you find all of sub commands +by pressing TAB after ``mirror SEC_ID;``. + +.. code-block:: console + + spp > mirror 1; # press TAB key + component port status + +It tries to complete all of possible arguments. However, ``spp_mirror`` takes +also an arbitrary parameter which cannot be predicted, for example, name of +component. In this cases, ``spp_mirror`` shows capitalized keyword for +indicating it is an arbitrary parameter. Here is an exmaple of ``component`` +command to initialize a worker thread. Keyword ``NAME`` should be replaced with +your favorite name for the worker of the role. + +.. code-block:: console + + spp > mirror 1; component st # press TAB key to show args starting 'st' + start stop + spp > mirror 1; component start NAME # 'NAME' is shown with TAB after start + spp > mirror 1; component start mr1 # replace 'NAME' with favorite name + spp > mirror 1; component start mr1 # then, press TAB to show core IDs + 5 6 7 + +It is another example of replacing keyword. ``port`` is a sub command for +assigning a resource to a worker thread. ``RES_UID`` is replaced with +resource UID which is a combination of port type and its ID such as +``ring:0`` or ``vhost:1`` to assign it as RX port of forwarder ``mr1``. + +.. code-block:: console + + spp > mirror 1; port add RES_UID + spp > mirror 1; port add ring:0 rx mr1 + +If you are reached to the end of arguments, no candidate keyword is displayed. +It is a completed statement of ``component`` command, and TAB +completion does not work after ``mirror`` because it is ready to run. + +.. code-block:: console + + spp > mirror 1; component start mr1 5 mirror + Succeeded to start component 'mr1' on core:5 + +It is also completed secondary IDs of ``spp_mirror`` and it is helpful if you run +several ``spp_mirror`` processes. + +.. code-block:: console + + spp > mirror # press TAB after space following 'mirror' + 1; 3; # you find two spp_mirror processes of sec ID 1, 3 + +By the way, it is also a case of no candidate keyword is displayed if your +command statement is wrong. You might be encountered an error if you run the +wrong command. Please take care. + +.. code-block:: console + + spp > mirror 1; compa # no candidate shown for wrong command + Invalid command "compa". + + +.. _commands_spp_mirror_status: + +status +------ + +Show the information of worker threads and its resources. Status information +consists of three parts. + +.. code-block:: console + + spp > vf 1; status + Basic Information: + - client-id: 3 + - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4] + Components: + - core:5 'mr1' (type: mirror) + - rx: ring:0 + - tx: [ring:1, ring:2] + - core:6 'mr2' (type: mirror) + - rx: ring:3 + - tx: [ring:4, ring:5] + - core:7 '' (type: unuse) + +``Basic Information`` is for describing attributes of ``spp_mirror`` itself. +``client-id`` is a secondary ID of the process and ``ports`` is a list of +all of ports owned the process. + +``Components`` is a list of all of worker threads. Each of workers has a +core ID running on, type of the worker and a list of resources. +Entry of no name with ``unuse`` type means that no worker thread assigned to +the core. In other words, it is ready to be assinged. + + +.. _commands_spp_mirror_component: + +component +--------- + +Assing or release a role of forwarding to worker threads running on each of +cores which are reserved with ``-c`` or ``-l`` option while launching +``spp_mirror``. Unlike ``spp_vf``, ``spp_mirror`` only has one role, ``mirror``. + +.. code-block:: console + + # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME' + spp > mirror SEC_ID; component start NAME CORE_ID ROLE + + # release worker 'NAME' from the role + spp > mirror SEC_ID; component stop NAME + +Here is some examples of assigning roles with ``component`` command. + +.. code-block:: console + + # assign 'mirror' role with name 'mr1' on core 2 + spp > mirror 2; component start mr1 2 mirror + +Or examples of releasing roles. + +.. code-block:: console + + # release mirror role + spp > vf 2; component stop mr1 + + +.. _commands_spp_mirror_port: + +port +---- + +Add or delete a port to a worker. + +Adding port +~~~~~~~~~~~ + +.. code-block:: console + + spp > vf SEC_ID; port add RES_UID DIR NAME + +``RES_UID`` is with replaced with resource UID such as ``ring:0`` or +``vhost:1``. ``spp_mirror`` supports three types of port. + + * ``phy`` : Physical NIC + * ``ring`` : Ring PMD + * ``vhost`` : Vhost PMD + +``DIR`` means the direction of forwarding and it should be ``rx`` or ``tx``. +``NAME`` is the same as for ``component`` command. + +This is an example for adding ports to ``mr1``. In this case, it is configured +to receive packets from ``ring:0`` and send it to ``vhost:0`` and ``vhost:1`` +by duplicating the packets. + +.. code-block:: console + + # recieve from 'phy:0' + spp > mirror 2; port add ring:0 rx mr1 + + # send to 'ring:0' and 'ring:1' + spp > mirror 2; port add vhost:0 tx mr1 + spp > mirror 2; port add vhost:1 tx mr1 + + +Deleting port +~~~~~~~~~~~~~ + +Delete a port which is not used anymore. It is almost same as adding port. + +.. code-block:: console + + spp > mirror SEC_ID; port del RES_UID DIR NAME + + +Here is an example. + +.. code-block:: console + + # delete rx port 'ring:0' from 'mr1' + spp > mirror 2; port del ring:0 rx mr1 + + # delete tx port 'vhost:1' from 'mr1' + spp > mirror 2; port del vhost:1 tx mr1 -- 2.7.4