[PATCH] Adding tracing documentation in user manual
Vidushi Vashishth
reachvidu at gmail.com
Tue Jun 5 15:44:25 UTC 2018
Hi!
This is a rough skeleton of the tracing chapter in the user manual
documentation with some incomplete bits. I have covered the "to be
completed bits" in some of my blogs and that should not take much time to
finish. Let me know if you have suggestions.
Thanks!
Vidushi
On Tue, Jun 5, 2018 at 9:10 PM, Vidushi Vashishth <reachvidu at gmail.com>
wrote:
> ---
> user/index.rst | 2 +
> user/tracing/development.rst | 12 ++++++
> user/tracing/index.rst | 25 ++++++++++++
> user/tracing/introduction.rst | 90 ++++++++++++++++++++++++++++++
> +++++++++++++
> user/tracing/usecases.rst | 77 ++++++++++++++++++++++++++++++++++++
> 5 files changed, 206 insertions(+)
> create mode 100644 user/tracing/development.rst
> create mode 100644 user/tracing/index.rst
> create mode 100644 user/tracing/introduction.rst
> create mode 100644 user/tracing/usecases.rst
>
> diff --git a/user/index.rst b/user/index.rst
> index 8cbcd1b..a764fe8 100644
> --- a/user/index.rst
> +++ b/user/index.rst
> @@ -52,6 +52,8 @@ to the Community Project hosted at http://www.rtems.org/
> .
>
> tools/index
>
> + tracing/index
> +
> support/index
>
> glossary/index
> diff --git a/user/tracing/development.rst b/user/tracing/development.rst
> new file mode 100644
> index 0000000..ad74d8f
> --- /dev/null
> +++ b/user/tracing/development.rst
> @@ -0,0 +1,12 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: All rights reserved.
> +
> +.. _development:
> +
> +Tracing Development
> +*******************
> +
> +RTEMS trace is an open source project currently under development.
> +
> +This section can contain how to build the rtems-tools after making
> changes to the trace linker.
> diff --git a/user/tracing/index.rst b/user/tracing/index.rst
> new file mode 100644
> index 0000000..ad22439
> --- /dev/null
> +++ b/user/tracing/index.rst
> @@ -0,0 +1,25 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: All rights reserved.
> +
> +.. _tracing-framework:
> +
> +RTEMS Tracing Framework
> +***********************
> +.. index:: Tracing Framework
> +
> +RTEMS Tracing Framework is an on-target software based system which helps
> track
> +the ongoings inside applications, 3rd party packages and the kernel in
> real time.
> +
> +Software based tracing is a complex process which requires components on
> both the
> +target and the host to work together. However its portability across all
> architectures
> +and board support packages makes it a useful asset. A key requirement in
> RTEMS trace process
> +is to take existing code in compiled format (ELF) and instrument it in
> order to log various events
> +and records in real time. However instrumenting of the code for tracing
> should happen without rebuilding
> +the code from the source and without annotating the source with trace
> code.
> +
> +.. toctree::
> +
> + introduction
> + usecases
> + development
> diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst
> new file mode 100644
> index 0000000..3314447
> --- /dev/null
> +++ b/user/tracing/introduction.rst
> @@ -0,0 +1,90 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: All rights reserved.
> +
> +.. _introduction:
> +
> +Introduction to Tracing
> +***********************
> +
> +Tracing is an important function which has several applications including
> identification of
> +complex threading, detection of deadlocks, tracing functions along with
> their argument values,
> +and return values through progression of several function calls and audit
> the performance of an
> +application according to required specifications.
> +
> +RTEMS tracing framework is under development and welcomes contribution by
> users.
> +
> +RTEMS has the following trace components:
> +
> +- RTEMS Trace Linker
> +- Capture Engine
> +- Common Trace Format Integration
> +
> +.. note::
> +
> + I could create separate pages to explain the aforementioned
> components in detail.
> +
> +
> +RTEMS trace framework can currently function using the following methods:
> +
> +RTEMS Trace Using Trace Buffering
> +=================================
> +
> +To be completed
> +
> +RTEMS Trace Using Printk
> +========================
> +
> +To be completed
> +
> +RTEMS Trace Using CTF
> +=====================
> +
> +`Common Trace Format <http://diamon.org/ctf/>`_ is a binary trace format
> which is fast to write
> +and has great flexibility. It allows traces to be developed by bare-metal
> applications or by any
> +other C/C++ system. RTEMS tracing framework can benefit from these
> features of CTF.
> +
> +A typical CTF *trace* consists of multiple *streams* of binary *events*.
> It is upto us how many
> +streams we want to divide our tracer generated events into. The
> *metadata* stream is a mandatory
> +stream which describes the layout of all the other streams in a trace.
> This metadata stream is written
> +using *Trace Stream Description Language* (TSDL).
> +
> +A binary *stream* is further a concatenation of several packets each
> containing the following:
> +
> +- A header
> +- An optional context
> +- A set of concatenated events each containing:
> + - A header
> + - A stream-specific context
> + - An event-specific context
> + - A payload
> +
> +This method of tracing is currently under development and can utilise the
> following 3rd party package:
> +
> +Babeltrace
> +----------
> +
> +Babeltrace is an open source trace format converter which can be used to
> convert RTEMS traces into CTF.
> +It is also a reference parser implementation of CTF. Babeltrace currently
> supports the following output
> +formats for traces:
> +
> +- Text
> +- CTF
> +- CTF-metadata
> +- Dummy
> +- lttng-live
> +
> +Babeltrace comes in the form of a library, python bindings (python3) and
> command line tool called ``babeltrace``.
> +To install babeltrace on your host you can follow one of the following
> methods:
> +
> +Using Distribution Packages:
> +
> +1) On ubuntu/debian run: ``sudo apt-get install babeltrace``
> +
> +2) On fedora run: ``sudo yum install babeltrace``
> +
> +3) On Arch linux run: ``yaourt -S babeltrace`` or ``yaourt -S
> babeltrace-git`` for the latest git version
> +
> +
> +You can also build from source using tarballs or git repositories of
> babeltrace. Refer to http://diamon.org/babeltrace/
> +for further details.
> diff --git a/user/tracing/usecases.rst b/user/tracing/usecases.rst
> new file mode 100644
> index 0000000..323fe15
> --- /dev/null
> +++ b/user/tracing/usecases.rst
> @@ -0,0 +1,77 @@
> +.. comment SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: All rights reserved.
> +
> +.. _usecases:
> +
> +Tracing Use Cases
> +*****************
> +
> +Following are the use cases of the tracing framework that are currently
> under development:
> +
> +Function Tracing
> +================
> +
> +Tracing the entry and exit of a function as well as the values of the
> arguments and
> +return values can prove to be an important application for the tracing
> framework.
> +
> +As a start to the development of function tracing using CTF we can work
> on the fileio
> +sample testsuit and trace all the calls to malloc, calloc, free and
> realloc functions.
> +Along with the calls made to these functions the trace must also capture
> the values of
> +their arguments at entry and the return values at function exit. As an
> example of an application
> +having the following progression of function calls:
> +
> +.. code-block:: c
> +
> + #include <stdlib.h>
> + int main(int argc, char** argv)
> + {
> + int* a = malloc(sizeof(int));
> + free(a);
> + a = calloc(1, sizeof(int));
> + return 0;
> + }
> +
> +
> +The trace of such an application must be output of the following kind:
> +
> +.. code-block:: shell
> +
> + Timestamp1 entry of malloc > argument value
> + Timestamp2 exit of malloc < return value
> + Timestamp3 entry of free > argument value
> + Timestamp4 exit of free < return value (null)
> + Timestamp5 entry of calloc > argument1 value, argument2 value
> + Timestamp6 exit of calloc < return value1
> +
> +There could be additional coulmns of details including current priority,
> task state etc.
> +
> +
> +Tracing Thread Operations
> +=========================
> +
> +Real time applications inherently utilise parallel programming which
> entails several
> +tasks executing simulataneously and competing for common resources. On
> single processor systems
> +the CPU performs context switching between each of these tasks rapidly.
> By tracing the creation and
> +termination of tasks as well as the context swicthes between them one can
> possibly identify probable race
> +conditions or complex threading operations.
> +
> +A sample trace tracking two tasks Ta and Tb could have an output of the
> following kind:
> +
> +.. code-block:: shell
> +
> + Timestamp1 taskid Ta CREATED
> + Timestamp1 taskid Ta SWITCHED-IN
> + Timestamp1 taskid Ta BEGIN
> + Timestamp1 taskid Tb CREATED
> + Timestamp1 taskid Ta SWITCHED-OUT
> + Timestamp1 taskid Tb SWITCHED-IN
> + Timestamp1 taskid Tb BEGIN
> + Timestamp1 taskid Tb SWITCHED-OUT
> + Timestamp1 taskid Tb TERMINATED
> + Timestamp1 taskid Ta SWITCHED-IN
> + Timestamp1 taskid Ta SWITCHED-OUT
> + Timestamp1 taskid Ta TERMINATED
> +
> +
> +
> --
> 2.7.4
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20180605/0f053646/attachment-0001.html>
More information about the devel
mailing list