[v3,7/7] doc: testpmd support event handling section

Message ID 20231106131128.33499-8-fengchengwen@huawei.com (mailing list archive)
State Deferred
Delegated to: Ferruh Yigit
Headers
Series fix race-condition of proactive error handling mode |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/loongarch-compilation success Compilation OK
ci/loongarch-unit-testing success Unit Testing PASS
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/intel-Functional success Functional PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-intel-Functional success Functional Testing PASS
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-sample-apps-testing success Testing PASS
ci/github-robot: build success github build: passed
ci/iol-compile-amd64-testing success Testing PASS
ci/iol-unit-amd64-testing success Testing PASS
ci/iol-unit-arm64-testing success Testing PASS
ci/iol-compile-arm64-testing success Testing PASS

Commit Message

fengchengwen Nov. 6, 2023, 1:11 p.m. UTC
  Add new section of event handling, which documented the ethdev and
device events.

Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
---
 doc/guides/testpmd_app_ug/event_handling.rst | 81 ++++++++++++++++++++
 doc/guides/testpmd_app_ug/index.rst          |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 doc/guides/testpmd_app_ug/event_handling.rst
  

Comments

lihuisong (C) Nov. 8, 2023, 3:03 a.m. UTC | #1
Acked-by: Huisong Li <lihuisong@huawei.com>

在 2023/11/6 21:11, Chengwen Feng 写道:
> Add new section of event handling, which documented the ethdev and
> device events.
>
> Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
> ---
>   doc/guides/testpmd_app_ug/event_handling.rst | 81 ++++++++++++++++++++
>   doc/guides/testpmd_app_ug/index.rst          |  1 +
>   2 files changed, 82 insertions(+)
>   create mode 100644 doc/guides/testpmd_app_ug/event_handling.rst
>
> diff --git a/doc/guides/testpmd_app_ug/event_handling.rst b/doc/guides/testpmd_app_ug/event_handling.rst
> new file mode 100644
> index 0000000000..1c39e0c486
> --- /dev/null
> +++ b/doc/guides/testpmd_app_ug/event_handling.rst
> @@ -0,0 +1,81 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2023 HiSilicon Limited.
> +
> +Event Handling
> +==============
> +
> +The ``testpmd`` application supports following two type event handling:
> +
> +ethdev events
> +-------------
> +
> +The ``testpmd`` provide options "--print-event" and "--mask-event" to control
> +whether display such as "Port x y event" when received "y" event on port "x".
> +This is named as default processing.
> +
> +This section details the support events, unless otherwise specified, only the
> +default processing is support.
> +
> +- ``RTE_ETH_EVENT_INTR_LSC``:
> +  If device started with lsc enabled, the PMD will launch this event when it
> +  detect link status changes.
> +
> +- ``RTE_ETH_EVENT_QUEUE_STATE``:
> +  Used when notify queue state event changed, for example: vhost PMD use this
> +  event report whether vring enabled.
> +
> +- ``RTE_ETH_EVENT_INTR_RESET``:
> +  Used to report reset interrupt happened, this event only reported when the
> +  PMD supports ``RTE_ETH_ERROR_HANDLE_MODE_PASSIVE``.
> +
> +- ``RTE_ETH_EVENT_VF_MBOX``:
> +  Used as a PF to process mailbox messages of the VFs to which the PF belongs.
> +
> +- ``RTE_ETH_EVENT_INTR_RMV``:
> +  Used to report device removal event. The ``testpmd`` will remove the port
> +  later.
> +
> +- ``RTE_ETH_EVENT_NEW``:
> +  Used to report port was probed event. The ``testpmd`` will setup the port
> +  later.
> +
> +- ``RTE_ETH_EVENT_DESTROY``:
> +  Used to report port was released event. The ``testpmd`` will changes the
> +  port's status.
> +
> +- ``RTE_ETH_EVENT_MACSEC``:
> +  Used to report MACsec offload related event.
> +
> +- ``RTE_ETH_EVENT_IPSEC``:
> +  Used to report IPsec offload related event.
> +
> +- ``RTE_ETH_EVENT_FLOW_AGED``:
> +  Used to report new aged-out flows was detected. Only valid with mlx5 PMD.
> +
> +- ``RTE_ETH_EVENT_RX_AVAIL_THRESH``:
> +  Used to report available Rx descriptors was smaller than the threshold. Only
> +  valid with mlx5 PMD.
> +
> +- ``RTE_ETH_EVENT_ERR_RECOVERING``:
> +  Used to report error happened, and PMD will do recover after report this
> +  event. The ``testpmd`` will stop packet forwarding when received the event.
> +
> +- ``RTE_ETH_EVENT_RECOVERY_SUCCESS``:
> +  Used to report error recovery success. The ``testpmd`` will restart packet
> +  forwarding when received the event.
> +
> +- ``RTE_ETH_EVENT_RECOVERY_FAILED``:
> +  Used to report error recovery failed. The ``testpmd`` will display one
> +  message to show which ports failed.
> +
> +.. note::
> +
> +   The ``RTE_ETH_EVENT_ERR_RECOVERING``, ``RTE_ETH_EVENT_RECOVERY_SUCCESS`` and
> +   ``RTE_ETH_EVENT_RECOVERY_FAILED`` only reported when the PMD supports
> +   ``RTE_ETH_ERROR_HANDLE_MODE_PROACTIVE``.
> +
> +device events
> +-------------
> +
> +Including two events ``RTE_DEV_EVENT_ADD`` and ``RTE_DEV_EVENT_ADD``, and
> +enabled only when the ``testpmd`` stated with options "--hot-plug".
> diff --git a/doc/guides/testpmd_app_ug/index.rst b/doc/guides/testpmd_app_ug/index.rst
> index 1ac0d25d57..3c09448c4e 100644
> --- a/doc/guides/testpmd_app_ug/index.rst
> +++ b/doc/guides/testpmd_app_ug/index.rst
> @@ -14,3 +14,4 @@ Testpmd Application User Guide
>       build_app
>       run_app
>       testpmd_funcs
> +    event_handling
  

