..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2010-2014 Intel Corporation


.. _commands_spp_pcap:

spp_pcap
========

``spp_pcap`` is a kind of SPP secondary process. It it introduced for
providing packet capture features.

Each of ``spp_pcap`` processes is managed with ``pcap`` command. It is for
sending sub commands with specific ID called secondary ID for starting or
stopping packet capture.

Secondary ID is referred as ``--client-id`` which is given as an argument
while launching ``spp_pcap``. It should be unique among all of secondary
processes including ``spp_nfv``, ``spp_vm`` and others.

``pcap`` 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.

.. code-block:: none

    spp > pcap 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
* start
* stop
* exit

``spp_pcap`` 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 ``pcap SEC_ID;``.

.. code-block:: none

    spp > pcap 1;  # press TAB key
    exit  start      status        stop

It tries to complete all of possible arguments.

.. code-block:: none

    spp > pcap 1; component st  # press TAB key to show args starting 'st'
    start  status  stop

If you are reached to the end of arguments, no candidate keyword is displayed.
It is a completed statement of ``start`` command, and TAB
completion does not work after ``start`` because it is ready to run.

.. code-block:: none

    spp > pcap 1; start
    Succeeded to start capture

It is also completed secondary IDs of ``spp_pcap`` and it is helpful if you
run several ``spp_pcap`` processes.

.. code-block:: none

    spp > pcap  # press TAB after space following 'pcap'
    1;  3;    # you find two spp_pcap 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:: none

    spp > pcap 1; ste  # no candidate shown for wrong command
    Invalid command "ste".


.. _commands_spp_pcap_status:

status
------

Show the information of worker threads of ``receiver`` and ``writer`` threads
and its resources.

.. code-block:: none

    spp > pcap 1; status
      - client-id: 1
      - status: idling
      - core:2 receive
        - rx: phy:0
      - core:3 write
        - filename:
      - core:4 write
        - filename:
      - core:5 write
        - filename:
      - core:6 write
        - filename:

``client-id`` is a secondary ID of the process and ``status`` shows
running status.

Each of lcore has a role of ``receive`` or ``write``.
``receiver`` has capture port as input and ``write`` has a capture file
as output, but the ``filename`` is empty while ``idling`` status
because capturing is not started yet.

If you start capturing, you can find each of ``writer`` threads has a
capture file. After capturing is stopped, ``filename`` is returned to
be empty again.

.. code-block:: none

    spp > pcap 2; status
      - client-id: 2
      - status: running
      - core:2 receive
        - rx: phy:0
      - core:3 write
        - filename: /tmp/spp_pcap.20190214161550.phy0.1.1.pcap.lz4
      - core:4 write
        - filename: /tmp/spp_pcap.20190214161550.phy0.2.1.pcap.lz4
      - core:5 write
        - filename: /tmp/spp_pcap.20190214161550.phy0.3.1.pcap.lz4
      - core:6 write
        - filename: /tmp/spp_pcap.20190214161550.phy0.4.1.pcap.lz4


.. _commands_spp_pcap_start:

start
-----

Start packet capture.

.. code-block:: none

    # start capture
    spp > pcap SEC_ID; start

Here is a example of starting capture.

.. code-block:: none

    # start capture
    spp > pcap 1; start
    Start packet capture.


.. _commands_spp_pcap_stop:

stop
----

Stop packet capture.

.. code-block:: none

   # stop capture
   spp > pcap SEC_ID; stop

Here is a example of stopping capture.

.. code-block:: none

    # stop capture
    spp > pcap 2; stop
    Start packet capture.


.. _commands_spp_pcap_exit:

exit
----

Terminate the ``spp_pcap``.

.. code-block:: none

    spp > pcap 1; exit