From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 87E40A058B; Wed, 25 Mar 2020 22:20:58 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id D69421C1CA; Wed, 25 Mar 2020 22:18:13 +0100 (CET) Received: from mx0b-0016f401.pphosted.com (mx0a-0016f401.pphosted.com [67.231.148.174]) by dpdk.org (Postfix) with ESMTP id 20C0E1C1C2 for ; Wed, 25 Mar 2020 22:18:11 +0100 (CET) Received: from pps.filterd (m0045849.ppops.net [127.0.0.1]) by mx0a-0016f401.pphosted.com (8.16.0.42/8.16.0.42) with SMTP id 02PLGGPQ008345; Wed, 25 Mar 2020 14:18:11 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding : content-type; s=pfpt0818; bh=VBQuP26IqDVpsgfuErugVOeK37rHo5bW4jiYZosFRp8=; b=Zj53voZf3zpZfwgNdguTboknEB0NbXnePbYqInxttz2o59GVChXd5lOIJkBvrurUdlkI EwDlSL5KCFgGMV0jl72YoRtcy1RjxKAwcJeRFnYrIWGRXPnUXmVK/ZpajYnaJROY5zRz AOqUVPwQR+yTuhCY03sWFrnxiLh5nc3qoIMwWjh1S1JVsggyjakaznuKcxNe5ijTJmUD 4TJ4Y3q/LQRmpfN6FsAp3pIpiS62OIndj/ZVWFl9lr8fhOpVz9HtgDI2744luLZ1yXez WlApR9YuUCN5SdnBtpsYbsSre1GTLREbf/H1Mrv9oyZ2SUz4acK3k3TcimrGIR9MzQVP GA== Received: from sc-exch01.marvell.com ([199.233.58.181]) by mx0a-0016f401.pphosted.com with ESMTP id 2ywg9ntf79-2 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Wed, 25 Mar 2020 14:18:11 -0700 Received: from DC5-EXCH01.marvell.com (10.69.176.38) by SC-EXCH01.marvell.com (10.93.176.81) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Wed, 25 Mar 2020 14:18:09 -0700 Received: from SC-EXCH01.marvell.com (10.93.176.81) by DC5-EXCH01.marvell.com (10.69.176.38) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Wed, 25 Mar 2020 14:18:08 -0700 Received: from maili.marvell.com (10.93.176.43) by SC-EXCH01.marvell.com (10.93.176.81) with Microsoft SMTP Server id 15.0.1497.2 via Frontend Transport; Wed, 25 Mar 2020 14:18:08 -0700 Received: from jerin-lab.marvell.com (jerin-lab.marvell.com [10.28.34.14]) by maili.marvell.com (Postfix) with ESMTP id 02BA63F7040; Wed, 25 Mar 2020 14:18:05 -0700 (PDT) From: To: John McNamara , Marko Kovacevic CC: , , , , , , Jerin Jacob Date: Thu, 26 Mar 2020 02:46:02 +0530 Message-ID: <20200325211603.240288-33-jerinj@marvell.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200325211603.240288-1-jerinj@marvell.com> References: <20200318190241.3150971-1-jerinj@marvell.com> <20200325211603.240288-1-jerinj@marvell.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.138, 18.0.645 definitions=2020-03-25_11:2020-03-24, 2020-03-25 signatures=0 Subject: [dpdk-dev] [PATCH v2 32/32] doc: add trace library guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" From: Sunil Kumar Kori Add programmar's guide for trace library support. Signed-off-by: Sunil Kumar Kori Signed-off-by: Jerin Jacob --- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/trace_lib.rst | 265 +++++++++++++++++++++++++ doc/guides/rel_notes/release_20_05.rst | 9 + 3 files changed, 275 insertions(+) create mode 100644 doc/guides/prog_guide/trace_lib.rst diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index fb250abf5..0daa08acc 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -35,6 +35,7 @@ Programmer's Guide lpm_lib lpm6_lib flow_classify_lib + trace_lib packet_distrib_lib reorder_lib ip_fragment_reassembly_lib diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst new file mode 100644 index 000000000..79753b9f5 --- /dev/null +++ b/doc/guides/prog_guide/trace_lib.rst @@ -0,0 +1,265 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(C) 2020 Marvell International Ltd. + +Trace Library +============= + +DPDK provides a tracing library that gives the ability to add tracepoints +in application to get runtime trace/debug information for control and fast +APIs with minimum impact on fast path performance. Typical trace overhead is +~20 cycles and instrumentation overhead is 1 cycle. + +Library mainly caters below mentioned use cases: + +- The DPDK provider will not have access to the DPDK customer applications. + Inbuilt tracer support will us enable to debug/analyze the slow path and + fast path DPDK API usage. + +- Provides a low overhead fast path multi-core PMD driver's debugging/analysis + infrastructure to fix the functional and performance issue(s). + +- Post trace analysis tools can provide various status across the system such + as cpu_idle() using the timestamp added in the trace. + +Below sections will provide detailed information about: + + - Trace a user application + - View and analyze the recorded events + +Trace a user application +------------------------ + +This section steps you through a simple example to trace an application. +A trace can be achieved using below mentioned steps: + +Define and register a tracepoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The application can define and register tracepoints either existing C file or +create a new file (say xyz_app_trace_point.c). Also, all the tracepoints must be +resolved before rte_eal_init i.e. tracepoints must be registered as constructor +using RTE_INIT interface. + +Following are the MACRO definition exposed by the trace Library to define and +register a tracepoint. + +.. code-block:: c + + #define RTE_TRACE_POINT_DEFINE(tp)\ + uint64_t __attribute__((section("__rte_trace_point"))) __##tp + + #define RTE_TRACE_POINT_REGISTER(trace, name, level)\ + __rte_trace_point_register(&__##trace, RTE_STR(name), RTE_LOG_ ## level,\ + (void (*)(void)) trace) + +Example tracepoint definition and registration + +.. code-block:: c + + RTE_TRACE_POINT_DEFINE(rte_trace_lib_eal_generic_str); /* Definition */ + + RTE_INIT(eal_trace_init) + { + /* Registration */ + RTE_TRACE_POINT_REGISTER(rte_trace_lib_eal_generic_str, + lib.eal.generic.str, INFO); + } + +For more details refer trace API documentation. +Defined tracepoint must be exported into corresponding .map file. + +.. Note:: + + A tracepoint is defined like __##tp i.e. __rte_trace_lib_eal_generic_str + for above example. Same must be updated into corresponding .map file. + +Define trace function to write events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After a successful tracepoint registration, the application must define a +trace function which solves three purposes: + + - Calculates the size of the event. + - Generate CTF metadata field string for the event. + - Emit the event to trace memory. + +A tracepoint can be classified as either a data path or a slow path tracepoint. +So based on that, the application must define tracepoint function using one of +the mentioned MACRO + +.. code-block:: c + + /* Define tracepoint function for slow path */ + #define RTE_TRACE_POINT(tp, args, ...)\ + __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__) + + /* Define tracepoint function for data path */ + #define RTE_TRACE_POINT_DP(tp, args, ...)\ + __RTE_TRACE_POINT(dp, tp, args, __VA_ARGS__) + +RTE_TRACE_POINT_DP is compiled out by default and can be enabled using +CONFIG_RTE_ENABLE_TRACE_DP configuration parameter. Also application can use +``rte_trace_is_dp_enabled`` to get current status of RTE_TRACE_POINT_DP. +For more details, refer DPDK Trace API documentation. + +Example tracepoint function definition + +.. code-block:: c + + /* Slow path tracepoint */ + RTE_TRACE_POINT( + rte_trace_lib_eal_generic_str, + RTE_TRACE_POINT_ARGS(const char *str), + rte_trace_ctf_string(str); + ) + + /* Data path tracepoint */ + RTE_TRACE_POINT_DP( + rte_trace_lib_eal_generic_str, + RTE_TRACE_POINT_ARGS(const char *str), + rte_trace_ctf_string(str); + ) + +Emit events to trace memory +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After trace function definition is ready to emit tracepoints. +To emit the event application needs to invoke tracepoint function, as defined +in the above steps, at the desired location. + +Below examples emit tracepoints in ``rte_eth_dev_configure`` to print a test +string: + +.. code-block:: c + + int + rte_eth_dev_configure(uint16_t port_id, uint16_t nb_rx_q, uint16_t nb_tx_q, + const struct rte_eth_conf *dev_conf) + { + struct rte_eth_dev *dev; + struct rte_eth_dev_info dev_info; + struct rte_eth_conf orig_conf; + int diag; + int ret; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -EINVAL); + + dev = &rte_eth_devices[port_id]; + + RTE_FUNC_PTR_OR_ERR_RET(*dev->dev_ops->dev_configure, -ENOTSUP); + + ... + + rte_trace_lib_eal_generic_str("tp_test_string"); + return ret; + } + +Generate CTF formatted metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +As of now emitted events just specify the debug information written by the +application but to view/analyze these events must be formatted into Common Trace +Format(CTF) so that any CTF compliant trace analysis tool can view those traces. + +Trace library exposes below API to write events to CTF formatted metadata file. + +.. code-block:: c + + int rte_trace_save(void); + +Currently library invokes this API implicitly during tear down and metadata file +is generated at either ``/root/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/`` or +at location if user has passed during command line(``say /tmp``) then +``/tmp/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/`` + +For more information, refer :doc:`../linux_gsg/linux_eal_parameters` for trace. + +View and analyze the recorded events +------------------------------------ +Once ``Trace a user application`` is completed, the user can view/inspect the +recorded events. + +There are many tools you can use to read DPDK traces: + + - ``babeltrace`` is a command-line utility that converts trace formats; it + supports the format that DPDK trace library produces, CTF, as well as a + basic text output that can be grep ed. The babeltrace command is part of the + opensource ``Babeltrace`` project. + + - ``Trace Compass`` is a graphical user interface for viewing and analyzing any + type of logs or traces, including DPDK traces. + +.. Note:: + + This section assumes that the trace library saved the traces, it recorded + during the previous tutorials, to their specified location. + + +Use the babeltrace command-line tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The simplest way to list all the recorded events of a trace is to pass its path +to babeltrace with no options:: + + babeltrace + +``babeltrace`` finds all traces recursively within the given path and prints all +their events, merging them in chronological order. + +You can pipe the output of the babeltrace into a tool like grep(1) for further +filtering. Below example grep the events for ``ethdev`` only:: + + babeltrace /tmp/my-dpdk-trace | grep ethdev + +You can pipe the output of babeltrace into a tool like wc(1) to count the +recorded events. Below example count the number of ``ethdev`` events:: + + babeltrace /tmp/my-dpdk-trace | grep ethdev | wc --lines + +Use the tracecompass GUI tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``Tracecompass`` is another tool to view/analyze the DPDK traces which gives +a graphical view of events. Like ``babeltrace``, tracecompass also provides +an interface to search for a particular event. To use ``tracecompass``, following are +the minimum required steps: + + - Install ``tracecompass`` to the localhost. Variants are available for Linux, + Windows, and OS-X. + - Launch ``tracecompass`` which will open a graphical window with trace + management interfaces. + - Open a trace using ``File->Open Trace`` option and select metadata file + which is to be viewed/analyzed. + +For more details, refer `Trace Compass `_ + +Core Concepts +------------- +As DPDK trace library is designed to generate traces that uses Common Trace +Format(CTF). CTF specification consist of following units to create a trace. + + - ``Stream`` Sequence of packets. + - ``Packet`` Header and one or more events. + - ``Event`` Header and payload. + +For detailed information, refer `Common Trace Format `_ + +Channel and trace memory +~~~~~~~~~~~~~~~~~~~~~~~~ +A channel is an object which is responsible for holding the trace memory. +The trace library creates the trace memory per thread to enable the lock-less +scheme to emit the event. When a DPDK tracer emits an event, it will be recorded +to the trace buffers that associated with that thread. + +Event record mode +~~~~~~~~~~~~~~~~~ +Event record mode is an attribute of trace buffers. Trace library exposes two +modes: + + - ``Overwrite`` This mode enables trace buffers to wrap around when trace buffer memory is full. + - ``Discard`` This mode enables trace buffers to discard when trace buffer memory is full. + +This mode can be enabled/disabled either using eal command line parameters or +DPDK trace library API to configure the mode. +Refer :doc:`../linux_gsg/linux_eal_parameters` and trace API documentation more +details. + +Metadata +~~~~~~~~ +Metadata defines the layout of event records so that trace analysis tool can +read the streams and show into the relevant format. +For more details, refer `Common Trace Format `_. diff --git a/doc/guides/rel_notes/release_20_05.rst b/doc/guides/rel_notes/release_20_05.rst index 000bbf501..4ca4ca366 100644 --- a/doc/guides/rel_notes/release_20_05.rst +++ b/doc/guides/rel_notes/release_20_05.rst @@ -62,6 +62,15 @@ New Features * Added support for matching on IPv4 Time To Live and IPv6 Hop Limit. +* **Added Trace Library and Tracepoints** + + A native implementation of ``common trace format(CTF)`` based trace library added + to provide the ability to add tracepoints in application/library to get runtime + trace/debug information for control and fast APIs with minimum impact on + fast path performance. Typical trace overhead is ~20 cycles and instrumentation + overhead is 1 cycle. Added tracepoints in ``EAL``, ``ethdev``, ``cryptodev``, + ``eventdev`` and ``mempool`` libraries for important functions. + Removed Items ------------- -- 2.25.1