From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from tama50.ecl.ntt.co.jp (tama50.ecl.ntt.co.jp [129.60.39.147]) by dpdk.org (Postfix) with ESMTP id 184C31B12C for ; Fri, 19 Oct 2018 09:07:43 +0200 (CEST) Received: from vc2.ecl.ntt.co.jp (vc2.ecl.ntt.co.jp [129.60.86.154]) by tama50.ecl.ntt.co.jp (8.13.8/8.13.8) with ESMTP id w9J77gF8013086; Fri, 19 Oct 2018 16:07:42 +0900 Received: from vc2.ecl.ntt.co.jp (localhost [127.0.0.1]) by vc2.ecl.ntt.co.jp (Postfix) with ESMTP id DB8B36390C2; Fri, 19 Oct 2018 16:07:42 +0900 (JST) Received: from localhost.localdomain (unknown [129.60.13.51]) by vc2.ecl.ntt.co.jp (Postfix) with ESMTP id C0223639099; Fri, 19 Oct 2018 16:07:42 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: spp@dpdk.org, ferruh.yigit@intel.com, ogawa.yasufumi@lab.ntt.co.jp Date: Fri, 19 Oct 2018 16:07:33 +0900 Message-Id: <20181019070733.81220-3-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.13.1 In-Reply-To: <20181019070733.81220-1-ogawa.yasufumi@lab.ntt.co.jp> References: <20181019070733.81220-1-ogawa.yasufumi@lab.ntt.co.jp> X-TM-AS-MML: disable Subject: [spp] [PATCH 2/2] docs: update spp_vf command 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: Fri, 19 Oct 2018 07:07:45 -0000 From: Yasufumi Ogawa Revise descriptions and examples of spp_vf command. Signed-off-by: Yasufumi Ogawa --- docs/guides/commands/spp_vf.rst | 363 +++++++++++++++++++++++++--------------- 1 file changed, 232 insertions(+), 131 deletions(-) diff --git a/docs/guides/commands/spp_vf.rst b/docs/guides/commands/spp_vf.rst index 8e4a72a..aa2b1f4 100644 --- a/docs/guides/commands/spp_vf.rst +++ b/docs/guides/commands/spp_vf.rst @@ -3,245 +3,346 @@ .. _commands_spp_vf: -SPP VF Commands -=============== +SPP VF +====== -Each of secondary processes is managed with ``sec`` command. -It is for sending sub commands to secondary with specific ID called -secondary ID. +``spp_vf`` is a kind of SPP secondary process. It it introduced for +providing SR-IOV like features. -``sec`` command takes an secondary ID and a sub command. They must be -separated with delimiter ``;``. -Some of sub commands take additional arguments for speicfying resource -owned by secondary process. +Each of ``spp_vf`` processes is managed with ``vf`` command. It is for +sending sub commands with specific ID called secondary ID for changing +configuration, assigning or releasing resources. + +Secondary ID is referred as ``--client-id`` which is given as an argument +while launching ``spp_vf``. It should be unique among all of secondary +processes including ``spp_nfv``, ``spp_vm`` and others. + +``vf`` 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 > sec [SID];[SUB_CMD] + spp > vf 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 ------- +* status +* component +* port +* classifier_table -Show running status and resources. +``spp_vf`` 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 ``vf SEC_ID;``. .. code-block:: console - spp > sec 1;status - recv:7:{Client ID 1 Idling - 1 - port id: 0,on,PHY,outport: none - port id: 1,on,PHY,outport: none - } - + spp > vf 1; # press TAB key + classifier_table component port status -component ---------- +It tries to complete all of possible arguments. However, ``spp_vf`` takes +also an arbitrary parameter which cannot be predicted, for example, name of +component MAC address. In this cases, ``spp_vf`` 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. -.. note:: - This command is only supported for spp_vf. +.. code-block:: console -Start or stop a component. SPP VF provides three types of components, -``forwarder``, ``classifier`` and ``merger``. + spp > vf 1; component st # press TAB key to show args starting 'st' + start stop + spp > vf 1; component start NAME # 'NAME' is shown with TAB after start + spp > vf 1; component start fw1 # replace 'NAME' with your favorite name + spp > vf 1; component start fw1 # then, press TAB to show core IDs + 5 6 7 8 -``component start`` command creates and starts a component with given -options. +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 ``fw1``. .. code-block:: console - spp > sec [SID];component start [NAME] [CORE_ID] [DIRECTIVE] - -* ``NAME`` is used as an identifier of the component. -* ``DIRECTIVE`` is a role of the component and corresponds to three types - of components. + spp > vf 1; port add RES_UID + spp > vf 1; port add ring:0 rx fw1 - * forward - * merge - * classifier_mac - -This is an example for starting three types of components. +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 ``forward`` because it is ready to run. .. code-block:: console - spp > sec 1;component start forwarder1 2 forward - spp > sec 1;component start merger1 3 merge - spp > sec 1;component start classifier1 4 classifier_mac + spp > vf 1; component start fw1 5 forward + Succeeded to start component 'fw1' on core:5 -``component stop`` command terminates a component with given options -same as ``component start`` command.. +It is also completed secondary IDs of ``spp_vf`` and it is helpful if you run +several ``spp_vf`` processes. .. code-block:: console - spp > sec [SID];component stop [NAME] [CORE_ID] [DIRECTIVE] + spp > vf # press TAB after space following 'vf' + 1; 3; # you find two spp_vf processes of sec ID 1, 3 -This is an example for stopping three types of components. +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 > sec 1;component stop forwarder1 2 forward - spp > sec 1;component stop merger1 3 merge - spp > sec 1;component stop classifier1 4 classifier_mac + spp > vf 1; compo # no candidate shown for wrong command + Invalid command "compo". -port ----- +.. _commands_spp_vf_status: -.. note:: - This command is only supported for spp_vf. - -Add a port to a component or delete it from. -SPP VF is able to treat VLAN tag by adding port with VLAN options. +status +------ -``port add`` command adds a port to a component with given options. +Show the information of worker threads and its resources. Status information +consists of three parts. .. code-block:: console - spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME] + spp > vf 1; status + Basic Information: + - client-id: 3 + - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4] + Classifier Table: + - C0:8E:CD:38:EA:A8, ring:4 + - C0:8E:CD:38:BC:E6, ring:3 + Components: + - core:5 'fw1' (type: forward) + - rx: ring:0 + - tx: ring:1 + - core:6 'mg' (type: merge) + - core:7 'cls' (type: classifier_mac) + - rx: ring:2 + - tx: ring:3 + - tx: ring:4 + - core:8 '' (type: unuse) + +``Basic Information`` is for describing attributes of ``spp_vf`` itself. +``client-id`` is a secondary ID of the process and ``ports`` is a list of +all of ports owned the process. + +``Classifier Table`` is a list of entries of ``classifier_mac`` worker thread. +Each of entry is a combination of MAC address and destination port which is +assigned to this thread. + +``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_vf_component: -* ``RES_ID`` is a resource ID and defined as a combination of resource - type and number separated with delimiter ``:``. - There are three types of resources. +component +--------- - * ``phy`` for physical NIC - * ``vhost`` for vhost PMD - * ``ring`` for ring PMD +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_vf``. The role of the worker is chosen from ``forward``, ``merge`` or +``classifier_mac``. -* ``PORT_TYPE`` is ``rx`` or ``tx``. -* ``NAME`` is used as an identifier of the component. +``forward`` role is for simply forwarding from source port to destination port. +On the other hands, ``merge`` role is for receiving packets from multiple ports +as N:1 communication, or ``classifier_mac`` role is for sending packet to +multiple ports by referring MAC address as 1:N communication. -This is an example for adding port ``phy:0`` to ``classifier1`` as -``rx`` and to ``merger1`` as ``tx``. +You are required to give an arbitrary name with as an ID for specifying the role. +This name is also used while releasing the role. .. code-block:: console - spp > sec 1;port add phy:0 rx classifier1 - spp > sec 1;port add phy:0 tx merger1 + # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME' + spp > vf SEC_ID; component start NAME CORE_ID ROLE + + # release worker 'NAME' from the role + spp > vf SEC_ID; component stop NAME -For VLAN support, you need to add options for ``port add`` command. -To add VLAN tag, additional option ``add_vlantag`` with its options -``VID`` and ``PCP`` are required. +Here is some examples of assigning roles with ``component`` command. .. code-block:: console - spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME] add_vlantag [VID] [PCP] + # assign 'forward' role with name 'fw1' on core 2 + spp > vf 2; component start fw1 2 forward -* ``PCP`` (Priority Code Point) is an attribute for priority defined in - IEEE 802.1p standard. It is ranged from 0 to 7 and - 7 is the highest priority. + # assign 'merge' role with name 'mgr1' on core 3 + spp > vf 2; component start mgr1 3 merge -Or to delete VLAN tag, ``del_vlantag`` option is required. + # assign 'classifier_mac' role with name 'cls1' on core 4 + spp > vf 2; component start cls1 4 classifier_mac + +Or examples of releasing roles. .. code-block:: console - spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME] del_vlantag + # release roles + spp > vf 2; component stop fw1 + spp > vf 2; component stop mgr1 + spp > vf 2; component stop cls1 -This is an example for adding a port with ``add_vlantag`` or -``del_vlantag``. -In this case, add rx port to append VLAN ID 101 with PCP 3 and -tx port to append VLAN ID 102 with PCP3. -(1) Add VLAN tag +.. _commands_spp_vf_port: -.. code-block:: console +port +---- - spp > sec 1;port add phy:0 rx classifier1 add_vlantag 101 3 - spp > sec 1;port add phy:0 tx merger1 add_vlantag 102 3 +Add or delete a port to a worker. -(2) Delete VLAN tag +Adding port +~~~~~~~~~~~ .. code-block:: console - spp > sec 1;port add phy:0 rx classifier1 del_vlantag - spp > sec 1;port add phy:0 tx merger1 del_vlantag + spp > vf SEC_ID; port add RES_UID DIR NAME -``port del`` command deletes a port from a component with given options -same as ``port add`` command.. +``RES_UID`` is with replaced with resource UID such as ``ring:0`` or +``vhost:1``. ``spp_vf`` supports three types of port. -.. code-block:: console + * ``phy`` : Physical NIC + * ``ring`` : Ring PMD + * ``vhost`` : Vhost PMD - spp > sec [SID];port del [RES_ID] [PORT_TYPE] [NAME] +``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 deleting port added in previous example. +This is an example for adding ports to a classifer ``cls1``. In this case, +it is configured to receive packets from ``phy:0`` and send it to ``ring:0`` +or ``ring:1``. The destination is decided with MAC address of the packets +by referring the table. How to configure the table is described in +:ref:`classifier_table` command. .. code-block:: console - spp > sec 1;port del phy:0 rx classifier1 - spp > sec 1;port del phy:0 tx merger1 + # recieve from 'phy:0' + spp > vf 2; port add phy:0 rx cls1 + # send to 'ring:0' and 'ring:1' + spp > vf 2; port add ring:0 tx cls1 + spp > vf 2; port add ring:1 tx cls1 -classifier_table ----------------- +``spp_vf`` also supports VLAN features, adding or deleting VLAN tag. +It is used remove VLAN tags from incoming packets from outside of host +machine, or add VLAN tag to outgoing packets. -.. note:: - This command is only supported for spp_vf. +To configure VLAN features, use additional sub command ``add_vlantag`` +or ``del_vlantag`` followed by ``port`` sub command. -Register an entry as a combination of MAC address and resource ID -to classifier table. +To remove VLAN tag, simply add ``del_vlantag`` sub command without arguments. .. code-block:: console - spp > sec [SID];classifier_table add mac [MAC_ADDRESS] [RES_ID] + spp > vf SEC_ID; port add RES_UID DIR NAME del_vlantag -This is an example to register MAC address ``52:54:00:01:00:01`` -with resource ID ``ring:0``. +On the other hand, use ``add_vlantag`` which takes two arguments, +``VID`` and ``PCP``, for adding VLAN tag to the packets. .. code-block:: console - spp > sec 1;classifier_table add mac 52:54:00:01:00:01 ring:0 + spp > vf SEC_ID; port add RES_UID DIR NAME add_vlantag VID PCP -Here is another example in which using keyword ``default`` instead of -``52:54:00:01:00:01``. -``default`` is applied for packets which are not matched any of registered -MAC addresses. -In this case, all of not matched packets are sent to ``ring:0``. +``VID`` is a VLAN ID and ``PCP`` is a Priority Code Point defined in +`IEEE 802.1p +`_. +It is used for QoS by defining priority ranged from lowest prioroty +``0`` to the highest ``7``. + +Here is an example of use of VLAN features considering a use case of +a forwarder removes VLAN tag from incoming packets and another forwarder +adds VLAN tag before sending packet outside. .. code-block:: console - spp > sec 0;classifier_table add mac default ring:0 + # remove VLAN tag in forwarder 'fw1' + spp > vf 2; port add phy:0 rx fw1 del_vlantag + + # add VLAN tag with VLAN ID and PCP in forwarder 'fw2' + spp > vf 2; port add phy:1 tx fw2 add_vlantag 101 3 + +Deleting port +~~~~~~~~~~~~~ -Register an entry with a VLAN ID to classifier table. +Delete a port which is not used anymore. .. code-block:: console - spp > sec 1;classifier_table add vlan [VID] [MAC_ADDRESS] [RES_ID] + spp > sec SEC_ID; port del RES_UID DIR NAME -This is an example to register MAC address ``52:54:00:01:00:01`` -with VLAN ID and resource ID ``ring:0``. +It is same as the adding port, but no need to add additional sub command +for VLAN features. + +Here is an example. + +.. code-block:: console + + # delete rx port 'ring:0' from 'cls1' + spp > vf 2; port del rx cls1 + + # delete tx port 'vhost:1' from 'mgr1' + spp > vf 2; port del vhost:1 tx mgr1 + + +.. _commands_spp_vf_classifier_table: + +classifier_table +---------------- + +Register an entry of a combination of MAC address and port to +a table of classifier. .. code-block:: console - spp > sec 0;classifier_table add vlan 101 52:54:00:01:00:01 ring:0 + # add entry + spp > vf SEC_ID; classifier_table add mac MAC_ADDR RES_UID + + # delete entry + spp > vf SEC_ID; classifier_table del mac [MAC_ADDRESS] [RES_ID] -Here is another example in which using keyword ``default`` instead of -``52:54:00:01:00:01``. -``default`` is applied for packets which are not matched any of registered -MAC addresses for specified VLAN ID. -In this case, all of not matched packets are sent to ``ring:0``. +This is an example to register MAC address ``52:54:00:01:00:01`` +with port ``ring:0``. .. code-block:: console - spp > sec 0;classifier_table add vlan 101 default ring:1 + spp > vf 1; classifier_table add mac 52:54:00:01:00:01 ring:0 -Delete an entry. +Classifier supports the ``default`` entry for packets which does not +match any of entries in the table. If you assign ``ring:1`` as default, +simply specify ``default`` instead of MAC address. .. code-block:: console - spp > sec 1;classifier_table add del [MAC_ADDRESS] [RES_ID] + spp > vf 1; classifier_table add mac default ring:1 -This is an example to delete an entry for port ``ring:0``. +``classifier_table`` sub command also supports VLAN features as similar +to ``port``. .. code-block:: console - spp > sec 1;classifier_table del mac 52:54:00:01:00:01 ring:0 + # add entry with VLAN features + spp > vf SEC_ID; classifier_table add vlan VID MAC_ADDR RES_UID -Delete an entry with a VLAN ID. + # delete entry of VLAN + spp > vf SEC_ID; classifier_table del vlan VID MAC_ADDR RES_UID + +Here is an example for adding entries. .. code-block:: console - spp > sec 1;classifier_table del vlan [VID] [MAC_ADDRESS] [RES_ID] + # add entry with VLAN tag + spp > vf 1; classifier_table add vlan 101 52:54:00:01:00:01 ring:0 + + # add entry of default with VLAN tag + spp > vf 1; classifier_table add vlan 101 default ring:1 -This is an example to delete an entry with VLAN ID 101. +Delete an entryThis is an example to delete an entry for port ``ring:0``. .. code-block:: console - spp > sec 0;classifier_table del vlan 101 52:54:00:01:00:01 ring:0 + # delete entry with VLAN tag + spp > vf 1; classifier_table del vlan 101 52:54:00:01:00:01 ring:0 -- 2.13.1