[PATCH] Adding tracing documentation in user manual
Vidushi Vashishth
reachvidu at gmail.com
Tue Jun 5 15:40:08 UTC 2018
---
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
More information about the devel
mailing list