Changes between Initial Version and Version 1 of TBR/Review/Debugging/Start


Ignore:
Timestamp:
Oct 4, 2005, 7:41:43 PM (16 years ago)
Author:
JoelSherrill
Comment:

_ conversion error from phpwiki

Legend:

Unmodified
Added
Removed
Modified
  • TBR/Review/Debugging/Start

    v1 v1  
     1= Debugging =
     2
     3= Symbolic Debug Information =
     4
     5
     6RTEMS and the RTEMS tool chains support symbolic debugging. The application, RTEMS and any libraries you wish to debug need to be compiled with the '''gcc''' option '''-g'''. This option causes the compiler to emit debugging information, while the code generated should not change. The '''GNU gcc''' debugging options can be found here -
     7  {{{}}}
     8
     9  http://gcc.gnu.org/onlinedocs/gcc-3.4.3/gcc/Debugging-Options.html#Debugging-Options
     10
     11Using the '''-g''' option results in larger object and executable file sizes, and for C++ this can be quite large. For example a M68K C++ application can have a ELF executable file size of 19M bytes yet the code size is only 1.6M bytes. The actual memory foot print can be seen by using the '''size''' tool on an object file or the final executable -
     12  {{{}}}
     13
     14  <verbatim>
     15  $ m68k-rtems-size myfile.o
     16  </verbatim>
     17
     18For RTEMS you typically do not need to strip the executable. The loading of the executable into the target memory or conversion to S records, Intel Hex, for binary format will automatically strip the debug information. Keeping the excutable with the debugging information is recommended. If a problem appears with code in the field and you recieve a some sort of dump or trace you can use the '''objdump''' tool to help locate the problem -
     19  {{{}}}
     20
     21  <verbatim>
     22  $ m68k-rtems-objdump -D --line-numbers --source --demangle  myapp.elf | less
     23  </verbatim>
     24= Debugging a BSP =
     25
     26
     27To test a BSP you need an application. The samples and tests provide a proven set of applications that allow you to test your BSP. Select a sample application such as the '''Hello World''' to try first, then move to an application that uses more interrupt sources.
     28
     29The following is a list of debugging tools and setups that we recommended. Time spent on this will be rewarded further into the project:
     30
     31 * Try to create a working debugger environment for the target hardware. The GNU debugger, GDB, supports a number of different ways to connect to a target. The interface can be a simple serial port using a [wiki:Debugging/GdbSerialMonitor GdbSerialMonitor], or an expensive TCP/IP type hardware probe.
     32
     33 * If your target processor supports a simulator it is recommended you learn how to use it. It will give you a stable debugging enviroment.
     34
     35 * Implement a ''printk'' interface in your BSP. For target hardware that does not have a video interface the ''printk'' outputs to a serial port. The driver is normally a simple polled UART driver.
     36
     37 * Use the [wiki:TBR/UserManual/Capture_Engine Capture Engine] to aid the debugging and verfication of your real-time design.
     38= GDB and RTEMS =
     39
     40
     41Currently GDB is not RTEMS aware. GDB scripts exist that can help by providing presenting kernel structures in a user friendly manner. These can be found here: [wiki:Debugging/GDBScripts GdbScripts].
     42
     43The issue with making GDB aware of RTEMS is where the knowledge of the kernel structures is located. A version of GDB that contains a specific kernel structure layout will break if RTEMS changes. The ideal would be for GDB to find the structure elements using the applications debug information.
     44= How much memory is left in the C Program Heap? =
     45
     46
     47The C heap is a region so this should work:
     48
     49{{{
     50  (gdb) p '''((Region''Control ''')''Region''Information->local''table<nowiki>[</nowiki>1])->Memory->first
     51  $9 <tt> {back''flag </tt> 1, front''flag <tt> 8058280, next </tt> 0x7ea5b4, previous = 0x7ea5b0}
     52}}}
     53
     54Let's look at that gdb command in more detail.
     55
     56 * ''Region''Information_ contains the information used to manage Region objects.
     57 * ''Region''Information->local_table is the object pointer table for Regions.  It is
     58  indexed by the ''object index'' portion of the object ID.
     59 * ''Region''Information->local''table<nowiki>[</nowiki>1] points to the first Region object.  It is of type ''(Region''Control *)''.
     60 * ((Region''Control *)''Region''Information->local''table<nowiki>[</nowiki>1])->Memory points to the Heap control portion of this Region's control block.
     61 * '''((Region''Control ''')''Region''Information->local''table<nowiki>[</nowiki>1])->Memory->first references the contents of the first ''heap block'' on this Heap.
     62
     63Notice that the ''front''flag'' is displayed as ''8058280''.  This is in decimal since we used ''p'' not ''p/x'' to gdb.  Since this number is even, we know the ''in use bit_ is 0 and the block is free.  Thus the first block on the heap is 8,058,280 bytes and there are at least that many bytes left.
     64
     65'''NOTE:''' This is really a crude estimate.
     66
     67If you have compiled RTEMS libraries with -DRTEMS_DEBUG, malloc will maintain statistics. From an RTEMS application:
     68
     69{{{
     70##include <libcsupport.h>
     71    .....
     72  malloc_dump ();
     73}}}
     74
     75will print malloc's heap statistics to ''stdout''. Example usage can be found in <tt>c/src/tests/frye/libcleak</tt> and <tt>c/src/tests/libtests/malloctest</tt>.
     76
     77The following GDB macro may also be of use. If provided with an argument of '''0''' for a summary, or '''1''' to explicitly list the regions.
     78
     79 
     80 define rtems-mallocheap-walk
     81   printf "walking the heap:\n"
     82   set $heapstart = ((Region_Control *)_Region_Information->local_table[RTEMS_Malloc_Heap&0xffff])->Memory->start
     83   set $currentblock = $heapstart
     84   set $used = 0
     85   set $numused = 0
     86   set $free = 0
     87   set $numfree = 0
     88   while $currentblock->front_flag != 1
     89     if $currentblock->front_flag & 1
     90       if $arg0 != 0
     91        printf "USED: %d\n", $currentblock->front_flag & ~1
     92       else
     93         printf "*"
     94       end
     95       set $used = $used + $currentblock->front_flag & ~1
     96       set $numused = $numused + 1
     97     else
     98       if $arg0 != 0
     99        printf "FREE: %d\n", $currentblock->front_flag & ~1
     100       else
     101         printf "."
     102       end
     103       set $free = $free + $currentblock->front_flag & ~1
     104       set $numfree = $numfree + 1
     105     end
     106     set $currentblock = (Heap_Block *)((char *)$currentblock + ($currentblock->front_flag&~1))
     107   end
     108   if $arg0 == 0
     109     printf "\n"
     110   end
     111   printf "TOTAL: %d (%d)\tUSED: %d (%d) \tFREE: %d (%d)\n", \
     112     $used + $free, $numused + $numfree, \
     113     $used, $numused, \
     114     $free, $numfree
     115 end
     116
     117= How much memory is left in the RTEMS Workspace? =
     118
     119
     120An RTEMS workspace overage can be fairly easily spotted with a debugger. Look at ''Workspace''Area. If first == last, then there is only one free block of memory in the workspace (very likely if no task or message queue deletions). Then do this:
     121
     122{{{
     123  (gdb) p '''(Heap''Block ''')''Workspace_Area->first
     124  $3 <tt> {back''flag </tt> 1, front''flag <tt> 68552, next </tt> 0x1e260, previous = 0x1e25c}
     125}}}
     126
     127 * ''Workspace''Area is the variable name of the RTEMS Workspace Heap control block.
     128 * '''(Heap''Block ''')''Workspace_Area->first is the contents of the first heap block information.
     129
     130Just as with the C Program Heap, the number was even indicating it is free.  In this case, I had 68552 bytes left in the workspace.
     131
     132'''NOTE:''' This is really a crude estimate.  GDB 5.0 and newer support a macro language that provides the features necessary to write a function which would walk a heap structure and print out accurate statistics.  If you write this, submit it. :)
     133= BSP rtems_initialize_executive_late call dies =
     134
     135
     136Your target is booting and the BSP is initialising but a call to ''rtems''initialize''executive''late_ results in an exception, or the target locking up. This can be due to a few reasons that you will need to work through.
     137
     138 * The memory map is not correct. RTEMS use the [wiki:WorkSpace WorkSpace] to create the initialization task, it's stack, the interrupt stack, plus more. If the [wiki:WorkSpace WorkSpace] is wrong the target will die. The exact way depends on the specific processor and mapping error. If you have implemented ''printk'' it may be a good idea to add some code to ''bsp''pretasking''hook'' to show you the base and size:
     139
     140{{{
     141          printk ("Heap : %5d KB @ 0x%08x\n   ", heap''size >> 10, heap''start);
     142}}}
     143
     144 * The initialization process encountered an error. The set of these is documented in the '''Classic API C User's Guide'''.  For RTEMS 4.6.1, this was documented in the [http://www.rtems.com/onlinedocs/releases/rtemsdocs-4.6.1/share/rtems/html/c_user/c_user00034.html Initialization Manager Failure ] section.
     145
     146 * Interrupts are pending and no interrupt handler is present, or a bug exists in the interrupt handler, or vector table layout. RTEMS will enable interrupts when it switches to the initialization task ''rtems''initialize''executive''late'' creates. This problem can be found by getting to the context switch call, '' ''Context''Switch_, then the crash or lockup. The fix is to make sure the BSP has masked all sources of interrupts in the hardware around the processor. This allows RTEMS and the application an ordered and controlled initialization of driver and therefore interrupts.
     147
     148The initialization task is a real task in RTEMS. The ''rtems''initialize''executive''late_ creates it and switches context to it. This means your BSP environment is another context that RTEMS will switch back to when RTEMS is shut down. This allows your BSP to take control again, then perform any specific functions it needs. A typical operational thing to do is to reboot as embedded targets should not stop.
     149= GDB Cannot Find My Source Files =
     150
     151
     152If you find the source code paths in your executable as seen by GDB are missing, you may find using an absolute path to invoke the RTEMS configure script may help. When RTEMS libraries get built, nested ''Makefiles'' are executed that '''walk''' through the build directory structure. Therefore, each file is compiled from a certain point in the build directory structure that lies in paralllel to the source directory structure.
     153
     154As a consequece of this, you get a varing number of "dots", depending on how deep the corresponding directory is inside the build tree. There is no common location, from which the source file pointers in the debug info is correct for all object files.
     155
     156If you call the initial <tt>configure</tt> in an absolute way such as :
     157
     158 
     159   /usr/local/src/rtems/tools/rtems-4.6.0/configure
     160
     161
     162rather that a relative way :
     163
     164 
     165   ../rtems-4.6.0/configure
     166
     167
     168GDB should find the source.