#format rst
#language de


GDB Befehle für das ES2 Praktikum
=================================

Alle Demo-Projekte enthalten eine GDB Startup Datei ``.estool/gdbinit``.

GDB immer im "Text User Interface" Modus starten (Option ``--tui``, siehe Makefile).

GDB vervollständigt viele Eingaben durch Drücken der Tablulator Taste. Jedes
Kommando kann verkürzt eingegeben werden, solange es eindeutig ist. Zum Beispiel
``br`` oder ``b`` statt ``breakpoint``.

In GDB bekommt man einen Hilfetext durch das ``help`` Kommando::

   (arm-gdb) help breakpoint

Breakpoints ausgeben::

    (arm-gdb) info br
    Num     Type           Disp Enb Address    What                            
    1       breakpoint     keep y   0x0800015e in main at main.c:47   

**Breakpoints** kann man löschen mit ``del <Num>``. Man kann sie auch           
deaktivieren/aktivieren mit ``disable <Num>`` und ``enable <Num>``. 
Mit ``cont`` führt man das Programm bis zum nächsten Breakpoint (oder bis zum 
Programmende) aus.

**Breakpoint** z.B. auf Funktion toggle_led() setzen: ``br toggle_leds``. Die Funktionsnamen vervollständigt GDB durch die TAB Taste.  Man kann auch Zeilennummern verwenden, z.B. ``br 192``.

**Variablen** ausgeben mit ``p <variable>``.

**Lokale** Variable ausgeben mit <Funktion>::<Variable>:

::

     (arm-gdb) p main::loopcnt
     $2 = 0x4e


Adressen von globalen Variablen ausgeben am Beispiel von ``globvar``:

::
   
     (arm-gdb) p &globvar
     $1 = (int *) 0x2000000c <globvar>

*Anregung:* Definieren Sie Variablen in unterschiedlichen Speicherabschnitten und
finden Sie die Adressen::

    int g_bss;
    int g_data = 4;
    uint8_t g_array[] = {2, 14, 29, 7, 0};                                     
    const int g_cdata = 5;

Ordnen Sie die gefundenen Adressen in die Abschnitte des Linker-Scripts ein.
Schauen Sie sich in diesem Zusammenhang auch das GCC Werkeug ``arm-none-eabi-nm``
an. Es findet Adressen in ausführbaren Programmen. 

**Displays.** Man kann sich mit ``display`` Variablen und Register              
automatisch nach jedem Breakpoint anzeigen lassen:

::
 
   br 192
   display hADCxConvertedData_Temperature_DegreeCelsius

Ein Display löscht man wieder mit dem ``undisplay`` Kommando.

**Ausgeben des Speichers** ("memory dump"). Die Variable ``g_data`` hat den Wert 4. 
Aufpassen: Das Kommando ``x/1xw g_data`` interpretiert den Wert von ``g_data`` als
Adresse auf den Speicher! Der meist gewünschte Output wird erst durch ``x/1xw &g_data`` 
erreicht. 

::

    (arm-gdb) x/1xw g_data
    0x4:    0x080001c5
    (arm-gdb) x/1xw &g_data
    0x20000000 <g_data>:    0x00000004

Geben Sie alle Elemente von ``g_array`` aus. Dazu müssen Sie das        
Kommando ``x`` modifizieren, eine Hilfe bekommen Sie durch              
``(arm-gdb) help x``.

Variable auf neuen Wert setzen:

::

     (arm-gdb) set var g_bss = 21

GDB "Oberfläche" auf **mehrere Fenster** umschalten, in denen
der C Quelltext, die Assemblerbefehle und die Kommandos stehen:
::

     (arm-gdb) C-x 2

Die Angabe ``C-x 2`` bedeutet: zunächst Steuerung-x drücken, Finger weg, dann die 2 drücken. Mehrfaches ``C-x 2`` schaltet verschiedene Ansichten durch. Mit ``C-x o`` kann man den Fokus nacheinander auf 
jedes Fenster legen.

Programm wieder von Anfang an ausführen:

::

   (arm-gdb) monitor reset halt
   (arm-gdb) continue

In ``gdbinit`` gibt es dazu das selbst definierte Kommando ``debug-program``. 

**Watchpoints** unterbrechen den Programmablauf, wenn eine Variable geschrieben oder
gelesen wird::

   (arm-gdb) watch hADCxConvertedData_Temperature_DegreeCelsius

**Kommandos** mit Breakpoints verknüpfen. Das folgende Beispiel legt ein print 
Kommando für den Breakpoint Nr. 5 an. Es können auch mehrere Kommandos vor dem
``end`` aufgenommen werden. Nach jedem Breakpoint Nr. 5 wird die Kommando-Liste
abgearbeitet.

::

   commands 5
   p hADCxConvertedData_Temperature_DegreeCelsius
   end

**Bedingter Breakpoint**

::

  (arm-gdb) br 192 if hADCxConvertedData_Temperature_DegreeCelsius == 19


**Bedingter Breakpoint**, zusätzlich mit Kommandoliste:

::

   set $tmp = hADCxConvertedData_Temperature_DegreeCelsius                            
   b 192 if $tmp != hADCxConvertedData_Temperature_DegreeCelsius                      
   commands                                                                           
   set $tmp = hADCxConvertedData_Temperature_DegreeCelsius                         
   p hADCxConvertedData_Temperature_DegreeCelsius                                  
   continue                                                                        
   end    

GDB Kommandos lassen sich in eine Textdatei schreiben und auf dem GDB Prompt
mit ``source`` ausführen, z.B.

::

    (arm-gdb) source gdbcmd

Die Datei mit den Kommandos heisst hier ``gdbcmd``, sie kann einen beliebigen Namen haben.