From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E8C7642D7F; Wed, 28 Jun 2023 13:10:58 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 540FB42D2C; Wed, 28 Jun 2023 13:10:42 +0200 (CEST) Received: from NAM12-DM6-obe.outbound.protection.outlook.com (mail-dm6nam12on2063.outbound.protection.outlook.com [40.107.243.63]) by mails.dpdk.org (Postfix) with ESMTP id BFF5142BDA for ; Wed, 28 Jun 2023 13:10:38 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=YkzVVMVDTMqAB/n3R9m8eTIqKAyhTCBsMZ1OmJUpjTkHeIeG9ptktTvZ6e6mM976C6rCrG+aOtNuUQrD7/ZPvs5hXT3M6uh65g9EUFN+8cbzRsy99Zj0Uy2uY0ri81e52/ShW9l4RwPOGn/KBEYhp1f2UWEzYDBCJjjHNc7DCJCCw8CNwD6gLKApSzgRMwYjdIkqKn9NQ0TOXSUvEt0Mx+tMrqeAWK/0c8hMsa3p0/mREUVHkydaWWvMte0GQCbrqdhS9bJZtZqqxAZ0uGtNazbsHuSsg0LabNvFMLZrcfq1lIHwfuARz60EKdHCfdcq0gWcWSrCYYL0fw+Xk8PW3A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=Mnfie/REdgpuW91CbhKBwim+GyE4PDrDM5wQP+fa24Y=; b=bx/zcf4eNq6BQZcPsVr3Ly+FLQrKieQQR+X3IIw6OgMX8PMDnvjIp+qgU8ctsWRBsaXOCEQJUL3zoY5XVQ6tj1fdah0bAEcdUWt1i/ZQn7thjXJ1NLoKPxWH3T5MWuQnJ5/B+zTNu0jB24m4HEBohsZ5RN0kO1MNEYuyDBevvd5RiV66qhhlj66wdzp8JSx7oA6MUst23gCELjZCPLbE0RwTQAQq1ON5N2WMSy2NyhurzmjBZfBFzubfvv5s1J6os2OxAtFntweWoxphoN2dKV4z5IZYq/CJV9BXLUNoXAeFbWxjvkWbIw1eipTVf1hS4PTz7BeH3cKvxRZmfZdRqQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 216.228.117.161) smtp.rcpttodomain=dpdk.org smtp.mailfrom=nvidia.com; dmarc=pass (p=reject sp=reject pct=100) action=none header.from=nvidia.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=Nvidia.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=Mnfie/REdgpuW91CbhKBwim+GyE4PDrDM5wQP+fa24Y=; b=Sz3R2onR4EYEkfL4k1KCcQOLiuCF0XH/wmw09cuGa4VnNXbc7DPikGSGk1tN28ga1abLeWPV9kIyFJn1BDYbLEvp5wZEW5J5DOUSW++YFL7ZCP8RGzn33u50xiNrpAtrHgD804g6mx2p94GmsSfv/i3qOm3JASchl59i+GB9w+rtJDvX5eV+emhvhSdBfekdEqtbTIlxJ+GP/d6ZYVMhVzPsDZSaEJp5gprsbdDf/Av2wi/PgjAcpscmd2Id0xmoad7lPyWU2r2tIPU7AITXDWJ3AhZG5TtZ434RkFKO9rtwmYsfthStjZEZaL17Lok6jY8w5SEUeFRdMZZFfTHjBQ== Received: from BN8PR03CA0028.namprd03.prod.outlook.com (2603:10b6:408:94::41) by DM6PR12MB4880.namprd12.prod.outlook.com (2603:10b6:5:1bc::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6521.24; Wed, 28 Jun 2023 11:10:37 +0000 Received: from BN8NAM11FT093.eop-nam11.prod.protection.outlook.com (2603:10b6:408:94:cafe::8e) by BN8PR03CA0028.outlook.office365.com (2603:10b6:408:94::41) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6544.19 via Frontend Transport; Wed, 28 Jun 2023 11:10:36 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 216.228.117.161) smtp.mailfrom=nvidia.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=nvidia.com; Received-SPF: Pass (protection.outlook.com: domain of nvidia.com designates 216.228.117.161 as permitted sender) receiver=protection.outlook.com; client-ip=216.228.117.161; helo=mail.nvidia.com; pr=C Received: from mail.nvidia.com (216.228.117.161) by BN8NAM11FT093.mail.protection.outlook.com (10.13.177.22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6500.48 via Frontend Transport; Wed, 28 Jun 2023 11:10:36 +0000 Received: from rnnvmail201.nvidia.com (10.129.68.8) by mail.nvidia.com (10.129.200.67) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.5; Wed, 28 Jun 2023 04:10:23 -0700 Received: from nvidia.com (10.126.230.35) by rnnvmail201.nvidia.com (10.129.68.8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.37; Wed, 28 Jun 2023 04:10:22 -0700 From: Viacheslav Ovsiienko To: Subject: [PATCH v3 4/4] doc: add mlx5 datapath tracing feature description Date: Wed, 28 Jun 2023 14:09:58 +0300 Message-ID: <20230628110958.1403-5-viacheslavo@nvidia.com> X-Mailer: git-send-email 2.18.1 In-Reply-To: <20230628110958.1403-1-viacheslavo@nvidia.com> References: <20230420100803.494-1-viacheslavo@nvidia.com> <20230628110958.1403-1-viacheslavo@nvidia.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [10.126.230.35] X-ClientProxiedBy: rnnvmail201.nvidia.com (10.129.68.8) To rnnvmail201.nvidia.com (10.129.68.8) X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: BN8NAM11FT093:EE_|DM6PR12MB4880:EE_ X-MS-Office365-Filtering-Correlation-Id: 57457118-5185-4f96-6204-08db77c84ccd X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: DARtcftQxj2D9ug6/szMCexJBLNUWcKulcpuJUIh2wbPJ6m1ccfPupcRGtD/sSh9mr6w9Miy+kPtkCxGH/T1b6svyUbGPkUJhZ4YjXrmDByADlIOLZhOhkRzXMOmcREmKrphL3F0MwaR/OpCUBofmwyakCEWVYm7HbEPqKuxyQqo1u/S85F21yV4jsSAOmxNzwwtBkKlkK8fcoNqWeWow4G2tIrWDhmkErtCWmnCL6W/Bec/YINd7tf0O3RONFlrL4Rlb0Q5AZ+auLbBaO4z4VkGhyN2ovhbE2ikIuY2cLs9aP4IqfAlLHUjjPcylcXVlRqHAGbLIOEhwQXkG990LqqZJiwi1VBGpk38zSTi5E3Rwy/qWUQLZUyfpwIHn7v4qbwUnD8VqnuOwlA5tjbFObrxuZIeQY19sqnZCnIEMjX4mLtNZ5SFs5QWWlINMaNANXdUTsx3JR2IC9d6zH745u9lOdSwGd3sqfzJoofOHHCnYFRDa3VRbubmk+PJk+kTQF8T02De9191XDFPXggCfnPrDLHu+Y+maSh0/iR151tXaO5aAXOAH2e0M80MSp6CbmdmKtFS/alDd01ah/JyEBWMsESNdT7wiKNjxYr1KRR/5p3PHx/Enu+WApwGDwmgOKYBF0Niuyeo1ZMkoi73iurz2u5zgs5UgLDvB9Jlge17uQ7/gVCD5QYog747iEAz1PryZc0x6HO7XNDBi+/ZrYMYF5nzUMacC+uKXRZbxCwEM+B9WXkHUDj/n2I2TFcOrxLbHJoUCxn5Rw+4YhottreZ1m08CLJsAOz9A8+dDXg= X-Forefront-Antispam-Report: CIP:216.228.117.161; CTRY:US; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:mail.nvidia.com; PTR:dc6edge2.nvidia.com; CAT:NONE; SFS:(13230028)(4636009)(346002)(376002)(136003)(396003)(39860400002)(451199021)(36840700001)(46966006)(40470700004)(82310400005)(41300700001)(36860700001)(70206006)(966005)(47076005)(26005)(6666004)(83380400001)(7696005)(426003)(2616005)(336012)(478600001)(186003)(16526019)(6286002)(2906002)(1076003)(356005)(36756003)(40460700003)(5660300002)(70586007)(55016003)(82740400003)(7636003)(40480700001)(316002)(6916009)(8676002)(8936002)(86362001); DIR:OUT; SFP:1101; X-OriginatorOrg: Nvidia.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 28 Jun 2023 11:10:36.6718 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 57457118-5185-4f96-6204-08db77c84ccd X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=43083d15-7273-40c1-b7db-39efd9ccc17a; Ip=[216.228.117.161]; Helo=[mail.nvidia.com] X-MS-Exchange-CrossTenant-AuthSource: BN8NAM11FT093.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR12MB4880 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org The mlx5 provides the send scheduling on specific moment of time, and for the related kind of applications it would be extremely useful to have extra debug information - when and how packets were scheduled and when the actual sending was completed by the NIC hardware (it helps application to track the internal delay issues). The patch adds the documentation for feature usage. Signed-off-by: Viacheslav Ovsiienko --- doc/guides/nics/mlx5.rst | 77 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst index 0ed5cb5bc3..555f02ad2a 100644 --- a/doc/guides/nics/mlx5.rst +++ b/doc/guides/nics/mlx5.rst @@ -2081,3 +2081,80 @@ Set the flow engine to active(0) or standby(1) mode with specific flags:: This command works for software steering only. Default FDB jump should be disabled if switchdev is enabled. The mode will propagate to all the probed ports. + +Tx datapath tracing +^^^^^^^^^^^^^^^^^^^ + +The mlx5 provides the Tx datapath tracing capability with extra debug +information - when and how packets were scheduled and when the actual +sending was completed by the NIC hardware. The feature engages the +exisiting DPDK datapath tracing capability. + +Usage of the mlx5 Tx datapath tracing: + +#. Build DPDK application with enabled datapath tracking + + * The meson option should be specified: ``--enable_trace_fp=true`` + * The c_args shoudl be specified: ``-DALLOW_EXPERIMENTAL_API`` + + .. code-block:: console + + meson configure --buildtype=debug -Denable_trace_fp=true + -Dc_args='-DRTE_LIBRTE_MLX5_DEBUG -DRTE_ENABLE_ASSERT -DALLOW_EXPERIMENTAL_API' build + + meson configure --buildtype=release -Denable_trace_fp=true + -Dc_args='-DRTE_ENABLE_ASSERT -DALLOW_EXPERIMENTAL_API' build + +#. Configure the NIC + + If the sending completion timings are important the NIC should be configured + to provide realtime timestamps, the ``REAL_TIME_CLOCK_ENABLE`` NV settings + parameter should be configured to TRUE. + + .. code-block:: console + + mlxconfig -d /dev/mst/mt4125_pciconf0 s REAL_TIME_CLOCK_ENABLE=1 + +#. Run application with EAL parameters configuring the tracing in mlx5 Tx datapath + + * ``--trace=pmd.net.mlx5.tx`` - the regular expression enabling the tracepoints + with matching names at least "pmd.net.mlx5.tx" must be enabled to gather all + events needed to analyze mlx5 Tx datapath and its timings. By default all + tracepoints are disabled. + +#. Store the tracing data file with gathered tracing information + +#. Install or build the ``Babeltrace2`` Package + + The gathered trace data can be analyzed with a developed Python script. + To parse the trace, the data script uses the ``Babeltrace2`` library. + The package should be either installed or built from source code as + shown below. + + .. code-block:: console + + git clone https://github.com/efficios/babeltrace.git + cd babeltrace + ./bootstrap + ./configure -help + ./configure --disable-api-doc --disable-man-pages + --disable-python-bindings-doc --enbale-python-plugins + --enable-python-binding + +#. Run analyzing scrypt (in Python) to combine related events (packet firing and + completion) and see the output in human-readable view + + The analyzing script is located in the folder: ``./drivers/net/mlx5/tools`` + It requires Python3.6, ``Babeltrace2`` packages and it takes the only parameter + of trace data file. + + .. code-block:: console + + ./mlx5_trace.py /var/log/rte-2023-01-23-AM-11-52-39 + +#. Interpreting the Script Output Data + + All the timings are given in nanoseconds. + The list of Tx bursts per port/queue is presented in the output. + Each list element contains the list of built WQEs with specific opcodes, and + each WQE contains the list of the encompassed packets to send. -- 2.18.1