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