Bare-Metal Debugging

Debugging

Um auf einem Raspberry Pi erfolgreich Bare-Metal zu programmieren, ist das Debuggen unverzichtbar. Unter „Debuggen“ versteht man das systematische Aufspüren von Fehlern. Dabei geht man das Programm oft Schritt für Schritt durch und beobachtet live, wie sich Register, der Arbeitsspeicher und die Hardware verhalten.

Da in einer Bare-Metal-Umgebung kein Betriebssystem hilft, Fehler zu melden (es gibt z.B. keinen „Bluescreen“ oder eine Fehlermeldung auf dem Monitor), benötigen wir eine Brücke in die Hardware. Hier kommt die Raspberry Pi Debug Probe ins Spiel. Sie erlaubt uns einen direkten Blick in das „Herz“ des Prozessors, während das Programm läuft.

Die Raspberry Pi Debug Probe

Die Raspberry Pi Debug Probe ist eine spezialisierte Hardware-Lösung für ARM-basierte Mikrocontroller und Computer. Sie kombiniert zwei wichtige Funktionen in einem Gerät:

USB-zu-SWD-Brücke (Serial Wire Debug): Dies ist die eigentliche Debug-Schnittstelle. Sie ermöglicht es dem PC, den Prozessor des Raspberry Pi zu steuern, Programme in den Speicher zu laden und den Code jederzeit anzuhalten (Breakpoints).

USB-zu-UART-Brücke: Ein serieller Port, mit dem Textausgaben des Raspberry Pi (ähnlich wie bei einem Terminal) am PC empfangen werden können.

Damit kann sich die Debug Probe mit Geräten wie dem Raspberry Pi Pico oder dem Raspberry Pi 5 verbinden und die Brücke zu einem Host-Rechner (Windows-PC, Mac oder Linux) schlagen. Dank des standardisierten CMSIS-DAP-Protokolls ist sie mit fast allen gängigen Entwicklungsumgebungen kompatibel.

Raspberry Pi 4

Die Verwendung der **Raspberry Pi Debug Probe** mit einem **Raspberry Pi 4** unter Windows 11 ist ein exzellenter Weg, um echtes Bare-Metal-Debugging zu betreiben. Da der Pi 4 im Gegensatz zum Pi 5 keinen dedizierten Debug-Port hat, müssen wir die **GPIO-Pins** dafür konfigurieren.

Hier ist der Schritt-für-Schritt-Plan, um GDB zum Laufen zu bringen:

---

1. 1. 1. 1. Hardware-Verbindung (SWD & UART)

Die Debug Probe hat zwei Anschlüsse: **D** (Debug/SWD) und **U** (UART/Seriell).

• • Verbindung zum GPIO-Header des Pi 4:**

Verwende das beiliegende Kabel (JST-auf-Header-Pins).

| Debug Probe (D-Port) | Pi 4 GPIO Pin | Funktion | | --- | --- | --- | | **SD** (gelb/gold) | **GPIO 24** (Pin 18) | SWDIO | | **SC** (orange) | **GPIO 25** (Pin 22) | SWCLK | | **GND** (schwarz) | **GND** (z.B. Pin 20) | Masse (Wichtig!) |

• • Optional: UART für Textausgabe (U-Port):**

| Debug Probe (U-Port) | Pi 4 GPIO Pin | Funktion | | --- | --- | --- | | **TX** | **GPIO 15** (Pin 10) | Pi RX | | **RX** | **GPIO 14** (Pin 8) | Pi TX |

---

1. 1. 1. 2. Konfiguration auf der SD-Karte (`config.txt`)

Damit der Pi 4 die JTAG/SWD-Signale an den GPIO-Pins überhaupt zulässt, musst du das in der `config.txt` auf deiner SD-Karte aktivieren:

```ini

1. Aktiviert JTAG/SWD auf den Pins 22-27 (Alt4 Modus)

enable_jtag_gpio=1

1. Dein Bare-Metal Kernel

kernel=kernel8.img

```

---

1. 1. 1. 3. Software-Setup unter Windows 11

Du benötigst zwei Hauptkomponenten: **OpenOCD** (als Brücke zur Hardware) und den **GDB** (als Debugger-Interface).