Patch

diff --git a/doc/guides/testpmd_app_ug/event_handling.rst b/doc/guides/testpmd_app_ug/event_handling.rst
new file mode 100644
index 0000000000..1c39e0c486
--- /dev/null
+++ b/doc/guides/testpmd_app_ug/event_handling.rst
@@ -0,0 +1,81 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2023 HiSilicon Limited.
+
+Event Handling
+==============
+
+The ``testpmd`` application supports following two type event handling:
+
+ethdev events
+-------------
+
+The ``testpmd`` provide options "--print-event" and "--mask-event" to control
+whether display such as "Port x y event" when received "y" event on port "x".
+This is named as default processing.
+
+This section details the support events, unless otherwise specified, only the
+default processing is support.
+
+- ``RTE_ETH_EVENT_INTR_LSC``:
+  If device started with lsc enabled, the PMD will launch this event when it
+  detect link status changes.
+
+- ``RTE_ETH_EVENT_QUEUE_STATE``:
+  Used when notify queue state event changed, for example: vhost PMD use this
+  event report whether vring enabled.
+
+- ``RTE_ETH_EVENT_INTR_RESET``:
+  Used to report reset interrupt happened, this event only reported when the
+  PMD supports ``RTE_ETH_ERROR_HANDLE_MODE_PASSIVE``.
+
+- ``RTE_ETH_EVENT_VF_MBOX``:
+  Used as a PF to process mailbox messages of the VFs to which the PF belongs.
+
+- ``RTE_ETH_EVENT_INTR_RMV``:
+  Used to report device removal event. The ``testpmd`` will remove the port
+  later.
+
+- ``RTE_ETH_EVENT_NEW``:
+  Used to report port was probed event. The ``testpmd`` will setup the port
+  later.
+
+- ``RTE_ETH_EVENT_DESTROY``:
+  Used to report port was released event. The ``testpmd`` will changes the
+  port's status.
+
+- ``RTE_ETH_EVENT_MACSEC``:
+  Used to report MACsec offload related event.
+
+- ``RTE_ETH_EVENT_IPSEC``:
+  Used to report IPsec offload related event.
+
+- ``RTE_ETH_EVENT_FLOW_AGED``:
+  Used to report new aged-out flows was detected. Only valid with mlx5 PMD.
+
+- ``RTE_ETH_EVENT_RX_AVAIL_THRESH``:
+  Used to report available Rx descriptors was smaller than the threshold. Only
+  valid with mlx5 PMD.
+
+- ``RTE_ETH_EVENT_ERR_RECOVERING``:
+  Used to report error happened, and PMD will do recover after report this
+  event. The ``testpmd`` will stop packet forwarding when received the event.
+
+- ``RTE_ETH_EVENT_RECOVERY_SUCCESS``:
+  Used to report error recovery success. The ``testpmd`` will restart packet
+  forwarding when received the event.
+
+- ``RTE_ETH_EVENT_RECOVERY_FAILED``:
+  Used to report error recovery failed. The ``testpmd`` will display one
+  message to show which ports failed.
+
+.. note::
+
+   The ``RTE_ETH_EVENT_ERR_RECOVERING``, ``RTE_ETH_EVENT_RECOVERY_SUCCESS`` and
+   ``RTE_ETH_EVENT_RECOVERY_FAILED`` only reported when the PMD supports
+   ``RTE_ETH_ERROR_HANDLE_MODE_PROACTIVE``.
+
+device events
+-------------
+
+Including two events ``RTE_DEV_EVENT_ADD`` and ``RTE_DEV_EVENT_ADD``, and
+enabled only when the ``testpmd`` stated with options "--hot-plug".
diff --git a/doc/guides/testpmd_app_ug/index.rst b/doc/guides/testpmd_app_ug/index.rst
index 1ac0d25d57..3c09448c4e 100644
--- a/doc/guides/testpmd_app_ug/index.rst
+++ b/doc/guides/testpmd_app_ug/index.rst
@@ -14,3 +14,4 @@  Testpmd Application User Guide
     build_app
     run_app
     testpmd_funcs
+    event_handling