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