[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