[PATCH] Adding tracing documentation in user manual

Gedare Bloom gedare at rtems.org
Tue Jun 5 16:24:13 UTC 2018


On Tue, Jun 5, 2018 at 11:40 AM, 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.
> +

I don't know how it is elsewhere, but I would prefer to see the Oxford
comma here, i.e., "3rd party packages, and the kernel"

> +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.
> +
Remove this note, and create/link the separate pages with the "TBD" stub.

> +
> +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

Delete "It is upto us ... events into." This is an unnecessary
statement in user documentation.

> +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

"A packet header" maybe better, more precise?

> +- An optional context

"packet context" ?

> +- A set of concatenated events each containing:
> + - A header

"An event header" ?

> + - A stream-specific context
> + - An event-specific context
> + - A payload
> +

On second thought, it's not clear to me if a user needs this much
detail about what is happening inside CTF. They want to know what are
the advantages/disadvantages and how do I use it. These details about
the packet formats may be superfluous, I guess that remains to be
seen.

> +This method of tracing is currently under development and can utilise the following 3rd party package:

Rewrite this sentence to better introduce the reader to the need that
is filled by babeltrace.

> +
> +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
> +

I would just refer the reader to the babeltrace instructions
themselves. We don't want to provide an exhaustive list here.

> +
> +You can also build from source using tarballs or git repositories of babeltrace. Refer to http://diamon.org/babeltrace/
> +for further details.

Yes, just refer to the URL and be done with it.

> 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.
> +

Why is it important? What purpose does it serve? (Debugging aid?
Program behavior comprehension?)

I suggest you devise a templated approach to describe these use cases.
Something like:
Name
=====

Brief description.

Objective
-------------
What purpose this use case intends to accomplish / its goal / user's
need filled by it.

Requirements
------------------
What the use case needs out of the trace to accomplish its purpose.

Example
------------
Like what you have below.


> +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.

typo: testsuite

> +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:
> +

Eventually, you would be able to show some actual output. For now, you
should try to "mock" the expected output as closely as you can.

> +.. 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.
> +

spelling: coulmns.

> +
> +Tracing Thread Operations
> +=========================
> +

Here you would instantiate a new use case template and fill it in.

> +Real time applications inherently utilise parallel programming which entails several
> +tasks executing simulataneously and competing for common resources. On single processor systems

spelling: simultaneously. Please use a spell checker when writing documentation.

> +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

sp: swicthes.

> +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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel



More information about the devel mailing list