1. **OpenOCD für Windows:** Lade dir eine aktuelle Version herunter (z.B. von [xPack OpenOCD](https://github.com/xpack-dev-tools/openocd-xpack/releases)). 2. **ARM Toolchain:** Installiere die `arm-none-eabi-gcc` Toolchain, die den Debugger `arm-none-eabi-gdb` enthält.

---

1. 1. 1. 4. Den Debug-Vorgang starten

1. 1. 1. 1. Schritt A: OpenOCD Server starten

Öffne ein Terminal (PowerShell/CMD) und starte OpenOCD. Du musst die Konfiguration für die Debug Probe (`cmsis-dap`) und den Pi 4 (`bcm2711`) angeben:

```bash openocd -f interface/cmsis-dap.cfg -f target/bcm2711.cfg

```

• Wenn alles klappt, siehst du eine Meldung wie `Listening on port 3333 for gdb connections`.*

1. 1. 1. 1. Schritt B: GDB verbinden

Öffne ein zweites Terminal und starte den Debugger mit deiner Bare-Metal ELF-Datei:

```bash arm-none-eabi-gdb dein_projekt.elf

```

Innerhalb von GDB gibst du nun folgende Befehle ein:

```gdb (gdb) target extended-remote localhost:3333 (gdb) monitor reset halt (gdb) load (gdb) continue

```

---

1. 1. 1. Wichtige Tipps für Windows 11:

• **Zadig-Treiber:** Falls OpenOCD die Probe nicht erkennt, lade das Tool **Zadig** herunter. Wähle die Debug Probe aus und stelle sicher, dass der Treiber auf `WinUSB` oder `CMSIS-DAP` eingestellt ist.
• **VS Code Integration:** Für ein komfortableres Erlebnis empfehle ich die Erweiterung **"Cortex-Debug"**. Damit kannst du Breakpoints direkt im Code setzen, anstatt Befehle in die Konsole zu tippen.

Raspberry Pi 5

Beim **Raspberry Pi 5** ist die Situation deutlich angenehmer als beim Pi 4, da die Hardware von Grund auf für das Debugging mit der **Raspberry Pi Debug Probe** vorbereitet wurde. Der Pi 5 besitzt einen dedizierten **Debug-Anschluss**, sodass du keine GPIO-Pins mehr "opfern" oder mühsam Kabel stecken musst.

Hier ist der Ablauf für den Pi 5 unter Windows 11:

---

1. 1. 1. 1. Hardware-Verbindung (Der einfache Weg)

Der Pi 5 hat zwischen dem HDMI-Port und dem USB-C Stromanschluss einen kleinen **3-Pin-JST-Anschluss** mit der Beschriftung **"UART"**.

• Verwende das **3-Pin-auf-3-Pin-Kabel**, das der Debug Probe beiliegt.
• Verbinde den **D-Port** (Debug) der Probe direkt mit diesem Anschluss am Pi 5.
• **Wichtig:** Dieser eine Anschluss am Pi 5 liefert sowohl die **SWD-Signale** (für GDB) als auch den **UART-Ausgang** (für die serielle Konsole). Du brauchst also nur dieses eine Kabel!

---

1. 1. 1. 2. Software-Konfiguration (Bare-Metal)

Beim Pi 5 (BCM2712 Chip) ist der Debug-Port standardmäßig für UART aktiv, aber für echtes SWD-Debugging musst du sicherstellen, dass die Firmware den Zugriff erlaubt.

In der `config.txt` auf deiner SD-Karte:

```ini

1. Aktiviert die Debug-Funktionen

enable_jtag_gpio=1

1. Optional: Verhindert, dass der Pi in tiefe Stromsparmodi geht, die den Debugger trennen

arm_64bit=1 kernel=kernel8.img

```

---

1. 1. 1. 3. Debugging mit GDB unter Windows 11

Da der Pi 5 einen neueren Chip (**BCM2712**) verwendet, benötigt OpenOCD die passenden Konfigurationsdateien.

1. 1. 1. 1. Schritt A: OpenOCD starten

In der PowerShell/Eingabeaufforderung:

```bash openocd -f interface/cmsis-dap.cfg -c "transport select swd" -f target/bcm2712.cfg

```

• Hinweis: Sollte `target/bcm2712.cfg` in deiner OpenOCD-Version fehlen, musst du eventuell eine ganz aktuelle Version von [xPack OpenOCD](https://github.com/xpack-dev-tools/openocd-xpack/releases) laden oder die Konfigurationsdatei manuell aus dem [Raspberry Pi OpenOCD GitHub](https://github.com/raspberrypi/openocd) kopieren.*

1. 1. 1. 1. Schritt B: GDB (AArch64) nutzen

Da der Pi 5 ein reiner 64-Bit-Prozessor (Cortex-A76) ist, solltest du den **aarch64-none-elf-gdb** verwenden (Teil der ARM GNU Toolchain).

```bash aarch64-none-elf-gdb dein_baremetal_projekt.elf

```

Im GDB-Prompt:

```gdb (gdb) target extended-remote localhost:3333 (gdb) monitor reset halt (gdb) load (gdb) continue

```

---

1. 1. 1. 4. Besonderheit beim Pi 5: Der "Bootloader-Modus"

Der Pi 5 ist beim Booten sehr schnell. Wenn dein Bare-Metal-Code sofort abstürzt, verlierst du oft die Verbindung.

• Du kannst den Pi 5 in einen "Wartemodus" versetzen, indem du bestimmte Flags in der EEPROM-Konfiguration setzt, aber für den Anfang reicht meist der Befehl `monitor reset halt` in GDB, um die CPU sofort nach dem Reset anzuhalten.

---

1. 1. 1. Zusammenfassung der Vorteile beim Pi 5:

• **Kein Kabelsalat:** Ein Stecker für alles (Debug & Konsole).
• **Keine GPIO-Konflikte:** Du kannst alle 40 GPIO-Pins für dein Projekt nutzen, während du debuggst.
• **Geschwindigkeit:** Der BCM2712 reagiert wesentlich schneller auf Debug-Befehle als der alte Pi 4 Chip.

• • Ein kleiner Fallstrick:** Die Debug Probe muss unter Windows 11 manchmal via **Zadig** korrekt zugewiesen werden (wie beim Pi 4 erwähnt), damit OpenOCD den `cmsis-dap` Treiber korrekt anspricht.

Willst du ein bestehendes C-Projekt auf den Pi 5 portieren, oder fängst du mit einem "Hello World" (LED blinken) komplett neu an?