On Tue, Jun 5, 2018 at 11:40 AM, Vidushi Vashishth <reachv...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
