[v6,33/33] doc: add trace library guide
Checks
Commit Message
From: Jerin Jacob <jerinj@marvell.com>
Add programmar's guide for trace library support.
Signed-off-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Sunil Kumar Kori <skori@marvell.com>
---
MAINTAINERS | 1 +
doc/guides/prog_guide/index.rst | 1 +
doc/guides/prog_guide/trace_lib.rst | 346 +++++++++++++++++++++++++
doc/guides/rel_notes/release_20_05.rst | 9 +
4 files changed, 357 insertions(+)
create mode 100644 doc/guides/prog_guide/trace_lib.rst
Comments
Hi,
Below is a doc review.
General comment: it is better to split lines after punctuation signs
in order to make future patches easier to read.
19/04/2020 12:01, jerinj@marvell.com:
> +DPDK tracing library features
> +-----------------------------
> +
> +- A framework to add tracepoints in control and fast APIs with minimum impact on
fast, you mean fast path?
> + performance. Typical trace overhead is ~20 cycles and instrumentation
> + overhead is 1 cycle.
> +- Enable and disable the tracepoints at runtime.
> +- Save the trace buffer to the filesystem at any point in time.
> +- Supports ``overwrite`` and ``discard`` trace mode operations.
> +- String-based tracepoint object lookup.
> +- Enable and disable a set of tracepoints based on regular expression and/or
> + globbing.
> +- Generate trace in ``common trace format(CTF)``. ``CTF`` is an open-source trace
common trace format(CTF) -> Common Trace Format (CTF)
> + format and it is compatible with ``LTTng``.
it is -> is
> + For detailed information, refer `Common Trace Format <https://diamon.org/ctf/>`_
refer -> refer to
> +
> +How to add a tracepoint?
> +------------------------
> +
> +This section steps you through the details of adding a simple tracepoint.
> +
> +.. _create_provider_header_file:
> +
> +Create the tracepoint provider header file
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. code-block:: c
> +
> + #include <rte_trace_point.h>
> +
> + RTE_TRACE_POINT(app_trace_string,
> + RTE_TRACE_POINT_ARGS(const char *str),
> + rte_trace_point_emit_string(str);
> + )
> +
> +The above macro creates ``app_trace_string`` tracepoint. The user can choose
> +any name for the tracepoint. However, when adding the tracepoint in the DPDK
> +library, the ``rte_trace_lib_<library_name>_[<domain>]_<name>`` naming convention
> +must be followed. The examples are ``rte_trace_lib_eal_generic_str``,
> +``rte_trace_lib_mempool_create``.
If adding a symbol in a lib, the namespace should the lib's namespace.
So the format must be rte_<library_name>_trace_[<domain>_]<name>.
Examples will become rte_eal_trace_generic_str and rte_mempool_trace_create.
> +
> +When ``RTE_TRACE_POINT`` expands for above the definition, it creates the
expands for above the definition -> expands from above definition
> +following function template. The consumer of this tracepoint can invoke
> +``app_trace_string(const char *str)`` to emit the trace event to the trace buffer.
This last sentence should be below the following code block.
> +
> +.. code-block:: c
> +
> + static __rte_always_inline void
> + app_trace_string(const char *str)
> + {
> + /* Trace subsystem hooks */
> + ...
> + rte_trace_point_emit_string(str);
> + }
> +
> +Register the tracepoint
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. code-block:: c
> +
> + #define RTE_TRACE_POINT_REGISTER_SELECT /* Select trace point register macros */
I don't understand this #define.
> +
> + #include <tracepoint_provider_header_file.h>
Is it the header file created in previous section?
A reference is missing. Maybe call it my_tracepoint_provider.h
> +
> + RTE_TRACE_POINT_DEFINE(app_trace_string);
> +
> + RTE_INIT(eal_trace_init)
Why "eal" in the name of this constructor?
> + {
> + RTE_TRACE_POINT_REGISTER(app_trace_string, app.trace.string);
> + }
> +
> +The above code snippet registers the ``app_trace_string`` tracepoint to
> +trace library. Here, the ``tracepoint_provider_header_file.h`` is the header file
> +that user created in the first step :ref:`create_provider_header_file`
> +
> +The second argument for the ``RTE_TRACE_POINT_REGISTER`` is the name for the
> +tracepoint. This string will be used for tracepoint lookup or regular expression
> +and/or glob based tracepoint operations. There is no requirement for
> +the trace function and its name to be similar. However, it is recommended to
> +have a similar name for a better naming convention.
> +
> +The user must register the tracepoint before the ``rte_eal_init`` invocation.
> +The user can use the ``RTE_INIT`` construction scheme to achieve the same.
> +
> +.. note::
> +
> + The ``RTE_TRACE_POINT_DEFINE`` defines the tracepoint of ``rte_trace_point_t``
> + type. When the tracepoint defined in the shared library, the user must
tracepoint defined in the shared library -> tracepoint is defined in a shared library
> + update the ``.map`` file with ``__<trace_function_name>`` symbol.
All libraries can be shared, so it should be reworded to make it mandatory.
> + For example, ``__app_trace_string`` will be the exported symbol in the
> + above example.
> +
> +Datapath tracepoint
> +-------------------
> +
> +In order to avoid performance impact for the datapath tracepoint, the library
> +introduced ``RTE_TRACE_POINT_FP``. When adding the tracepoint in datapath code,
> +The user must use ``RTE_TRACE_POINT_FP`` instead of ``RTE_TRACE_POINT``.
> +
> +``RTE_TRACE_POINT_FP`` is compiled out by default and it can be enabled using
> +``CONFIG_RTE_ENABLE_TRACE_FP`` configuration parameter. The ``enable_trace_fp``
> +build option shall be used for the same for meson build .The application may use
Typo with the spaces around the dot.
> +``rte_trace_fp_is_enabled()`` to get status of ``CONFIG_RTE_ENABLE_TRACE_FP``.
> +
> +Event record mode
> +-----------------
> +
> +Event record mode is an attribute of trace buffers. Trace library exposes the
> +following modes:
> +
> +.. _table_event_record_modes:
> +
> +.. table:: Event record modes.
> +
> + +-----------+-----------------------------------------------------------------+
> + | Mode | Description |
> + | | |
> + +===========+=================================================================+
> + | Overwrite | When trace buffer is full, new trace events overwrites the |
> + | | existing captured events in the trace buffer. |
> + +-----------+-----------------------------------------------------------------+
> + | Discard | When trace buffer is full, new trace events will be discarded. |
> + +-----------+-----------------------------------------------------------------+
Please don't use a table for definition.
It will be better rendered as a definition list:
https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
> +The mode can be configured either using EAL command line parameters on
Which EAL option?
> +application boot up or use ``rte_trace_mode_set()`` API to configure at runtime.
> +Refer :doc:`../linux_gsg/linux_eal_parameters` for EAL command line options.
> +
> +Trace file location
> +-------------------
> +
> +On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
> +the trace buffers to the filesystem. By default, library saves trace files at
> +``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``. It can be overridden by
Please don't create a specific directory, but use rte_eal_get_runtime_dir().
> +the ``--trace-dir=<directory path>`` EAL command line option.
I don't think this option is needed.
XDG_RUNTIME_DIR environment variable can do the same.
> +
> +For more information, refer :doc:`../linux_gsg/linux_eal_parameters` for trace
> +EAL command line options.
> +
> +
> +View and analyze the recorded events
> +------------------------------------
> +
> +Once the trace directory is available, the user can view/inspect the recorded events.
> +
> +There are many tools you can use to read DPDK traces:
> +
> +1. ``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
grep ed -> grep'ed
> +opensource ``Babeltrace`` project.
opensource -> Open Source
Why quotes around Babeltrace?
> +
> +2. ``Trace Compass`` is a graphical user interface for viewing and analyzing any
> +type of logs or traces, including DPDK traces.
The rest looks good, thanks.
On Tue, Apr 21, 2020 at 5:49 AM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> Hi,
>
> Below is a doc review.
> General comment: it is better to split lines after punctuation signs
> in order to make future patches easier to read.
Thanks for the review.
Except below two comments, Everything else accepted and fixed in v7.
> > +
> > +Register the tracepoint
> > +~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +.. code-block:: c
> > +
> > + #define RTE_TRACE_POINT_REGISTER_SELECT /* Select trace point register macros */
>
> I don't understand this #define.
See the headerfile.
/**
* Macro to select rte_trace_point_emit_* definition for trace register function
*
* rte_trace_point_emit_* emits different definitions for trace function.
* Application must define RTE_TRACE_POINT_REGISTER_SELECT before including
* rte_trace_point.h in the C file where RTE_TRACE_POINT_REGISTER used.
*
* @see RTE_TRACE_POINT_REGISTER
*/
#define RTE_TRACE_POINT_REGISTER_SELECT
>
> > +Trace file location
> > +-------------------
> > +
> > +On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
> > +the trace buffers to the filesystem. By default, library saves trace files at
> > +``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``. It can be overridden by
>
> Please don't create a specific directory, but use rte_eal_get_runtime_dir().
Trace files are huge in size, /var/run is not the correct place to store it.
User needs to have control over where the trace file generated.It can
be different than rte_eal_get_runtime_dir().
Multiple DPDK application running case has been taken care of by using
eal_get_hugefile_prefix() in trace session creation.
> > +the ``--trace-dir=<directory path>`` EAL command line option.
>
> I don't think this option is needed.
> XDG_RUNTIME_DIR environment variable can do the same.
21/04/2020 07:47, Jerin Jacob:
> On Tue, Apr 21, 2020 at 5:49 AM Thomas Monjalon <thomas@monjalon.net> wrote:
> >
> > Hi,
> >
> > Below is a doc review.
> > General comment: it is better to split lines after punctuation signs
> > in order to make future patches easier to read.
>
> Thanks for the review.
> Except below two comments, Everything else accepted and fixed in v7.
>
> > > +
> > > +Register the tracepoint
> > > +~~~~~~~~~~~~~~~~~~~~~~~
> > > +
> > > +.. code-block:: c
> > > +
> > > + #define RTE_TRACE_POINT_REGISTER_SELECT /* Select trace point register macros */
> >
> > I don't understand this #define.
>
> See the headerfile.
> /**
> * Macro to select rte_trace_point_emit_* definition for trace register function
> *
> * rte_trace_point_emit_* emits different definitions for trace function.
> * Application must define RTE_TRACE_POINT_REGISTER_SELECT before including
> * rte_trace_point.h in the C file where RTE_TRACE_POINT_REGISTER used.
> *
> * @see RTE_TRACE_POINT_REGISTER
> */
> #define RTE_TRACE_POINT_REGISTER_SELECT
Please add an explanation in the doc about why it is needed, the rationale.
> > > +Trace file location
> > > +-------------------
> > > +
> > > +On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
> > > +the trace buffers to the filesystem. By default, library saves trace files at
> > > +``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``. It can be overridden by
> >
> > Please don't create a specific directory, but use rte_eal_get_runtime_dir().
>
> Trace files are huge in size, /var/run is not the correct place to store it.
> User needs to have control over where the trace file generated.It can
> be different than rte_eal_get_runtime_dir().
> Multiple DPDK application running case has been taken care of by using
> eal_get_hugefile_prefix() in trace session creation.
At least, the default directory should be the runtime_dir I think.
It's not good to create new directories without user approval.
> > > +the ``--trace-dir=<directory path>`` EAL command line option.
> >
> > I don't think this option is needed.
> > XDG_RUNTIME_DIR environment variable can do the same.
On Tue, Apr 21, 2020 at 2:41 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> 21/04/2020 07:47, Jerin Jacob:
> > On Tue, Apr 21, 2020 at 5:49 AM Thomas Monjalon <thomas@monjalon.net> wrote:
> > >
> > > Hi,
> > >
> > > Below is a doc review.
> > > General comment: it is better to split lines after punctuation signs
> > > in order to make future patches easier to read.
> >
> > Thanks for the review.
> > Except below two comments, Everything else accepted and fixed in v7.
> >
> > > > +
> > > > +Register the tracepoint
> > > > +~~~~~~~~~~~~~~~~~~~~~~~
> > > > +
> > > > +.. code-block:: c
> > > > +
> > > > + #define RTE_TRACE_POINT_REGISTER_SELECT /* Select trace point register macros */
> > >
> > > I don't understand this #define.
> >
> > See the headerfile.
> > /**
> > * Macro to select rte_trace_point_emit_* definition for trace register function
> > *
> > * rte_trace_point_emit_* emits different definitions for trace function.
> > * Application must define RTE_TRACE_POINT_REGISTER_SELECT before including
> > * rte_trace_point.h in the C file where RTE_TRACE_POINT_REGISTER used.
> > *
> > * @see RTE_TRACE_POINT_REGISTER
> > */
> > #define RTE_TRACE_POINT_REGISTER_SELECT
>
> Please add an explanation in the doc about why it is needed, the rationale.
As you wish.
>
>
> > > > +Trace file location
> > > > +-------------------
> > > > +
> > > > +On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
> > > > +the trace buffers to the filesystem. By default, library saves trace files at
> > > > +``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``. It can be overridden by
> > >
> > > Please don't create a specific directory, but use rte_eal_get_runtime_dir().
> >
> > Trace files are huge in size, /var/run is not the correct place to store it.
> > User needs to have control over where the trace file generated.It can
> > be different than rte_eal_get_runtime_dir().
> > Multiple DPDK application running case has been taken care of by using
> > eal_get_hugefile_prefix() in trace session creation.
>
> At least, the default directory should be the runtime_dir I think.
> It's not good to create new directories without user approval.
Nobody adds log or trace files in /var/run. It is the place to store
pid specific low volume information.
I checked the LTTng, it creates the $HOME/lttng-traces/ as default.
So the current scheme looks good to me.
>
> > > > +the ``--trace-dir=<directory path>`` EAL command line option.
> > >
> > > I don't think this option is needed.
> > > XDG_RUNTIME_DIR environment variable can do the same.
>
>
>
@@ -200,6 +200,7 @@ M: Sunil Kumar Kori <skori@marvell.com>
F: lib/librte_eal/include/rte_trace*.h
F: lib/librte_eal/common/eal_common_trace*.c
F: lib/librte_eal/common/eal_trace.h
+F: doc/guides/prog_guide/trace_lib.rst
Memory Allocation
M: Anatoly Burakov <anatoly.burakov@intel.com>
@@ -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
new file mode 100644
@@ -0,0 +1,346 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(C) 2020 Marvell International Ltd.
+
+Trace Library
+=============
+
+Overview
+--------
+
+*Tracing* is a technique used to understand what goes on in a running software
+system. The software used for tracing is called a *tracer*, which is conceptually
+similar to a tape recorder. When recording, specific instrumentation points
+placed in the software source code generate events that are saved on a giant
+tape: a trace file. The trace file then later can be opened in *trace viewers* to
+visualize and analyze the trace events with timestamps and multi-core views.
+Such a mechanism will be useful for resolving a wide range of problems such as
+multi-core synchronization issues, latency measurements, finding out the
+post analyses information like CPU idle time, etc that would otherwise be
+extremely challenging.
+
+Tracing is often compared to *logging*. However, tracers and loggers are two
+different tools, serving two different purposes. Tracers are designed to record
+much lower-level events that occur much more frequently than log messages, often
+in the range of thousands per second, with very little execution overhead.
+Logging is more appropriate for a very high-level analysis of less frequent
+events: user accesses, exceptional conditions (errors and warnings, for
+example), database transactions, instant messaging communications, and such.
+Simply put, logging is one of the many use cases that can be satisfied with
+tracing.
+
+DPDK tracing library features
+-----------------------------
+
+- A framework to add tracepoints in control and fast APIs with minimum impact on
+ performance. Typical trace overhead is ~20 cycles and instrumentation
+ overhead is 1 cycle.
+- Enable and disable the tracepoints at runtime.
+- Save the trace buffer to the filesystem at any point in time.
+- Supports ``overwrite`` and ``discard`` trace mode operations.
+- String-based tracepoint object lookup.
+- Enable and disable a set of tracepoints based on regular expression and/or
+ globbing.
+- Generate trace in ``common trace format(CTF)``. ``CTF`` is an open-source trace
+ format and it is compatible with ``LTTng``.
+ For detailed information, refer `Common Trace Format <https://diamon.org/ctf/>`_
+
+How to add a tracepoint?
+------------------------
+
+This section steps you through the details of adding a simple tracepoint.
+
+.. _create_provider_header_file:
+
+Create the tracepoint provider header file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ #include <rte_trace_point.h>
+
+ RTE_TRACE_POINT(app_trace_string,
+ RTE_TRACE_POINT_ARGS(const char *str),
+ rte_trace_point_emit_string(str);
+ )
+
+The above macro creates ``app_trace_string`` tracepoint. The user can choose
+any name for the tracepoint. However, when adding the tracepoint in the DPDK
+library, the ``rte_trace_lib_<library_name>_[<domain>]_<name>`` naming convention
+must be followed. The examples are ``rte_trace_lib_eal_generic_str``,
+``rte_trace_lib_mempool_create``.
+
+When ``RTE_TRACE_POINT`` expands for above the definition, it creates the
+following function template. The consumer of this tracepoint can invoke
+``app_trace_string(const char *str)`` to emit the trace event to the trace buffer.
+
+.. code-block:: c
+
+ static __rte_always_inline void
+ app_trace_string(const char *str)
+ {
+ /* Trace subsystem hooks */
+ ...
+ rte_trace_point_emit_string(str);
+ }
+
+Register the tracepoint
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ #define RTE_TRACE_POINT_REGISTER_SELECT /* Select trace point register macros */
+
+ #include <tracepoint_provider_header_file.h>
+
+ RTE_TRACE_POINT_DEFINE(app_trace_string);
+
+ RTE_INIT(eal_trace_init)
+ {
+ RTE_TRACE_POINT_REGISTER(app_trace_string, app.trace.string);
+ }
+
+The above code snippet registers the ``app_trace_string`` tracepoint to
+trace library. Here, the ``tracepoint_provider_header_file.h`` is the header file
+that user created in the first step :ref:`create_provider_header_file`
+
+The second argument for the ``RTE_TRACE_POINT_REGISTER`` is the name for the
+tracepoint. This string will be used for tracepoint lookup or regular expression
+and/or glob based tracepoint operations. There is no requirement for
+the trace function and its name to be similar. However, it is recommended to
+have a similar name for a better naming convention.
+
+The user must register the tracepoint before the ``rte_eal_init`` invocation.
+The user can use the ``RTE_INIT`` construction scheme to achieve the same.
+
+.. note::
+
+ The ``RTE_TRACE_POINT_DEFINE`` defines the tracepoint of ``rte_trace_point_t``
+ type. When the tracepoint defined in the shared library, the user must
+ update the ``.map`` file with ``__<trace_function_name>`` symbol.
+ For example, ``__app_trace_string`` will be the exported symbol in the
+ above example.
+
+Datapath tracepoint
+-------------------
+
+In order to avoid performance impact for the datapath tracepoint, the library
+introduced ``RTE_TRACE_POINT_FP``. When adding the tracepoint in datapath code,
+The user must use ``RTE_TRACE_POINT_FP`` instead of ``RTE_TRACE_POINT``.
+
+``RTE_TRACE_POINT_FP`` is compiled out by default and it can be enabled using
+``CONFIG_RTE_ENABLE_TRACE_FP`` configuration parameter. The ``enable_trace_fp``
+build option shall be used for the same for meson build .The application may use
+``rte_trace_fp_is_enabled()`` to get status of ``CONFIG_RTE_ENABLE_TRACE_FP``.
+
+Event record mode
+-----------------
+
+Event record mode is an attribute of trace buffers. Trace library exposes the
+following modes:
+
+.. _table_event_record_modes:
+
+.. table:: Event record modes.
+
+ +-----------+-----------------------------------------------------------------+
+ | Mode | Description |
+ | | |
+ +===========+=================================================================+
+ | Overwrite | When trace buffer is full, new trace events overwrites the |
+ | | existing captured events in the trace buffer. |
+ +-----------+-----------------------------------------------------------------+
+ | Discard | When trace buffer is full, new trace events will be discarded. |
+ +-----------+-----------------------------------------------------------------+
+
+The mode can be configured either using EAL command line parameters on
+application boot up or use ``rte_trace_mode_set()`` API to configure at runtime.
+Refer :doc:`../linux_gsg/linux_eal_parameters` for EAL command line options.
+
+Trace file location
+-------------------
+
+On ``rte_trace_save()`` or ``rte_eal_cleanup()`` invocation, the library saves
+the trace buffers to the filesystem. By default, library saves trace files at
+``$HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/``. It can be overridden by
+the ``--trace-dir=<directory path>`` EAL command line option.
+
+For more information, refer :doc:`../linux_gsg/linux_eal_parameters` for trace
+EAL command line options.
+
+
+View and analyze the recorded events
+------------------------------------
+
+Once the trace directory is available, the user can view/inspect the recorded events.
+
+There are many tools you can use to read DPDK traces:
+
+1. ``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.
+
+2. ``Trace Compass`` is a graphical user interface for viewing and analyzing any
+type of logs or traces, including DPDK traces.
+
+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 </path-to-trace-events/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/>
+
+``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 <https://www.eclipse.org/tracecompass/>`_
+
+Quick start
+-----------
+
+This section steps you through the details of generating trace and viewing it.
+
+- Start the dpdk-test::
+
+ echo "quit" | ./build/app/test/dpdk-test --no-huge --trace=.*
+
+- View the traces with babeltrace viewer::
+
+ babeltrace $HOME/dpdk-traces/rte-yyyy-mm-dd-[AP]M-hh-mm-ss/
+
+Implementation details
+----------------------
+
+As DPDK trace library is designed to generate traces that uses ``Common Trace
+Format (CTF)``. ``CTF`` specification consists of the 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 <https://diamon.org/ctf/>`_
+
+The implementation details broadly divided into the following areas:
+
+Trace metadata creation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Based on the ``CTF`` specification, One of a CTF trace's streams is mandatory:
+the metadata stream. It contains exactly what you would expect: data about the
+trace itself. The metadata stream contains a textual description of the binary
+layouts of all the other streams.
+
+This description is written using the Trace Stream Description Language (TSDL),
+a declarative language that exists only in the realm of CTF. The purpose of the
+metadata stream is to make CTF readers know how to parse a trace's binary
+streams of events without CTF specifying any fixed layout. The only stream
+layout known in advance is, in fact, the metadata stream's one.
+
+The internal ``trace_metadata_create()`` function generates the metadata.
+
+Trace memory
+~~~~~~~~~~~~
+
+The trace memory will be allocated through an internal function
+``__rte_trace_mem_per_thread_alloc()``. The trace memory will be allocated
+per thread to enable lock less trace-emit function. The memory for the
+trace memory for DPDK lcores will be allocated on ``rte_eal_init()`` if the trace
+is enabled through a EAL option. For non DPDK threads, on the first trace
+emission, the memory will be allocated.
+
+Trace memory layout
+~~~~~~~~~~~~~~~~~~~
+
+.. _table_trace_mem_layout:
+
+.. table:: Trace memory layout.
+
+ +-------------------+
+ | packet.header |
+ +-------------------+
+ | packet.context |
+ +-------------------+
+ | trace 0 header |
+ +-------------------+
+ | trace 0 payload |
+ +-------------------+
+ | trace 1 header |
+ +-------------------+
+ | trace 1 payload |
+ +-------------------+
+ | trace N header |
+ +-------------------+
+ | trace N payload |
+ +-------------------+
+
+packet.header
+^^^^^^^^^^^^^
+
+.. _table_packet_header:
+
+.. table:: Packet header layout.
+
+ +-------------------+
+ | uint32_t magic |
+ +-------------------+
+ | rte_uuid_t uuid |
+ +-------------------+
+
+packet.context
+^^^^^^^^^^^^^^
+
+.. _table_packet_context:
+
+.. table:: Packet context layout.
+
+ +----------------------+
+ | uint32_t thread_id |
+ +----------------------+
+ | char thread_name[32] |
+ +----------------------+
+
+trace.header
+^^^^^^^^^^^^
+
+.. _table_trace_header:
+
+.. table:: Packet context layout.
+
+ +----------------------+
+ | event_id [63:48] |
+ +----------------------+
+ | timestamp [47:0] |
+ +----------------------+
+
+The trace header is 64bit, it consists of 48bit of timestamp and 16bit event ID.
+
+The ``packet.header`` and ``packet.context`` will be written in the slow path
+at the time of trace memory creation. The ``trace.header`` and trace payout
+will be emitted when the trace function invoked.
@@ -81,6 +81,15 @@ New Features
by making use of the event device capabilities. The event mode currently supports
only inline IPsec protocol offload.
+* **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
-------------