From 8f4f80d437c84ac8b4a0194a868ff83baf394462 Mon Sep 17 00:00:00 2001 From: Vidushi Vashishth Date: Thu, 14 Jun 2018 19:47:58 +0530 Subject: Adding Trace Documentation - Updates #3454 - This commit adds Tracing Framework Chapter in the RTEMS User Manual - It comprises of subchapters on RTEMS Trace Linker, Capture Engine, Trace generation techniques explaining trace generation using Trace Buffering and Printk generators and sample demonstrations. --- user/tracing/introduction.rst | 103 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 user/tracing/introduction.rst (limited to 'user/tracing/introduction.rst') diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst new file mode 100644 index 0000000..27de441 --- /dev/null +++ b/user/tracing/introduction.rst @@ -0,0 +1,103 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns +.. 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 :ref:`tracelinker` +- RTEMS :ref:`capturengine` +- Common Trace Format Integration + +RTEMS trace framework can currently function using the following methods. Both +of the methods make use of the :ref:`tracelinker` : + +.. _tracebuffering: + +RTEMS Trace Using Trace Buffering +================================= + +This scheme of tracing goes through the flow of events described in a +subsequent flowchart: + +Step 1: The user creates an application and user configuration file. The +configuration file specifies the use of the trace buffer generator and other +standard initializations. The user then configures their BSP and invokes the +trace linker using a command to link the application executable. The trace +linker uses the application files in compiled format (ELF) and the libraries +used to build the application for performing this link. + +Step 2: The RTEMS Trace Linker reads the user’s configuration file and that +results in it reading the standard Trace Buffering Configuration files +installed with the RTEMS Trace Linker. The trace linker uses the target +compiler and linker to create the trace enabled application executable. It +wraps the functions defined in the user’s configuration with code that captures +trace records into the statically allocated buffer. The trace wrapper code is +compiled with the target compiler and the resulting ELF object file is added to +the standard link command line used to link the application and the application +is re-linked using the wrapping option of the GNU linker. + +Step 3: The trace linker creates an executable which is capable of running on +the target hardware or simulator. + +Step 4: RTEMS shell provides the “rtrace” command to display and save trace +buffers. + +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing +.. figure:: ../../images/user/rtems-trace-buffering.png + :align: center + :width: 75% + +.. _printk: + +RTEMS Trace Using Printk +======================== + +This scheme of tracing goes through the flow of events described in a subsequent +flowchart: + +Step 1: The user creates an RTEMS application in the normal manner as well as a +Trace Linker configuration file. The configuration file specifies using the +Printk trace mode and the functions to trace. The user invokes the Trace Linker +with the configuration and the normal link command line used to the link the +application executable. The application ELF object files and libraries, +including the RTEMS libraries are standard and do not need to be built +specially. + +Step 2: The RTEMS Trace Linker reads the user's configuration file and that +results in it reading the standard Printk Trace Configuration files installed +with the RTEMS Trace Linker. The trace linker uses the target compiler and +linker to create the trace enabled application executable. It wraps the +functions defined in the user's configuration with code that prints the entry +with arguments and exit and return value if any. The trace wrapper code is +compiled with the target compiler and the resulting ELF object file is added to +the standard link command line used to link the application and the application +is relinked using the wrapping option of the GNU linker. + +Step 3: The trace linker creates and RTEMS ELF executable that can be run on the +target hardware or simulator. + +Step 4: The application is run in the hardware directly or using a debugger. The +printk() output appears on the target console and the user can save that to a +file. + +.. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing +.. figure:: ../../images/user/rtems-trace-printk.png + :align: center + :width: 75% + +The :ref:`examples` section describes generation of traces using Trace Buffering +technique for the `fileio` testsuite available with RTEMS installation. -- cgit v1.2.3