<div dir="ltr"><div>Hi!</div><div><br></div><div>This is a rough skeleton of the tracing chapter in the user manual documentation with some incomplete bits. I have covered the "to be completed bits" in some of my blogs and that should not take much time to finish. Let me know if you have suggestions. <br></div><div><br></div><div>Thanks!</div><div>Vidushi<br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jun 5, 2018 at 9:10 PM, Vidushi Vashishth <span dir="ltr"><<a href="mailto:reachvidu@gmail.com" target="_blank">reachvidu@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">---<br>
user/index.rst | 2 +<br>
user/tracing/development.rst | 12 ++++++<br>
user/tracing/index.rst | 25 ++++++++++++<br>
user/tracing/introduction.rst | 90 ++++++++++++++++++++++++++++++<wbr>+++++++++++++<br>
user/tracing/usecases.rst | 77 ++++++++++++++++++++++++++++++<wbr>++++++<br>
5 files changed, 206 insertions(+)<br>
create mode 100644 user/tracing/development.rst<br>
create mode 100644 user/tracing/index.rst<br>
create mode 100644 user/tracing/introduction.rst<br>
create mode 100644 user/tracing/usecases.rst<br>
<br>
diff --git a/user/index.rst b/user/index.rst<br>
index 8cbcd1b..a764fe8 100644<br>
--- a/user/index.rst<br>
+++ b/user/index.rst<br>
@@ -52,6 +52,8 @@ to the Community Project hosted at <a href="http://www.rtems.org/" rel="noreferrer" target="_blank">http://www.rtems.org/</a>.<br>
<br>
tools/index<br>
<br>
+ tracing/index<br>
+<br>
support/index<br>
<br>
glossary/index<br>
diff --git a/user/tracing/development.rst b/user/tracing/development.rst<br>
new file mode 100644<br>
index 0000000..ad74d8f<br>
--- /dev/null<br>
+++ b/user/tracing/development.rst<br>
@@ -0,0 +1,12 @@<br>
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. comment: All rights reserved.<br>
+<br>
+.. _development:<br>
+<br>
+Tracing Development<br>
+*******************<br>
+<br>
+RTEMS trace is an open source project currently under development.<br>
+<br>
+This section can contain how to build the rtems-tools after making changes to the trace linker. <br>
diff --git a/user/tracing/index.rst b/user/tracing/index.rst<br>
new file mode 100644<br>
index 0000000..ad22439<br>
--- /dev/null<br>
+++ b/user/tracing/index.rst<br>
@@ -0,0 +1,25 @@<br>
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. comment: All rights reserved.<br>
+<br>
+.. _tracing-framework:<br>
+<br>
+RTEMS Tracing Framework<br>
+***********************<br>
+.. index:: Tracing Framework<br>
+<br>
+RTEMS Tracing Framework is an on-target software based system which helps track<br>
+the ongoings inside applications, 3rd party packages and the kernel in real time.<br>
+<br>
+Software based tracing is a complex process which requires components on both the<br>
+target and the host to work together. However its portability across all architectures<br>
+and board support packages makes it a useful asset. A key requirement in RTEMS trace process<br>
+is to take existing code in compiled format (ELF) and instrument it in order to log various events<br>
+and records in real time. However instrumenting of the code for tracing should happen without rebuilding<br>
+the code from the source and without annotating the source with trace code.<br>
+<br>
+.. toctree::<br>
+<br>
+ introduction<br>
+ usecases<br>
+ development<br>
diff --git a/user/tracing/introduction.<wbr>rst b/user/tracing/introduction.<wbr>rst<br>
new file mode 100644<br>
index 0000000..3314447<br>
--- /dev/null<br>
+++ b/user/tracing/introduction.<wbr>rst<br>
@@ -0,0 +1,90 @@<br>
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. comment: All rights reserved.<br>
+<br>
+.. _introduction:<br>
+<br>
+Introduction to Tracing<br>
+***********************<br>
+<br>
+Tracing is an important function which has several applications including identification of<br>
+complex threading, detection of deadlocks, tracing functions along with their argument values,<br>
+and return values through progression of several function calls and audit the performance of an<br>
+application according to required specifications. <br>
+<br>
+RTEMS tracing framework is under development and welcomes contribution by users.<br>
+<br>
+RTEMS has the following trace components:<br>
+<br>
+- RTEMS Trace Linker<br>
+- Capture Engine<br>
+- Common Trace Format Integration<br>
+<br>
+.. note::<br>
+<br>
+ I could create separate pages to explain the aforementioned components in detail.<br>
+<br>
+<br>
+RTEMS trace framework can currently function using the following methods:<br>
+<br>
+RTEMS Trace Using Trace Buffering<br>
+=============================<wbr>====<br>
+<br>
+To be completed<br>
+<br>
+RTEMS Trace Using Printk<br>
+========================<br>
+<br>
+To be completed<br>
+<br>
+RTEMS Trace Using CTF<br>
+=====================<br>
+<br>
+`Common Trace Format <<a href="http://diamon.org/ctf/" rel="noreferrer" target="_blank">http://diamon.org/ctf/</a>>`_ is a binary trace format which is fast to write<br>
+and has great flexibility. It allows traces to be developed by bare-metal applications or by any<br>
+other C/C++ system. RTEMS tracing framework can benefit from these features of CTF. <br>
+<br>
+A typical CTF *trace* consists of multiple *streams* of binary *events*. It is upto us how many<br>
+streams we want to divide our tracer generated events into. The *metadata* stream is a mandatory<br>
+stream which describes the layout of all the other streams in a trace. This metadata stream is written<br>
+using *Trace Stream Description Language* (TSDL).<br>
+<br>
+A binary *stream* is further a concatenation of several packets each containing the following:<br>
+<br>
+- A header<br>
+- An optional context<br>
+- A set of concatenated events each containing:<br>
+ - A header<br>
+ - A stream-specific context<br>
+ - An event-specific context<br>
+ - A payload<br>
+<br>
+This method of tracing is currently under development and can utilise the following 3rd party package:<br>
+<br>
+Babeltrace<br>
+----------<br>
+<br>
+Babeltrace is an open source trace format converter which can be used to convert RTEMS traces into CTF.<br>
+It is also a reference parser implementation of CTF. Babeltrace currently supports the following output<br>
+formats for traces:<br>
+<br>
+- Text<br>
+- CTF<br>
+- CTF-metadata<br>
+- Dummy<br>
+- lttng-live <br>
+<br>
+Babeltrace comes in the form of a library, python bindings (python3) and command line tool called ``babeltrace``.<br>
+To install babeltrace on your host you can follow one of the following methods:<br>
+<br>
+Using Distribution Packages:<br>
+<br>
+1) On ubuntu/debian run: ``sudo apt-get install babeltrace``<br>
+<br>
+2) On fedora run: ``sudo yum install babeltrace``<br>
+<br>
+3) On Arch linux run: ``yaourt -S babeltrace`` or ``yaourt -S babeltrace-git`` for the latest git version<br>
+<br>
+<br>
+You can also build from source using tarballs or git repositories of babeltrace. Refer to <a href="http://diamon.org/babeltrace/" rel="noreferrer" target="_blank">http://diamon.org/babeltrace/</a><br>
+for further details.<br>
diff --git a/user/tracing/usecases.rst b/user/tracing/usecases.rst<br>
new file mode 100644<br>
index 0000000..323fe15<br>
--- /dev/null<br>
+++ b/user/tracing/usecases.rst<br>
@@ -0,0 +1,77 @@<br>
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. comment: All rights reserved.<br>
+<br>
+.. _usecases:<br>
+<br>
+Tracing Use Cases<br>
+*****************<br>
+<br>
+Following are the use cases of the tracing framework that are currently under development:<br>
+<br>
+Function Tracing<br>
+================<br>
+<br>
+Tracing the entry and exit of a function as well as the values of the arguments and<br>
+return values can prove to be an important application for the tracing framework.<br>
+<br>
+As a start to the development of function tracing using CTF we can work on the fileio<br>
+sample testsuit and trace all the calls to malloc, calloc, free and realloc functions.<br>
+Along with the calls made to these functions the trace must also capture the values of<br>
+their arguments at entry and the return values at function exit. As an example of an application<br>
+having the following progression of function calls:<br>
+<br>
+.. code-block:: c<br>
+<br>
+ #include <stdlib.h><br>
+ int main(int argc, char** argv)<br>
+ {<br>
+ int* a = malloc(sizeof(int));<br>
+ free(a);<br>
+ a = calloc(1, sizeof(int));<br>
+ return 0;<br>
+ }<br>
+<br>
+<br>
+The trace of such an application must be output of the following kind:<br>
+<br>
+.. code-block:: shell<br>
+<br>
+ Timestamp1 entry of malloc > argument value<br>
+ Timestamp2 exit of malloc < return value<br>
+ Timestamp3 entry of free > argument value<br>
+ Timestamp4 exit of free < return value (null)<br>
+ Timestamp5 entry of calloc > argument1 value, argument2 value<br>
+ Timestamp6 exit of calloc < return value1<br>
+<br>
+There could be additional coulmns of details including current priority, task state etc.<br>
+<br>
+ <br>
+Tracing Thread Operations<br>
+=========================<br>
+<br>
+Real time applications inherently utilise parallel programming which entails several<br>
+tasks executing simulataneously and competing for common resources. On single processor systems<br>
+the CPU performs context switching between each of these tasks rapidly. By tracing the creation and<br>
+termination of tasks as well as the context swicthes between them one can possibly identify probable race<br>
+conditions or complex threading operations.<br>
+<br>
+A sample trace tracking two tasks Ta and Tb could have an output of the following kind:<br>
+<br>
+.. code-block:: shell<br>
+<br>
+ Timestamp1 taskid Ta CREATED<br>
+ Timestamp1 taskid Ta SWITCHED-IN<br>
+ Timestamp1 taskid Ta BEGIN<br>
+ Timestamp1 taskid Tb CREATED<br>
+ Timestamp1 taskid Ta SWITCHED-OUT<br>
+ Timestamp1 taskid Tb SWITCHED-IN<br>
+ Timestamp1 taskid Tb BEGIN<br>
+ Timestamp1 taskid Tb SWITCHED-OUT<br>
+ Timestamp1 taskid Tb TERMINATED<br>
+ Timestamp1 taskid Ta SWITCHED-IN<br>
+ Timestamp1 taskid Ta SWITCHED-OUT<br>
+ Timestamp1 taskid Ta TERMINATED <br>
+ <br>
+<br>
+<br>
<span class="HOEnZb"><font color="#888888">-- <br>
2.7.4<br>
<br>
</font></span></blockquote></div><br></div>