From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 0D47F432B0;
	Mon,  6 Nov 2023 14:15:17 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 33D1340C35;
	Mon,  6 Nov 2023 14:14:24 +0100 (CET)
Received: from szxga01-in.huawei.com (szxga01-in.huawei.com [45.249.212.187])
 by mails.dpdk.org (Postfix) with ESMTP id 95C66402EF
 for <dev@dpdk.org>; Mon,  6 Nov 2023 14:14:13 +0100 (CET)
Received: from dggpeml100024.china.huawei.com (unknown [172.30.72.55])
 by szxga01-in.huawei.com (SkyGuard) with ESMTP id 4SPBYg3TTnzrTxL;
 Mon,  6 Nov 2023 21:11:03 +0800 (CST)
Received: from localhost.localdomain (10.50.165.33) by
 dggpeml100024.china.huawei.com (7.185.36.115) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2507.31; Mon, 6 Nov 2023 21:14:12 +0800
From: Chengwen Feng <fengchengwen@huawei.com>
To: <thomas@monjalon.net>, <ferruh.yigit@amd.com>,
 <konstantin.ananyev@huawei.com>, <ajit.khaparde@broadcom.com>, Aman Singh
 <aman.deep.singh@intel.com>, Yuying Zhang <yuying.zhang@intel.com>
CC: <dev@dpdk.org>, <andrew.rybchenko@oktetlabs.ru>,
 <kalesh-anakkur.purayil@broadcom.com>, <Honnappa.Nagarahalli@arm.com>
Subject: [PATCH v3 7/7] doc: testpmd support event handling section
Date: Mon, 6 Nov 2023 13:11:27 +0000
Message-ID: <20231106131128.33499-8-fengchengwen@huawei.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20231106131128.33499-1-fengchengwen@huawei.com>
References: <20230301030610.49468-1-fengchengwen@huawei.com>
 <20231106131128.33499-1-fengchengwen@huawei.com>
MIME-Version: 1.0
Content-Type: text/plain
X-Originating-IP: [10.50.165.33]
X-ClientProxiedBy: dggems703-chm.china.huawei.com (10.3.19.180) To
 dggpeml100024.china.huawei.com (7.185.36.115)
X-CFilter-Loop: Reflected
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org

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
-- 
2.17.1