1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | .. _introduction: |
---|
6 | |
---|
7 | Introduction to Tracing |
---|
8 | *********************** |
---|
9 | |
---|
10 | Tracing is an important function which has several applications including |
---|
11 | identification of complex threading, detection of deadlocks, tracing |
---|
12 | functions along with their argument values, and return values through |
---|
13 | progression of several function calls and audit the performance of an |
---|
14 | application according to required specifications. |
---|
15 | |
---|
16 | RTEMS tracing framework is under development and welcomes contribution by users. |
---|
17 | |
---|
18 | RTEMS has the following trace components: |
---|
19 | |
---|
20 | - :ref:`RTEMS Trace Linker <TraceLinker>` |
---|
21 | - :ref:`RTEMS Capture Engine <CaptureEngine>` |
---|
22 | - :ref:`RTEMS Event Recording <EventRecording>` |
---|
23 | - Common Trace Format Integration |
---|
24 | |
---|
25 | RTEMS trace framework can currently function using the following methods. Both |
---|
26 | of the methods make use of the :ref:`tracelinker` : |
---|
27 | |
---|
28 | .. _tracebuffering: |
---|
29 | |
---|
30 | RTEMS Trace Using Trace Buffering |
---|
31 | ================================= |
---|
32 | |
---|
33 | This scheme of tracing goes through the flow of events described in a |
---|
34 | subsequent flowchart: |
---|
35 | |
---|
36 | Step 1: The user creates an application and user configuration file. The |
---|
37 | configuration file specifies the use of the trace buffer generator and other |
---|
38 | standard initializations. The user then configures their BSP and invokes the |
---|
39 | trace linker using a command to link the application executable. The trace |
---|
40 | linker uses the application files in compiled format (ELF) and the libraries |
---|
41 | used to build the application for performing this link. |
---|
42 | |
---|
43 | Step 2: The RTEMS Trace Linker reads the user's configuration file and that |
---|
44 | results in it reading the standard Trace Buffering Configuration files |
---|
45 | installed with the RTEMS Trace Linker. The trace linker uses the target |
---|
46 | compiler and linker to create the trace enabled application executable. It |
---|
47 | wraps the functions defined in the user's configuration with code that captures |
---|
48 | trace records into the statically allocated buffer. The trace wrapper code is |
---|
49 | compiled with the target compiler and the resulting ELF object file is added to |
---|
50 | the standard link command line used to link the application and the application |
---|
51 | is re-linked using the wrapping option of the GNU linker. |
---|
52 | |
---|
53 | Step 3: The trace linker creates an executable which is capable of running on |
---|
54 | the target hardware or simulator. |
---|
55 | |
---|
56 | Step 4: RTEMS shell provides the "rtrace" command to display and save trace |
---|
57 | buffers. |
---|
58 | |
---|
59 | .. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing |
---|
60 | .. figure:: ../../images/user/rtems-trace-buffering.png |
---|
61 | :align: center |
---|
62 | :width: 75% |
---|
63 | |
---|
64 | .. _printk: |
---|
65 | |
---|
66 | RTEMS Trace Using Printk |
---|
67 | ======================== |
---|
68 | |
---|
69 | This scheme of tracing goes through the flow of events described in a subsequent |
---|
70 | flowchart: |
---|
71 | |
---|
72 | Step 1: The user creates an RTEMS application in the normal manner as well as a |
---|
73 | Trace Linker configuration file. The configuration file specifies using the |
---|
74 | Printk trace mode and the functions to trace. The user invokes the Trace Linker |
---|
75 | with the configuration and the normal link command line used to the link the |
---|
76 | application executable. The application ELF object files and libraries, |
---|
77 | including the RTEMS libraries are standard and do not need to be built |
---|
78 | specially. |
---|
79 | |
---|
80 | Step 2: The RTEMS Trace Linker reads the user's configuration file and that |
---|
81 | results in it reading the standard Printk Trace Configuration files installed |
---|
82 | with the RTEMS Trace Linker. The trace linker uses the target compiler and |
---|
83 | linker to create the trace enabled application executable. It wraps the |
---|
84 | functions defined in the user's configuration with code that prints the entry |
---|
85 | with arguments and exit and return value if any. The trace wrapper code is |
---|
86 | compiled with the target compiler and the resulting ELF object file is added to |
---|
87 | the standard link command line used to link the application and the application |
---|
88 | is relinked using the wrapping option of the GNU linker. |
---|
89 | |
---|
90 | Step 3: The trace linker creates and RTEMS ELF executable that can be run on the |
---|
91 | target hardware or simulator. |
---|
92 | |
---|
93 | Step 4: The application is run in the hardware directly or using a debugger. The |
---|
94 | printk() output appears on the target console and the user can save that to a |
---|
95 | file. |
---|
96 | |
---|
97 | .. comment: taken from https://devel.rtems.org/wiki/Developer/Tracing |
---|
98 | .. figure:: ../../images/user/rtems-trace-printk.png |
---|
99 | :align: center |
---|
100 | :width: 75% |
---|
101 | |
---|
102 | The :ref:`examples` section describes generation of traces using Trace Buffering |
---|
103 | technique for the `fileio` testsuite available with RTEMS installation. |
---|