Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt und speichern diese ins Verzeichnis '''C:\tools\openocd\openocd\scripts\interface''':
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
C:\Program Files (x86)\GnuWin32\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A72 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 4 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-24T08:51:09Z

Satyria: /* Umgebungsvariable „Path“ anpassen */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt und speichern diese ins Verzeichnis '''C:\tools\openocd\openocd\scripts\interface''':
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A72 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 4 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-24T08:50:51Z

Satyria: /* Umgebungsvariable „Path“ anpassen */

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-24T08:46:34Z

Satyria: /* OpenOCD einrichten und konfigurieren */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt und speichern diese ins Verzeichnis '''C:\tools\openocd\openocd\scripts\interface''':
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A72 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 4 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:55:09Z

Satyria: /* Zusammenfassung */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A72 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 4 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:54:36Z

Satyria: /* Die Debugger-Ansichten nutzen */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A72 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:53:15Z

Satyria: /* Hardware vorbereiten und Debugging in der GUI */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

=== Hardware verbinden ===

==== Verdrahtung ====
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:52:07Z

Satyria: /* Hardware vorbereiten und SD-Karte einrichten */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 4 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 4 muss wissen, dass wir ein Bare-Metal-Programm via JTAG debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel8.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).

'''bcm2711-rpi-4-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)

'''config.txt''' (Die Konfigurationsdatei für die Firmware).

'''bootcode.bin'''

'''fixup4.dat'''

'''start4.elf'''

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

Hardware verbinden:

=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:42:39Z

Satyria: /* Linkerscript und Makefile erstellen */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 4 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 4.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 4 ('''-mcpu=cortex-a72''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.



Hardware verbinden:

=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:40:26Z

Satyria: /* Die .vscode Konfigurationsdateien anlegen */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 4 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.



Hardware verbinden:

=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:39:49Z

Satyria: /* Die .vscode Konfigurationsdateien anlegen */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 4)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.



Hardware verbinden:

=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:38:21Z

Satyria:

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und dem FT232H Modul verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:
<syntaxhighlight>
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>
Zusätzlich benötigen wir ein Target-Profil für den Broadcom-Chip BCM2711 des Raspberry Pi 4. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2711.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
# SPDX-License-Identifier: GPL-2.0-or-later

# The Broadcom BCM2711 used in Raspberry Pi 4
# No documentation was found on Broadcom website

# Partial information is available on the Raspberry Pi website:
# https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711

if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2711
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

jtag newtap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# these addresses are obtained from the ROM table via 'dap info 0' command
set _DBGBASE {0x80410000 0x80510000 0x80610000 0x80710000}
set _CTIBASE {0x80420000 0x80520000 0x80620000 0x80720000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 4) - FT232H",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel8.elf",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts",
"${workspaceFolder}"
],
"configFiles": [
"interface/ft232h-jtag.cfg",
"target/bcm2711.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"adapter speed 3000",
"init"
],

"overrideLaunchCommands": [
"monitor halt",
"monitor wait_halt 2000",
"load",
"monitor reg pc 0x80000"
],

"preLaunchTask": "Kompilieren",
"showDevDebugOutput": "raw"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI4)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x1F0000);
LED_on();
wait(0x1F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
//
// The LED program for RPI4
// 20.02.2025 www.satyria.de
//
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"
#include "led.h"

void LED_on (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPSET = GPIO_GPSET0;
if (LED_Pin>31)
{
GPSET = GPSET + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPSET,1<<LED_Pin);
}

void LED_off (void)
{
u32 LED_Pin = 42;
SetGPIOFunction(LED_Pin,GPIO_output);

u32 GPCLR = GPIO_GPCLR0;
if (LED_Pin>31)
{
GPCLR = GPCLR + 4;
LED_Pin = LED_Pin - 32;
}
write32(GPCLR,1<<LED_Pin);
}

void SetGPIOFunction(u32 Pin, u32 Function)
{
u32 GPSEL = GPIO_GPFSEL0;
while (Pin >= 10)
{
Pin = Pin -10;
GPSEL = GPSEL + 4;
}
Pin = Pin *3;
Function = Function << Pin;
u32 mask = 0b111 << Pin;
mask =~mask; //Bitweise negieren

u32 sel=read32(GPSEL);
sel=sel&mask;
sel=sel|Function;
write32(GPSEL,sel);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0xFE000000

// General Purpose I/O (GPIO)
#define GPIO_BASE RPI_BASE + 0x200000
#define GPIO_GPFSEL0 GPIO_BASE + 0x00 // GPIO Function Select 0
#define GPIO_GPFSEL1 GPIO_BASE + 0x04 // GPIO Function Select 1
#define GPIO_GPFSEL2 GPIO_BASE + 0x08 // GPIO Function Select 2
#define GPIO_GPFSEL3 GPIO_BASE + 0x0c // GPIO Function Select 3
#define GPIO_GPFSEL4 GPIO_BASE + 0x10 // GPIO Function Select 4
#define GPIO_GPFSEL5 GPIO_BASE + 0x14 // GPIO Function Select 5
#define GPIO_GPSET0 GPIO_BASE + 0x1c // GPIO Pin Output Set 0
#define GPIO_GPSET1 GPIO_BASE + 0x20 // GPIO Pin Output Set 1
#define GPIO_GPCLR0 GPIO_BASE + 0x28 // GPIO Pin Output Clear 0
#define GPIO_GPCLR1 GPIO_BASE + 0x2c // GPIO Pin Output Clear 1
#define GPIO_GPLEV0 GPIO_BASE + 0x34 // GPIO Pin Level 0
#define GPIO_GPLEV1 GPIO_BASE + 0x38 // GPIO Pin Level 1
#define GPIO_GPEDS0 GPIO_BASE + 0x40 // GPIO Pin Event Detect Status 0
#define GPIO_GPEDS1 GPIO_BASE + 0x44 // GPIO Pin Event Detect Status 1
#define GPIO_GPREN0 GPIO_BASE + 0x4c // GPIO Pin Rising Edge Detect Enable 0
#define GPIO_GPREN1 GPIO_BASE + 0x50 // GPIO Pin Rising Edge Detect Enable 1
#define GPIO_GPFEN0 GPIO_BASE + 0x58 // GPIO Pin Falling Edge Detect Enable 0
#define GPIO_GPFEN1 GPIO_BASE + 0x5c // GPIO Pin Falling Edge Detect Enable 1
#define GPIO_GPHEN0 GPIO_BASE + 0x64 // GPIO Pin High Detect Enable 0
#define GPIO_GPHEN1 GPIO_BASE + 0x68 // GPIO Pin High Detect Enable 1
#define GPIO_GPLEN0 GPIO_BASE + 0x70 // GPIO Pin Low Detect Enable 0
#define GPIO_GPLEN1 GPIO_BASE + 0x74 // GPIO Pin Low Detect Enable 1
#define GPIO_GPAREN0 GPIO_BASE + 0x7c // GPIO Pin Async. Rising Edge Detect 0
#define GPIO_GPAREN1 GPIO_BASE + 0x80 // GPIO Pin Async. Rising Edge Detect 1
#define GPIO_GPAFEN0 GPIO_BASE + 0x88 // GPIO Pin Async. Falling Edge Detect 0
#define GPIO_GPAFEN1 GPIO_BASE + 0x8c // GPIO Pin Async. Falling Edge Detect 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG0 GPIO_BASE + 0xe4 // GPIO Pull-up / Pull-down Register 0
#define GPIO_GPIO_PUP_PDN_CNTRL_REG1 GPIO_BASE + 0xe8 // GPIO Pull-up / Pull-down Register 1
#define GPIO_GPIO_PUP_PDN_CNTRL_REG2 GPIO_BASE + 0xec // GPIO Pull-up / Pull-down Register 2
#define GPIO_GPIO_PUP_PDN_CNTRL_REG3 GPIO_BASE + 0xf0 // GPIO Pull-up / Pull-down Register 3
// Information from BCM2835 ARM Peropherals
#define GPIO_GPPUD GPIO_BASE + 0x94 // GPIO Pin Pull-up/down Enable
#define GPIO_GPPUDCLK0 GPIO_BASE + 0x98 // GPIO Pin Pull-up/down Enable Clock 0
#define GPIO_GPPUDCLK1 GPIO_BASE + 0x9c // GPIO Pin Pull-up/down Enable Clock 1

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

#include "types.h"

#define GPIO_input 0b000 //Input
#define GPIO_output 0b001 //Output
#define GPIO_alt0 0b100 //alternate function 0
#define GPIO_alt1 0b101 //alternate function 1
#define GPIO_alt2 0b110 //alternate function 2
#define GPIO_alt3 0b111 //alternate function 3
#define GPIO_alt4 0b011 //alternate function 4
#define GPIO_alt5 0b010 //alternate function 5

#define GPPUD_OFF 0b00

void LED_off(void);
void LED_on(void);
void SetGPIOFunction(u32 Pin, u32 Function);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u32 a, u32 b);
u32 read32(u32 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 4 in den JTAG-Modus um. Dadurch wird die Kommunikation mit dem FT232H Modul überhaupt erst möglich.



Hardware verbinden:

=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 4.
* Schließen Sie das FT232H Modul per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 4 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel8.elf''' (für den Debugger inklusive Symbolen) und '''kernel8.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 4 über das FT232H Modul auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 4 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

=== Wichtiger Hinweis zum Reboot ===
Da es nicht möglich ist, ein Reset an den Raspberry Pi 4 zu schicken, muss vor jedem Neukompilieren der Raspberry Pi 4 neu gestartet werden.

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4

2026-06-05T13:08:33Z

Satyria: Die Seite wurde neu angelegt: „Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist. Um direkt mit dem Raspberry Pi 5 zu kommunizieren u…“

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Um direkt mit dem Raspberry Pi 5 zu kommunizieren und Programme zu debuggen, wird zusätzlich eine '''Raspberry Pi Debug Probe''' benötigt. Diese wird über USB mit einem Windows-Rechner und über die Debug-Pins mit dem Raspberry Pi 5 verbunden.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und der Debug Probe verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Überprüfen Sie anschließend, ob die Datei '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' existiert. Diese wird in der Regel standardmäßig mitgeliefert. Sollte sie fehlen, erstellen Sie diese Datei neu mit folgendem Inhalt:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>
Da in älteren oder Standard-OpenOCD-Releases ein passendes Target-Profil für den neuen Broadcom-Chip BCM2712 des Raspberry Pi 5 fehlt, müssen wir dieses manuell anlegen. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP für direkten Zugriff
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# Diese Adressen wurden aus der ROM-Table via 'dap info 0'-Befehl ausgelesen
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Standard-Target ist cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Überschreibt den standardmäßigen "reset halt" Befehl von VS-Code
"overrideResetCommands": [
"monitor halt"
],

// Befehle, die direkt nach dem Verbinden ausgeführt werden
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Zwingt den Prozessor direkt auf die Startadresse
],

"preLaunchTask": "Kompilieren"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI5)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Bit 9 auf 0 setzen
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Bit 9 auf 1 setzen
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO-Definitionen für den Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''kernel_address=0x80000''' setzt die Startadresse im RAM fest, an die unser Kernel geladen wird.

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 5 in den JTAG-/SWD-Modus um. Dadurch wird die Kommunikation mit der Raspberry Pi Debug Probe überhaupt erst möglich.



Hardware verbinden:
* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 5.
* Verbinden Sie die Raspberry Pi Debug Probe über das mitgelieferte 3-Pol-UART/Debug-Kabel mit dem dedizierten Debug-Port des Raspberry Pi 5 (befindet sich zwischen den Micro-HDMI-Ports).
* Schließen Sie die Debug Probe per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 5 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel_2712.elf''' (für den Debugger inklusive Symbolen) und '''kernel_2712.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 5 über die Debug Probe auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 5 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Hauptseite

2026-06-05T13:07:54Z

Satyria: /* Anhang */

== C und ARM-Assemblerprogrammierung mit dem Raspberry ==

[[Datei:EinhornOrg.png|frameless|300x300px]]

Matthias Steiner

Satyria Press © by 2020-2025

=== Vorwort ===

Herzlich willkommen auf unserer Seite zur Bare-Metal-Programmierung für den Raspberry Pi 4 und Pi 5! Diese Webseite richtet sich sowohl an Anfänger als auch an fortgeschrittene Programmierer, die tief in die Welt der hardwarenahen Programmierung eintauchen möchten.

Ursprünglich sollte diese Seite sich ausschließlich mit Assembler beschäftigen, wurde jedoch im Laufe der Zeit um C erweitert. Daher finden Sie hier zunächst grundlegende Informationen zu Assembler. Wenn Ihr Interesse in der C-Programmierung liegt und Sie mit Windows arbeiten, empfehlen wir Ihnen mit dem Kapitel '''[[Programmierumgebung erstellen (Konsole)]]''' zu beginnen. Für Linux-Nutzer ist das Kapitel '''[[Programmierumgebung erstellen unter Linux]]''' der richtige Startpunkt.

Im Kapitel '''Raspberry Pi 4 Assembler 32-Bit''' beschreiben wir die Assembler-Programmierung für den Raspberry Pi 4. Dieses Kapitel hat zwar bereits einige Jahre auf dem Buckel, bleibt aber weiterhin relevant und wertvoll. Hier finden Sie detaillierte Erklärungen der ARM-32-Bit-Befehle mit anschaulichen Beschreibungen und Beispielen, was besonders Anfängern den Einstieg erleichtern soll.

Das Kapitel '''Raspberry Pi 4 C (64-Bit)''' entstand im Laufe unserer Arbeit am Raspberry Pi 5 und bietet eine umfassende Beschreibung der 64-Bit-C-Programmierung für den Raspberry Pi 4. Dies wird auch später die USB-Programmierung einschließen, eine Funktion, die wir später auf den Raspberry Pi 5 übertragen werden. So haben alle Projekte einen gemeinsamen Ausgangspunkt.

Das Kapitel '''Raspberry Pi 5''' ist der ideale Startpunkt für die Programmierung des Raspberry Pi 5 in Assembler und C. Es führt Sie von der Installation des Hostsystems (Windows/Linux) bis zur abschließenden Programmierung in C und Assembler.

Im Anhang finden Sie viele nützliche Informationen, wie eine Beschreibung der '''GNU Compiler Collection''', eine Auflistung des '''ARM-Befehlssatzes''' (im Aufbau), verschiedene '''Raspberry Pi Modelle''' und einige hilfreiche '''Links''' zu anderen Projekten. Ein aktuelles Projekt zum Thema '''Debugging''' ist ebenfalls dort zu finden.

Wir hoffen, dass Sie auf unserer Seite viel Freude haben und sich gut zurechtfinden! Bei Fragen oder Kommentaren schicken Sie uns gerne eine E-Mail an assem@satyria.de. Wir freuen uns über Ihre Rückmeldungen und Anregungen.

Viel Spaß beim Programmieren!

== Sponsor ==
Wenn ihr uns etwas unterstützen möchtet, schaut einfach mal hier vorbei:

[[Datei:Logo hexenlaedle.png|frameless|200x200px|link=https://www.hexenlaedle.de]]

== Inhalt ==
*[[Vorwort]]
*[[Grundlegendes zu Assembler]]
**[[Grundlegendes zu Assembler#Der ARM-Assembler|Der ARM-Assembler]]
*[[Programmierumgebung erstellen (Konsole)]]

== Raspberry Pi 5 ==
*[[Programmierumgebung erstellen (64-Bit)]]
*[[Einführung in C- und Assemblerprogrammierung mit dem Raspberry Pi 5]]
**[[Einführung in C- und Assemblerprogrammierung mit dem Raspberry Pi 5#Warum C und Assembler?|Warum C und Assembler?]]
*[[Programm auf dem Raspberry Pi 5 ausführen]]
*[[Arbeiten mit Make und Linker-Script]]

== Raspberry Pi 5 Assembler==
*[[Unser erstes Programm (PI5)]]
*[[Lass die LED leuchten (PI5)]]
*[[Fehlerbehandlung]]
*[[Grafik (PI5)]]
*[[Chars (PI5)]]
*Das Terminal (PI5)

== Raspberry Pi 5 C ==
*[[Unser erstes Programm in C (PI5)]]
*[[Lass die LED leuchten in C (PI5)]]
*[[Fehlerbehandlung in C (PI5)]]
*[[Grafik in C (PI5)]]
*[[Chars in C (PI5)]]
*[[Das Terminal in C (PI5)]]
*[[printf in BareMetal (PI5)]]

== Raspberry Pi 4 Assembler 32-Bit ==
*[[Programmierumgebung erstellen (32-Bit)]]
*[[Systemprogrammierung / Bare Metal]]
*[[Das erste Programm]]
*[[General Purpose I/O]]
*[[System Timer]]
*[[UART]]
*[[Die Anzeige]]
*[[Zeichenfunktionen]]

== Raspberry Pi 4 C (64-Bit) ==
*[[Unser erstes Programm in C (PI4)]]
*[[Lass die LED leuchten in C (PI4)]]
*[[Fehlerbehandlung in C (PI4)]]
*[[Grafik in C (PI4)]]
*[[Chars in C (PI4)]]
*[[Das Terminal in C (PI4)]]
*[[Printf in BareMetal (PI4)]]
*[[Systeminformationen (PI4)]] (noch kein Inhalt)
*[[Interrupts (PI4)]]
**[[Beispiel Timer-Interrupt (PI4)]]
*[[Interrupt Teil 2 (PI4)]]

== ARM64 Assembler ==
*[[Programmieren mit ARM64 Assembler]]

== Zusätzliches Material ==
*[[Links der verwendeten Software]]

== Anhang ==
*[[GNU Compiler Collection]]
*[[ARM-Befehlssatz]]
**[[Grundlegende Befehle]]

*[[Raspberry PI Modelle]]
**[[Basisadressen der Modelle]]
*[[LINKS]]
* Debugging
**[[Bare-Metal Debugging (JTAG, RPI 4)]]

**[[Professionelle GUI mit Debugging für Bare-Metal (64-Bit) auf dem Raspberry Pi 4]]
**[[Professionelle GUI mit Debugging für Bare-Metal auf dem Raspberry Pi 5]]
----
*[[Die wichtigsten Linux-Terminal-Befehle]]

== Translations/Traducciones ==
*[[English]]

Bare-Metal Debugging (JTAG, RPI 4)

2026-06-05T13:06:17Z

Satyria: /* Konfigurationsdatei erstellen */

== Einleitung ==
Bei der Entwicklung von Software wird oft ein Debugger benötigt, um Fehler zu finden und zu beheben. Ein gängiger Debugger ist GDB. Solange das Programm aus einer Umgebung wie Linux oder Windows startbar ist, kann dieser Debugger direkt verwendet werden. Bei der Bare-Metal-Entwicklung sind die Dinge jedoch etwas schwieriger, da hier die gewohnte Betriebssystemumgebung fehlt. In solchen Fällen sind Emulatoren oder spezielle Hardwarelösungen nötig.

Da Emulatoren meist nicht zu 100 % die Hardware widerspiegeln können, verwenden wir das Hostsystem, welches direkt mit dem Raspberry Pi 4 (RPI4) kommuniziert. Das Programm wird auf dem Raspberry Pi direkt ausgeführt. Über das Hostsystem können wir jedoch den Code direkt manipulieren und sehen das Ergebnis unmittelbar auf der Hardware.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Hardware vorbereiten ==
Das FT232H Modul wurde zwar mit Stiftleisten geliefert, aber diese mussten zunächst auf das Modul aufgelötet werden. Anschließend konnte mit Kabelbrücken die Verbindung mit dem Raspberry Pi 4 hergestellt werden.
=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

== Verwendung von Windows ==
Unter Windows verwenden wir die MSYS2-Umgebung. Diese bietet eine Unix-ähnliche Umgebung unter Windows und ist nützlich für viele Entwicklungsaufgaben.

=== Installation und Einrichtung ===
Falls noch nicht geschehen, installieren wir MSYS2 nach folgender Anleitung [[Programmierumgebung erstellen (Konsole)]] und richten die Programmierumgebung ein, indem wir die folgenden Befehle ausführen:

* Starte MSYS2 MSYS.
* Gib die folgenden Befehle ein, um OpenOCD zu installieren und die Umgebungsvariablen zu setzen:
<syntaxhighlight lang="shell">
pacman -S mingw64/mingw-w64-x86_64-openocd
echo 'export PATH="/mingw64/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "C:\msys64\mingw64\share\openocd\scripts\interface\ftdi" ab, wenn MSYS2 nach den Vorgaben installiert wurde.

=== Treiberinstallation ===
OpenOCD möchte auf das Gerät über libusb zugreifen. In der Regel bietet Windows diesen Treiber nicht, sodass wir hier noch einen Treiber installieren müssen. Dazu verwenden wir "Zadig", welches von https://zadig.akeo.ie/ heruntergeladen werden kann.

# Installiere Zadig.
# Starte Zadig und aktiviere im Menü "Options" die Option "List All Devices".
# Wähle "Single RS232-HS" aus der Geräteliste.
# Als Treiber wähle "libusbK" aus und klicke auf "Replace Driver".
Damit ist Windows bereit, mit dem Modul über OpenOCD zu kommunizieren.

== Verwendung von Linux ==

=== Installation und Einrichtung ===
Zunächst benötigen wir OpenOCD:
<syntaxhighlight lang="shell">
sudo apt update
sudo apt install openocd
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "/usr/share/openocd/scripts/interface/ftdi" ab.

== Raspberry Pi vorbereiten ==
Nachdem unser Betriebssystem auf dem Raspberry Pi eingerichtet ist, müssen wir den Raspberry Pi 4 für Bare-Metal-Programmierung vorbereiten. Dazu schreiben wir ein kleines Programm, das nur eine Endlosschleife erzeugt, aber den Raspberry Pi startet:
<syntaxhighlight lang="asm">
//
// The boot program for RPI4
// 07.03.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

b _start // endless loop
</syntaxhighlight>

Wir verwenden ein Makefile, um das Programm zu kompilieren und zu linken (siehe [[Unser erstes Programm in C (PI4)#Kompilieren des Programms mit Make]]). Den erzeugten "kernel8.img" kopieren wir auf die SD-Karte. Beachte, dass auch folgende Dateien im Root-Verzeichnis der SD-Karte liegen müssen:
* bcm2711-rpi-4-b.dtb
* bootcode.bin
* fixup4.dat
* start4.elf

Nun müssen wir dem Raspberry Pi auch mitteilen, dass er auf JTAG reagiert. Dazu erstellen wir eine config.txt mit folgendem Inhalt:

<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>
Diese Datei legen wir ebenfalls in das Root-Verzeichnis der SD-Karte.

== Starten von OpenOCD und Verwendung von GDB ==
=== Verbindung herstellen ===
Verbinde zunächst das FT232H-Modul per USB mit dem Hostsystem. Auf dem Modul sollte nun eine LED leuchten, welche anzeigt, dass das Gerät betriebsbereit ist. Starte den Raspberry Pi. Wenn du ihn an einem Monitor angeschlossen hast, wird auf dem Bildschirm das Regenbogenbild angezeigt, was bedeutet, dass das System gestartet wurde.

Starte nun "MSYS2 MSYS" oder unter Linux ein Terminal:
[[Datei:OpenOcd.png|mini]]
<syntaxhighlight lang="shell">
openocd -f interface/ftdi/ft232h-jtag.cfg -f target/bcm2711.cfg
</syntaxhighlight>
Wenn alles korrekt eingerichtet ist, sollte OpenOCD alle vier CPUs des Raspberry Pi anzeigen. Es zeigt außerdem, dass die Ports 3333, 3334, 3335 und 3336 für die GDB-Kommunikation bereitgestellt werden.

=== Kernel-Upload und Debugging ===
Um sicherzugehen, öffnen wir ein weiteres "MSYS2 MSYS"-Fenster oder zweites Terminal unter Linux. Hier wechseln wir in das Verzeichnis, welches den zu testenden Code enthält. Falls der Code noch nicht kompiliert ist, muss dies jetzt erledigt werden.

Verwende für diese Versuche den kernel8.elf:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb
target extended-remote :3333
</syntaxhighlight>
Dies stellt eine Verbindung zur CPU0 her.

Lade nun den Kernel auf den Raspberry Pi hoch:
<syntaxhighlight lang="gdb">
load kernel8.elf
</syntaxhighlight>

Damit der Kernel nun startet, verwenden wir die folgenden Befehle:
<syntaxhighlight lang="gdb">
set $pc = 0x80000
continue
</syntaxhighlight>

=== Ohne Kernel-Upload ===

Wenn bereits auf dem Raspberry PI 4 der Kernel läuft, verwende folgendes:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb kernel8.elf
</syntaxhighlight>

Im Debugger dann:
<syntaxhighlight lang="gdb">
target extended-remote :3333
</syntaxhighlight>

Bare-Metal Debugging (JTAG, RPI 4)

2026-06-05T13:04:55Z

Satyria: /* Konfigurationsdatei erstellen */

== Einleitung ==
Bei der Entwicklung von Software wird oft ein Debugger benötigt, um Fehler zu finden und zu beheben. Ein gängiger Debugger ist GDB. Solange das Programm aus einer Umgebung wie Linux oder Windows startbar ist, kann dieser Debugger direkt verwendet werden. Bei der Bare-Metal-Entwicklung sind die Dinge jedoch etwas schwieriger, da hier die gewohnte Betriebssystemumgebung fehlt. In solchen Fällen sind Emulatoren oder spezielle Hardwarelösungen nötig.

Da Emulatoren meist nicht zu 100 % die Hardware widerspiegeln können, verwenden wir das Hostsystem, welches direkt mit dem Raspberry Pi 4 (RPI4) kommuniziert. Das Programm wird auf dem Raspberry Pi direkt ausgeführt. Über das Hostsystem können wir jedoch den Code direkt manipulieren und sehen das Ergebnis unmittelbar auf der Hardware.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Hardware vorbereiten ==
Das FT232H Modul wurde zwar mit Stiftleisten geliefert, aber diese mussten zunächst auf das Modul aufgelötet werden. Anschließend konnte mit Kabelbrücken die Verbindung mit dem Raspberry Pi 4 hergestellt werden.
=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

== Verwendung von Windows ==
Unter Windows verwenden wir die MSYS2-Umgebung. Diese bietet eine Unix-ähnliche Umgebung unter Windows und ist nützlich für viele Entwicklungsaufgaben.

=== Installation und Einrichtung ===
Falls noch nicht geschehen, installieren wir MSYS2 nach folgender Anleitung [[Programmierumgebung erstellen (Konsole)]] und richten die Programmierumgebung ein, indem wir die folgenden Befehle ausführen:

* Starte MSYS2 MSYS.
* Gib die folgenden Befehle ein, um OpenOCD zu installieren und die Umgebungsvariablen zu setzen:
<syntaxhighlight lang="shell">
pacman -S mingw64/mingw-w64-x86_64-openocd
echo 'export PATH="/mingw64/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter speed 3000

adapter driver ftdi

ftdi vid_pid 0x0403 0x6014
ftdi layout_init 0x0078 0x017b

ftdi_tdo_sample_edge falling
ftdi layout_signal nTRST -ndata 0x0010 -noe 0x0040
ftdi layout_signal nSRST -ndata 0x0020 -noe 0x0040

transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "C:\msys64\mingw64\share\openocd\scripts\interface\ftdi" ab, wenn MSYS2 nach den Vorgaben installiert wurde.

=== Treiberinstallation ===
OpenOCD möchte auf das Gerät über libusb zugreifen. In der Regel bietet Windows diesen Treiber nicht, sodass wir hier noch einen Treiber installieren müssen. Dazu verwenden wir "Zadig", welches von https://zadig.akeo.ie/ heruntergeladen werden kann.

# Installiere Zadig.
# Starte Zadig und aktiviere im Menü "Options" die Option "List All Devices".
# Wähle "Single RS232-HS" aus der Geräteliste.
# Als Treiber wähle "libusbK" aus und klicke auf "Replace Driver".
Damit ist Windows bereit, mit dem Modul über OpenOCD zu kommunizieren.

== Verwendung von Linux ==

=== Installation und Einrichtung ===
Zunächst benötigen wir OpenOCD:
<syntaxhighlight lang="shell">
sudo apt update
sudo apt install openocd
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter driver ftdi

ftdi vid_pid 0x0403 0x6014

# Setze das Layout für JTAG-Signale (TDI, TDO, TMS, TCK, nTRST, nSRST)
# Diese Pins sind für JTAG erforderlich
ftdi layout_init 0x0000 0x000b
ftdi layout_signal nTRST -data 0x0020 -oe 0x0020
ftdi layout_signal nSRST -data 0x0010 -oe 0x0010
ftdi layout_signal TDI -data 0x0011 -oe 0x0011
ftdi layout_signal TDO -data 0x0012 -oe 0x0012
ftdi layout_signal TMS -data 0x0013 -oe 0x0013
ftdi layout_signal TCK -data 0x0014 -oe 0x0014

# Wählen Sie den JTAG-Modus aus
transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "/usr/share/openocd/scripts/interface/ftdi" ab.

== Raspberry Pi vorbereiten ==
Nachdem unser Betriebssystem auf dem Raspberry Pi eingerichtet ist, müssen wir den Raspberry Pi 4 für Bare-Metal-Programmierung vorbereiten. Dazu schreiben wir ein kleines Programm, das nur eine Endlosschleife erzeugt, aber den Raspberry Pi startet:
<syntaxhighlight lang="asm">
//
// The boot program for RPI4
// 07.03.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

b _start // endless loop
</syntaxhighlight>

Wir verwenden ein Makefile, um das Programm zu kompilieren und zu linken (siehe [[Unser erstes Programm in C (PI4)#Kompilieren des Programms mit Make]]). Den erzeugten "kernel8.img" kopieren wir auf die SD-Karte. Beachte, dass auch folgende Dateien im Root-Verzeichnis der SD-Karte liegen müssen:
* bcm2711-rpi-4-b.dtb
* bootcode.bin
* fixup4.dat
* start4.elf

Nun müssen wir dem Raspberry Pi auch mitteilen, dass er auf JTAG reagiert. Dazu erstellen wir eine config.txt mit folgendem Inhalt:

<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>
Diese Datei legen wir ebenfalls in das Root-Verzeichnis der SD-Karte.

== Starten von OpenOCD und Verwendung von GDB ==
=== Verbindung herstellen ===
Verbinde zunächst das FT232H-Modul per USB mit dem Hostsystem. Auf dem Modul sollte nun eine LED leuchten, welche anzeigt, dass das Gerät betriebsbereit ist. Starte den Raspberry Pi. Wenn du ihn an einem Monitor angeschlossen hast, wird auf dem Bildschirm das Regenbogenbild angezeigt, was bedeutet, dass das System gestartet wurde.

Starte nun "MSYS2 MSYS" oder unter Linux ein Terminal:
[[Datei:OpenOcd.png|mini]]
<syntaxhighlight lang="shell">
openocd -f interface/ftdi/ft232h-jtag.cfg -f target/bcm2711.cfg
</syntaxhighlight>
Wenn alles korrekt eingerichtet ist, sollte OpenOCD alle vier CPUs des Raspberry Pi anzeigen. Es zeigt außerdem, dass die Ports 3333, 3334, 3335 und 3336 für die GDB-Kommunikation bereitgestellt werden.

=== Kernel-Upload und Debugging ===
Um sicherzugehen, öffnen wir ein weiteres "MSYS2 MSYS"-Fenster oder zweites Terminal unter Linux. Hier wechseln wir in das Verzeichnis, welches den zu testenden Code enthält. Falls der Code noch nicht kompiliert ist, muss dies jetzt erledigt werden.

Verwende für diese Versuche den kernel8.elf:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb
target extended-remote :3333
</syntaxhighlight>
Dies stellt eine Verbindung zur CPU0 her.

Lade nun den Kernel auf den Raspberry Pi hoch:
<syntaxhighlight lang="gdb">
load kernel8.elf
</syntaxhighlight>

Damit der Kernel nun startet, verwenden wir die folgenden Befehle:
<syntaxhighlight lang="gdb">
set $pc = 0x80000
continue
</syntaxhighlight>

=== Ohne Kernel-Upload ===

Wenn bereits auf dem Raspberry PI 4 der Kernel läuft, verwende folgendes:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb kernel8.elf
</syntaxhighlight>

Im Debugger dann:
<syntaxhighlight lang="gdb">
target extended-remote :3333
</syntaxhighlight>

Bare-Metal Debugging (JTAG, RPI 4)

2026-06-05T13:00:48Z

Satyria: /* Verdrahtung */

== Einleitung ==
Bei der Entwicklung von Software wird oft ein Debugger benötigt, um Fehler zu finden und zu beheben. Ein gängiger Debugger ist GDB. Solange das Programm aus einer Umgebung wie Linux oder Windows startbar ist, kann dieser Debugger direkt verwendet werden. Bei der Bare-Metal-Entwicklung sind die Dinge jedoch etwas schwieriger, da hier die gewohnte Betriebssystemumgebung fehlt. In solchen Fällen sind Emulatoren oder spezielle Hardwarelösungen nötig.

Da Emulatoren meist nicht zu 100 % die Hardware widerspiegeln können, verwenden wir das Hostsystem, welches direkt mit dem Raspberry Pi 4 (RPI4) kommuniziert. Das Programm wird auf dem Raspberry Pi direkt ausgeführt. Über das Hostsystem können wir jedoch den Code direkt manipulieren und sehen das Ergebnis unmittelbar auf der Hardware.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Hardware vorbereiten ==
Das FT232H Modul wurde zwar mit Stiftleisten geliefert, aber diese mussten zunächst auf das Modul aufgelötet werden. Anschließend konnte mit Kabelbrücken die Verbindung mit dem Raspberry Pi 4 hergestellt werden.
=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO22 || 15
|-
| AD7 || GPIO23 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

== Verwendung von Windows ==
Unter Windows verwenden wir die MSYS2-Umgebung. Diese bietet eine Unix-ähnliche Umgebung unter Windows und ist nützlich für viele Entwicklungsaufgaben.

=== Installation und Einrichtung ===
Falls noch nicht geschehen, installieren wir MSYS2 nach folgender Anleitung [[Programmierumgebung erstellen (Konsole)]] und richten die Programmierumgebung ein, indem wir die folgenden Befehle ausführen:

* Starte MSYS2 MSYS.
* Gib die folgenden Befehle ein, um OpenOCD zu installieren und die Umgebungsvariablen zu setzen:
<syntaxhighlight lang="shell">
pacman -S mingw64/mingw-w64-x86_64-openocd
echo 'export PATH="/mingw64/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter driver ftdi

ftdi vid_pid 0x0403 0x6014

# Setze das Layout für JTAG-Signale (TDI, TDO, TMS, TCK, nTRST, nSRST)
# Diese Pins sind für JTAG erforderlich
ftdi layout_init 0x0000 0x000b
ftdi layout_signal nTRST -data 0x0020 -oe 0x0020
ftdi layout_signal nSRST -data 0x0010 -oe 0x0010
ftdi layout_signal TDI -data 0x0011 -oe 0x0011
ftdi layout_signal TDO -data 0x0012 -oe 0x0012
ftdi layout_signal TMS -data 0x0013 -oe 0x0013
ftdi layout_signal TCK -data 0x0014 -oe 0x0014

# Wählen Sie den JTAG-Modus aus
transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "C:\msys64\mingw64\share\openocd\scripts\interface\ftdi" ab, wenn MSYS2 nach den Vorgaben installiert wurde.

=== Treiberinstallation ===
OpenOCD möchte auf das Gerät über libusb zugreifen. In der Regel bietet Windows diesen Treiber nicht, sodass wir hier noch einen Treiber installieren müssen. Dazu verwenden wir "Zadig", welches von https://zadig.akeo.ie/ heruntergeladen werden kann.

# Installiere Zadig.
# Starte Zadig und aktiviere im Menü "Options" die Option "List All Devices".
# Wähle "Single RS232-HS" aus der Geräteliste.
# Als Treiber wähle "libusbK" aus und klicke auf "Replace Driver".
Damit ist Windows bereit, mit dem Modul über OpenOCD zu kommunizieren.

== Verwendung von Linux ==

=== Installation und Einrichtung ===
Zunächst benötigen wir OpenOCD:
<syntaxhighlight lang="shell">
sudo apt update
sudo apt install openocd
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter driver ftdi

ftdi vid_pid 0x0403 0x6014

# Setze das Layout für JTAG-Signale (TDI, TDO, TMS, TCK, nTRST, nSRST)
# Diese Pins sind für JTAG erforderlich
ftdi layout_init 0x0000 0x000b
ftdi layout_signal nTRST -data 0x0020 -oe 0x0020
ftdi layout_signal nSRST -data 0x0010 -oe 0x0010
ftdi layout_signal TDI -data 0x0011 -oe 0x0011
ftdi layout_signal TDO -data 0x0012 -oe 0x0012
ftdi layout_signal TMS -data 0x0013 -oe 0x0013
ftdi layout_signal TCK -data 0x0014 -oe 0x0014

# Wählen Sie den JTAG-Modus aus
transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "/usr/share/openocd/scripts/interface/ftdi" ab.

== Raspberry Pi vorbereiten ==
Nachdem unser Betriebssystem auf dem Raspberry Pi eingerichtet ist, müssen wir den Raspberry Pi 4 für Bare-Metal-Programmierung vorbereiten. Dazu schreiben wir ein kleines Programm, das nur eine Endlosschleife erzeugt, aber den Raspberry Pi startet:
<syntaxhighlight lang="asm">
//
// The boot program for RPI4
// 07.03.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

b _start // endless loop
</syntaxhighlight>

Wir verwenden ein Makefile, um das Programm zu kompilieren und zu linken (siehe [[Unser erstes Programm in C (PI4)#Kompilieren des Programms mit Make]]). Den erzeugten "kernel8.img" kopieren wir auf die SD-Karte. Beachte, dass auch folgende Dateien im Root-Verzeichnis der SD-Karte liegen müssen:
* bcm2711-rpi-4-b.dtb
* bootcode.bin
* fixup4.dat
* start4.elf

Nun müssen wir dem Raspberry Pi auch mitteilen, dass er auf JTAG reagiert. Dazu erstellen wir eine config.txt mit folgendem Inhalt:

<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>
Diese Datei legen wir ebenfalls in das Root-Verzeichnis der SD-Karte.

== Starten von OpenOCD und Verwendung von GDB ==
=== Verbindung herstellen ===
Verbinde zunächst das FT232H-Modul per USB mit dem Hostsystem. Auf dem Modul sollte nun eine LED leuchten, welche anzeigt, dass das Gerät betriebsbereit ist. Starte den Raspberry Pi. Wenn du ihn an einem Monitor angeschlossen hast, wird auf dem Bildschirm das Regenbogenbild angezeigt, was bedeutet, dass das System gestartet wurde.

Starte nun "MSYS2 MSYS" oder unter Linux ein Terminal:
[[Datei:OpenOcd.png|mini]]
<syntaxhighlight lang="shell">
openocd -f interface/ftdi/ft232h-jtag.cfg -f target/bcm2711.cfg
</syntaxhighlight>
Wenn alles korrekt eingerichtet ist, sollte OpenOCD alle vier CPUs des Raspberry Pi anzeigen. Es zeigt außerdem, dass die Ports 3333, 3334, 3335 und 3336 für die GDB-Kommunikation bereitgestellt werden.

=== Kernel-Upload und Debugging ===
Um sicherzugehen, öffnen wir ein weiteres "MSYS2 MSYS"-Fenster oder zweites Terminal unter Linux. Hier wechseln wir in das Verzeichnis, welches den zu testenden Code enthält. Falls der Code noch nicht kompiliert ist, muss dies jetzt erledigt werden.

Verwende für diese Versuche den kernel8.elf:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb
target extended-remote :3333
</syntaxhighlight>
Dies stellt eine Verbindung zur CPU0 her.

Lade nun den Kernel auf den Raspberry Pi hoch:
<syntaxhighlight lang="gdb">
load kernel8.elf
</syntaxhighlight>

Damit der Kernel nun startet, verwenden wir die folgenden Befehle:
<syntaxhighlight lang="gdb">
set $pc = 0x80000
continue
</syntaxhighlight>

=== Ohne Kernel-Upload ===

Wenn bereits auf dem Raspberry PI 4 der Kernel läuft, verwende folgendes:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb kernel8.elf
</syntaxhighlight>

Im Debugger dann:
<syntaxhighlight lang="gdb">
target extended-remote :3333
</syntaxhighlight>

Bare-Metal Debugging (JTAG, RPI 4)

2026-06-05T12:58:25Z

Satyria:

== Einleitung ==
Bei der Entwicklung von Software wird oft ein Debugger benötigt, um Fehler zu finden und zu beheben. Ein gängiger Debugger ist GDB. Solange das Programm aus einer Umgebung wie Linux oder Windows startbar ist, kann dieser Debugger direkt verwendet werden. Bei der Bare-Metal-Entwicklung sind die Dinge jedoch etwas schwieriger, da hier die gewohnte Betriebssystemumgebung fehlt. In solchen Fällen sind Emulatoren oder spezielle Hardwarelösungen nötig.

Da Emulatoren meist nicht zu 100 % die Hardware widerspiegeln können, verwenden wir das Hostsystem, welches direkt mit dem Raspberry Pi 4 (RPI4) kommuniziert. Das Programm wird auf dem Raspberry Pi direkt ausgeführt. Über das Hostsystem können wir jedoch den Code direkt manipulieren und sehen das Ergebnis unmittelbar auf der Hardware.

Der Raspberry Pi unterstützt für solche Kommunikation das JTAG-Protokoll. Leider können Hostsysteme dieses Protokoll selten direkt bereitstellen, weshalb wir auf zusätzliche Hardware angewiesen sind. Eine günstige Option ist das "CJMCU FT232H Modul" (https://amzn.eu/d/hb8tKuA), welches ich für diese Anleitung verwendet habe.

== Hardware vorbereiten ==
Das FT232H Modul wurde zwar mit Stiftleisten geliefert, aber diese mussten zunächst auf das Modul aufgelötet werden. Anschließend konnte mit Kabelbrücken die Verbindung mit dem Raspberry Pi 4 hergestellt werden.
=== Verdrahtung ===
Die Verdrahtung zwischen dem FT232H Modul und dem Raspberry Pi 4 erfolgt wie folgt:
[[Datei:Verbindung.png|mini]]

{| class="wikitable"
|+ Verdrahtung
|-
! FT232H !! colspan="2"|Raspi 4
|-
! Name !! GPIO !! PIN
|-
| AD0 || GPIO25 || 22
|-
| AD1 || GPIO26 || 37
|-
| AD2 || GPIO24 || 18
|-
| AD3 || GPIO27 || 13
|-
| AD4 || GPIO27 || 15
|-
| AD7 || GPIO27 || 16
|-
| GND || GND || 6 (9,14,20,25,30,34,39)
|}

== Verwendung von Windows ==
Unter Windows verwenden wir die MSYS2-Umgebung. Diese bietet eine Unix-ähnliche Umgebung unter Windows und ist nützlich für viele Entwicklungsaufgaben.

=== Installation und Einrichtung ===
Falls noch nicht geschehen, installieren wir MSYS2 nach folgender Anleitung [[Programmierumgebung erstellen (Konsole)]] und richten die Programmierumgebung ein, indem wir die folgenden Befehle ausführen:

* Starte MSYS2 MSYS.
* Gib die folgenden Befehle ein, um OpenOCD zu installieren und die Umgebungsvariablen zu setzen:
<syntaxhighlight lang="shell">
pacman -S mingw64/mingw-w64-x86_64-openocd
echo 'export PATH="/mingw64/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter driver ftdi

ftdi vid_pid 0x0403 0x6014

# Setze das Layout für JTAG-Signale (TDI, TDO, TMS, TCK, nTRST, nSRST)
# Diese Pins sind für JTAG erforderlich
ftdi layout_init 0x0000 0x000b
ftdi layout_signal nTRST -data 0x0020 -oe 0x0020
ftdi layout_signal nSRST -data 0x0010 -oe 0x0010
ftdi layout_signal TDI -data 0x0011 -oe 0x0011
ftdi layout_signal TDO -data 0x0012 -oe 0x0012
ftdi layout_signal TMS -data 0x0013 -oe 0x0013
ftdi layout_signal TCK -data 0x0014 -oe 0x0014

# Wählen Sie den JTAG-Modus aus
transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "C:\msys64\mingw64\share\openocd\scripts\interface\ftdi" ab, wenn MSYS2 nach den Vorgaben installiert wurde.

=== Treiberinstallation ===
OpenOCD möchte auf das Gerät über libusb zugreifen. In der Regel bietet Windows diesen Treiber nicht, sodass wir hier noch einen Treiber installieren müssen. Dazu verwenden wir "Zadig", welches von https://zadig.akeo.ie/ heruntergeladen werden kann.

# Installiere Zadig.
# Starte Zadig und aktiviere im Menü "Options" die Option "List All Devices".
# Wähle "Single RS232-HS" aus der Geräteliste.
# Als Treiber wähle "libusbK" aus und klicke auf "Replace Driver".
Damit ist Windows bereit, mit dem Modul über OpenOCD zu kommunizieren.

== Verwendung von Linux ==

=== Installation und Einrichtung ===
Zunächst benötigen wir OpenOCD:
<syntaxhighlight lang="shell">
sudo apt update
sudo apt install openocd
</syntaxhighlight>
=== Konfigurationsdatei erstellen ===
Leider fehlt uns eine Konfigurationsdatei, die JTAG und FT232H beschreibt. Daher erstellen wir eine Datei namens ft232h-jtag.cfg mit folgendem Inhalt:

<syntaxhighlight lang="C">
adapter driver ftdi

ftdi vid_pid 0x0403 0x6014

# Setze das Layout für JTAG-Signale (TDI, TDO, TMS, TCK, nTRST, nSRST)
# Diese Pins sind für JTAG erforderlich
ftdi layout_init 0x0000 0x000b
ftdi layout_signal nTRST -data 0x0020 -oe 0x0020
ftdi layout_signal nSRST -data 0x0010 -oe 0x0010
ftdi layout_signal TDI -data 0x0011 -oe 0x0011
ftdi layout_signal TDO -data 0x0012 -oe 0x0012
ftdi layout_signal TMS -data 0x0013 -oe 0x0013
ftdi layout_signal TCK -data 0x0014 -oe 0x0014

# Wählen Sie den JTAG-Modus aus
transport select jtag
</syntaxhighlight>

Diese Datei legen wir ins Verzeichnis "/usr/share/openocd/scripts/interface/ftdi" ab.

== Raspberry Pi vorbereiten ==
Nachdem unser Betriebssystem auf dem Raspberry Pi eingerichtet ist, müssen wir den Raspberry Pi 4 für Bare-Metal-Programmierung vorbereiten. Dazu schreiben wir ein kleines Programm, das nur eine Endlosschleife erzeugt, aber den Raspberry Pi startet:
<syntaxhighlight lang="asm">
//
// The boot program for RPI4
// 07.03.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

b _start // endless loop
</syntaxhighlight>

Wir verwenden ein Makefile, um das Programm zu kompilieren und zu linken (siehe [[Unser erstes Programm in C (PI4)#Kompilieren des Programms mit Make]]). Den erzeugten "kernel8.img" kopieren wir auf die SD-Karte. Beachte, dass auch folgende Dateien im Root-Verzeichnis der SD-Karte liegen müssen:
* bcm2711-rpi-4-b.dtb
* bootcode.bin
* fixup4.dat
* start4.elf

Nun müssen wir dem Raspberry Pi auch mitteilen, dass er auf JTAG reagiert. Dazu erstellen wir eine config.txt mit folgendem Inhalt:

<syntaxhighlight>
gpio=22-27=np
enable_jtag_gpio=1
</syntaxhighlight>
Diese Datei legen wir ebenfalls in das Root-Verzeichnis der SD-Karte.

== Starten von OpenOCD und Verwendung von GDB ==
=== Verbindung herstellen ===
Verbinde zunächst das FT232H-Modul per USB mit dem Hostsystem. Auf dem Modul sollte nun eine LED leuchten, welche anzeigt, dass das Gerät betriebsbereit ist. Starte den Raspberry Pi. Wenn du ihn an einem Monitor angeschlossen hast, wird auf dem Bildschirm das Regenbogenbild angezeigt, was bedeutet, dass das System gestartet wurde.

Starte nun "MSYS2 MSYS" oder unter Linux ein Terminal:
[[Datei:OpenOcd.png|mini]]
<syntaxhighlight lang="shell">
openocd -f interface/ftdi/ft232h-jtag.cfg -f target/bcm2711.cfg
</syntaxhighlight>
Wenn alles korrekt eingerichtet ist, sollte OpenOCD alle vier CPUs des Raspberry Pi anzeigen. Es zeigt außerdem, dass die Ports 3333, 3334, 3335 und 3336 für die GDB-Kommunikation bereitgestellt werden.

=== Kernel-Upload und Debugging ===
Um sicherzugehen, öffnen wir ein weiteres "MSYS2 MSYS"-Fenster oder zweites Terminal unter Linux. Hier wechseln wir in das Verzeichnis, welches den zu testenden Code enthält. Falls der Code noch nicht kompiliert ist, muss dies jetzt erledigt werden.

Verwende für diese Versuche den kernel8.elf:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb
target extended-remote :3333
</syntaxhighlight>
Dies stellt eine Verbindung zur CPU0 her.

Lade nun den Kernel auf den Raspberry Pi hoch:
<syntaxhighlight lang="gdb">
load kernel8.elf
</syntaxhighlight>

Damit der Kernel nun startet, verwenden wir die folgenden Befehle:
<syntaxhighlight lang="gdb">
set $pc = 0x80000
continue
</syntaxhighlight>

=== Ohne Kernel-Upload ===

Wenn bereits auf dem Raspberry PI 4 der Kernel läuft, verwende folgendes:
<syntaxhighlight lang="gdb">
aarch64-none-elf-gdb kernel8.elf
</syntaxhighlight>

Im Debugger dann:
<syntaxhighlight lang="gdb">
target extended-remote :3333
</syntaxhighlight>

Professionelle GUI mit Debugging für Bare-Metal auf dem Raspberry Pi 5

2026-06-05T10:53:39Z

Satyria: /* Hardware vorbereiten und SD-Karte einrichten */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Um direkt mit dem Raspberry Pi 5 zu kommunizieren und Programme zu debuggen, wird zusätzlich eine '''Raspberry Pi Debug Probe''' benötigt. Diese wird über USB mit einem Windows-Rechner und über die Debug-Pins mit dem Raspberry Pi 5 verbunden.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und der Debug Probe verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Überprüfen Sie anschließend, ob die Datei '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' existiert. Diese wird in der Regel standardmäßig mitgeliefert. Sollte sie fehlen, erstellen Sie diese Datei neu mit folgendem Inhalt:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>
Da in älteren oder Standard-OpenOCD-Releases ein passendes Target-Profil für den neuen Broadcom-Chip BCM2712 des Raspberry Pi 5 fehlt, müssen wir dieses manuell anlegen. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP für direkten Zugriff
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# Diese Adressen wurden aus der ROM-Table via 'dap info 0'-Befehl ausgelesen
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Standard-Target ist cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Überschreibt den standardmäßigen "reset halt" Befehl von VS-Code
"overrideResetCommands": [
"monitor halt"
],

// Befehle, die direkt nach dem Verbinden ausgeführt werden
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Zwingt den Prozessor direkt auf die Startadresse
],

"preLaunchTask": "Kompilieren"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI5)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Bit 9 auf 0 setzen
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Bit 9 auf 1 setzen
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO-Definitionen für den Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''kernel_address=0x80000''' setzt die Startadresse im RAM fest, an die unser Kernel geladen wird.

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 5 in den JTAG-/SWD-Modus um. Dadurch wird die Kommunikation mit der Raspberry Pi Debug Probe überhaupt erst möglich.



Hardware verbinden:
* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 5.
* Verbinden Sie die Raspberry Pi Debug Probe über das mitgelieferte 3-Pol-UART/Debug-Kabel mit dem dedizierten Debug-Port des Raspberry Pi 5 (befindet sich zwischen den Micro-HDMI-Ports).
* Schließen Sie die Debug Probe per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 5 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel_2712.elf''' (für den Debugger inklusive Symbolen) und '''kernel_2712.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 5 über die Debug Probe auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 5 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal auf dem Raspberry Pi 5

2026-06-05T10:30:47Z

Satyria: /* Hardware vorbereiten und SD-Karte einrichten */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Um direkt mit dem Raspberry Pi 5 zu kommunizieren und Programme zu debuggen, wird zusätzlich eine '''Raspberry Pi Debug Probe''' benötigt. Diese wird über USB mit einem Windows-Rechner und über die Debug-Pins mit dem Raspberry Pi 5 verbunden.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und der Debug Probe verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Überprüfen Sie anschließend, ob die Datei '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' existiert. Diese wird in der Regel standardmäßig mitgeliefert. Sollte sie fehlen, erstellen Sie diese Datei neu mit folgendem Inhalt:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>
Da in älteren oder Standard-OpenOCD-Releases ein passendes Target-Profil für den neuen Broadcom-Chip BCM2712 des Raspberry Pi 5 fehlt, müssen wir dieses manuell anlegen. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP für direkten Zugriff
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# Diese Adressen wurden aus der ROM-Table via 'dap info 0'-Befehl ausgelesen
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Standard-Target ist cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Überschreibt den standardmäßigen "reset halt" Befehl von VS-Code
"overrideResetCommands": [
"monitor halt"
],

// Befehle, die direkt nach dem Verbinden ausgeführt werden
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Zwingt den Prozessor direkt auf die Startadresse
],

"preLaunchTask": "Kompilieren"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI5)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Bit 9 auf 0 setzen
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Bit 9 auf 1 setzen
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO-Definitionen für den Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''kernel_address=0x80000''' setzt die Startadresse im RAM fest, an die unser Kernel geladen wird.

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 5 in den JTAG-/SWD-Modus um. Dadurch wird die Kommunikation mit der Raspberry Pi Debug Probe überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen: https://www.satyria.de/arm/sources/RPI4/C/RPI4_ImageVSCode.zip

Hardware verbinden:
* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 5.
* Verbinden Sie die Raspberry Pi Debug Probe über das mitgelieferte 3-Pol-UART/Debug-Kabel mit dem dedizierten Debug-Port des Raspberry Pi 5 (befindet sich zwischen den Micro-HDMI-Ports).
* Schließen Sie die Debug Probe per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 5 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel_2712.elf''' (für den Debugger inklusive Symbolen) und '''kernel_2712.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 5 über die Debug Probe auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 5 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Professionelle GUI mit Debugging für Bare-Metal auf dem Raspberry Pi 5

2026-06-05T10:29:30Z

Satyria: /* Hardware vorbereiten und SD-Karte einrichten */

Viele Entwickler wünschen sich eine professionelle Möglichkeit, die Bare-Metal-Entwicklung direkt in einer grafischen Benutzeroberfläche (GUI) zu realisieren. In dieser Anleitung zeige ich Ihnen, wie Sie eine solche Entwicklungsumgebung aufsetzen können. Als IDE (Integrated Development Environment) nutzen wir Visual Studio Code von Microsoft, das unter der Open-Source-Lizenz MIT veröffentlicht ist.

Um direkt mit dem Raspberry Pi 5 zu kommunizieren und Programme zu debuggen, wird zusätzlich eine '''Raspberry Pi Debug Probe''' benötigt. Diese wird über USB mit einem Windows-Rechner und über die Debug-Pins mit dem Raspberry Pi 5 verbunden.

== Software-Voraussetzungen ==
Wie eingangs erwähnt, nutzen wir als GUI Visual Studio Code. Die Software kann kostenlos von der offiziellen Website heruntergeladen werden:

👉 https://code.visualstudio.com/

Zusätzlich benötigen wir die offizielle Toolchain von ARM, um Code für die AArch64-Architektur des Raspberry Pi 5 kompilieren zu können. Diese steht hier zum Download bereit:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Hinweis: Zum Zeitpunkt der Erstellung dieses Tutorials wurde die Version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' verwendet. Da die Toolchain kontinuierlich weiterentwickelt wird, kann sich die Versionsnummer bei Ihrem Download leicht unterscheiden.

Für die Verbindung zwischen dem PC und der Debug Probe verwenden wir OpenOCD (Open On-Chip Debugger). Eine vorkompilierte Windows-Version wird über das xPack-Projekt bereitgestellt:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direkter Download-Link der verwendeten Version: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Zuletzt benötigen wir noch das Build-Werkzeug '''GNU Make''', welches wir im nächsten Schritt direkt über die Windows-Konsole installieren.

== Installation und Einrichtung ==
=== Toolchain einrichten ===
Da Windows gelegentlich Probleme mit sehr langen Pfadnamen haben kann, benennen wir das heruntergeladene Archiv der Toolchain zunächst in '''toolchain.zip''' um.

Entpacken Sie das ZIP-Archiv vollständig.

Erstellen Sie ein neues Verzeichnis direkt auf Ihrem Systemlaufwerk: '''C:\tools'''.

Kopieren Sie den gesamten Inhalt des entpackten Toolchain-Ordners in dieses Verzeichnis, sodass die Ordnerstruktur direkt mit '''C:\tools\bin''' beginnt.

=== OpenOCD einrichten und konfigurieren ===
Entpacken Sie das OpenOCD-ZIP-Archiv.

Im entpackten Ordner finden Sie das Unterverzeichnis '''xpack-openocd-0.12.0-7''' (bzw. Ihre aktuellere Version). Benennen Sie diesen Ordner einfach in '''openocd''' um.

Verschieben Sie den gesamten Ordner '''openocd''' nach '''C:\tools''', sodass der Pfad '''C:\tools\openocd''' entsteht.

Überprüfen Sie anschließend, ob die Datei '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' existiert. Diese wird in der Regel standardmäßig mitgeliefert. Sollte sie fehlen, erstellen Sie diese Datei neu mit folgendem Inhalt:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>
Da in älteren oder Standard-OpenOCD-Releases ein passendes Target-Profil für den neuen Broadcom-Chip BCM2712 des Raspberry Pi 5 fehlt, müssen wir dieses manuell anlegen. Erstellen Sie dazu eine neue Datei unter dem Pfad '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' und fügen Sie folgenden Inhalt ein:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP für direkten Zugriff
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# Diese Adressen wurden aus der ROM-Table via 'dap info 0'-Befehl ausgelesen
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Standard-Target ist cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>
=== GNU Make installieren ===
Unter Windows stellt Microsoft ein Paket für '''GNU Make''' bereit, das sich komfortabel über den integrierten Paketmanager installieren lässt. Öffnen Sie ein Terminal (Eingabeaufforderung oder PowerShell) und geben Sie folgenden Befehl ein:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
Das Programm wird standardmäßig in das Verzeichnis '''C:\Program Files (x86)\GnuWin32\bin''' installiert. Damit '''Make''' reibungslos mit unseren anderen Tools zusammenarbeitet, kopieren Sie den gesamten Inhalt dieses bin-Ordners in unser zuvor angelegtes Verzeichnis '''C:\tools\bin'''.

=== Umgebungsvariable „Path“ anpassen ===
Damit Windows und Visual Studio Code die installierten Tools (Compiler, Make und OpenOCD) systemweit über die Konsole finden können, müssen wir die ausführbaren Dateien dem Systempfad hinzufügen.

Drücken Sie die '''Windows-Taste''' und tippen Sie im Suchfeld „''Umgebungsvariable''“ ein.

Wählen Sie den Punkt „''Systemumgebungsvariablen bearbeiten''“ und klicken Sie im nächsten Fenster unten auf den Button „''Umgebungsvariablen...''“.
[[Datei:Path1.png|300x300px]]

Suchen Sie im Bereich „''Benutzervariablen''“ oder „''Systemvariablen''“ nach dem Eintrag '''Path''' (oder PATH) und wählen Sie Bearbeiten.

[[Datei:Path2.png|300x300px]]

Fügen Sie der Liste die folgenden zwei Pfade als separate, neue Zeilen hinzu:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Bestätigen Sie alle geöffneten Fenster mit '''OK'''.

[[Datei:Path3.png|300x300px]]

Die grundlegende Toolchain ist damit erfolgreich installiert und eingerichtet. Im nächsten Teil widmen wir uns der Konfiguration von Visual Studio Code für das eigentliche Bare-Metal-Projekt.

=== Visual Studio Code einrichten ===
Nachdem die grundlegende Toolchain installiert ist, richten wir nun die Entwicklungsumgebung in Visual Studio Code ein.

Zunächst installiere Visual Studio Code komplett aus dem vorhergehenden Download.

==== VS Code Erweiterungen (Extensions) installieren ====
Öffnen Sie Visual Studio Code. Um die Bare-Metal-Entwicklung so komfortabel wie möglich zu gestalten, installieren wir zunächst einige essenzielle Erweiterungen. Klicken Sie dazu auf das Erweiterungs-Icon auf der linken Menüleiste (oder drücken Sie STRG + UMSCHALT + X) und suchen Sie nach folgenden Extensions:

* C/C++ (von Microsoft): Bietet Syntax-Highlighting und Code-Vervollständigung (IntelliSense) für C/C++.
* C/C++ Extension Pack (optional): Bringt zusätzliche nützliche Werkzeuge für die C-Entwicklung mit.
* Cortex-Debug (von marus25): Die Schlüssel-Erweiterung, die es uns ermöglicht, via OpenOCD direkt auf dem Raspberry Pi 5 zu debuggen.
* Arm Assembly (von dan-c-underwood): Bietet exzellente Unterstützung und Highlighting für ARM-Assembler-Code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Sprache der Benutzeroberfläche auf Deutsch umstellen ====
Falls Ihr VS Code englischsprachig ist und Sie zum Beispiel die deutsche Oberfläche bevorzugen:

Drücken Sie '''STRG + UMSCHALT + P''', um die Befehlspalette zu öffnen. Tippen Sie ''Configure Display Language'' ein und drücken Sie '''Enter'''.

Wählen Sie „Deutsch“ aus (falls nicht aufgelistet, können Sie es darüber direkt nachinstallieren).

Starten Sie VS Code neu.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Projektverzeichnis erstellen und öffnen ====
Erstellen Sie nun ein Verzeichnis auf Ihrer Festplatte, in dem Ihr Bare-Metal-Projekt leben soll. In diesem Beispiel verwenden wir den Pfad '''D:\projekt1'''. Wählen Sie in VS Code ''Datei -> Ordner öffnen...'' und wählen Sie das Verzeichnis '''D:\projekt1''' aus. Bestätigen Sie die Sicherheitsabfrage, ob Sie den Autoren des Ordners vertrauen, mit „''Ja, ich vertraue den Autoren''“.

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Die .vscode Konfigurationsdateien anlegen ====

Damit VS Code weiß, welchen Compiler es nutzen soll und wie der Debugger gestartet wird, legen wir ein Konfigurationsverzeichnis an. Erstellen Sie im Hauptverzeichnis Ihres Projekts einen neuen Ordner mit dem exakten Namen '''.vscode''' (den Punkt am Anfang nicht vergessen!). Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner '''.vscode''' und legen Sie nacheinander die folgenden drei Dateien an.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Kopieren Sie jeweils den entsprechenden JSON-Code hinein:

* '''c_cpp_properties.json''': Diese Datei konfiguriert die Code-Vervollständigung (IntelliSense), damit VS Code die ARM-spezifischen Befehle und Header versteht.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': Diese Datei steuert den Debugger (Cortex-Debug). Sie sorgt dafür, dass Ihr Code via OpenOCD auf den Raspberry Pi 5 geladen und der Prozessor exakt an der Startadresse gestoppt wird.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Überschreibt den standardmäßigen "reset halt" Befehl von VS-Code
"overrideResetCommands": [
"monitor halt"
],

// Befehle, die direkt nach dem Verbinden ausgeführt werden
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Zwingt den Prozessor direkt auf die Startadresse
],

"preLaunchTask": "Kompilieren"
}
]
}
</syntaxhighlight>
* '''tasks.json''': Hier wird der automatisierte Build-Prozess definiert. Bevor der Debugger startet, wird über diese Task automatisch make aufgerufen.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Kompilieren",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Speichern Sie alle Konfigurationen ab, indem Sie im Menü auf ''Datei -> Alles speichern'' klicken.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Hinweis zu vermeintlichen Fehlermeldungen ====
Nach dem Speichern der '''c_cpp_properties.json''' fällt Ihnen im Datei-Explorer oder im Reiter „Probleme“ (unten in VS Code) vermutlich eine kleine rote „'''2'''“ auf. Dies deutet auf aktive Warnungen hin. Wenn Sie auf die Meldung klicken, sehen Sie den Grund: VS Code beschwert sich, dass die beiden Verzeichnis-Pfade '''${workspaceFolder}/include''' und '''${workspaceFolder}/src''' nicht existieren.

[[Datei:Prob1.png|200x200px]]

💡Keine Sorge: Das ist völlig korrekt! Da wir ein leeres Projekt gestartet haben, gibt es diese Ordner einfach noch nicht. Sobald Sie im weiteren Verlauf Ihres Projekts die Ordner '''src''' und '''include''' anlegen, verschwindet diese Warnung von selbst.

Tipp: Sollte VS Code neu erstellte Ordner einmal nicht sofort registrieren, können Sie die Entwicklungsumgebung schnell aktualisieren. Drücken Sie dazu '''F1''', tippen Sie ''Reload Window'' ein und bestätigen Sie mit '''Enter'''. Das lädt die Oberfläche neu, ohne Ihre Arbeit zu unterbrechen.

== Sourcecode, Linkerscript und Makefile ==
=== Das Quellcode-Verzeichnis (src/) ===
Um unser Setup praktisch zu testen, verwenden wir ein minimalistisches LED-Blinkbeispiel in C und Assembler ([[Lass die LED leuchten in C (PI5)]]). Dieses Projekt nutzt die Aufteilung in verschiedene Dateien, damit Sie die Querverweise im Code und den Komfort einer professionellen GUI direkt erleben können.

Erstellen Sie im Hauptverzeichnis Ihres Projekts (z. B. '''D:\projekt1''') einen neuen Ordner namens '''src'''.

💡 Wichtiger Hinweis für Assembler-Dateien: Achten Sie darauf, dass Assembler-Dateien, die den C-Präprozessor nutzen (wie das Einbinden von Header-Dateien via '''#include'''), zwingend die Dateiendung mit einem großen „'''S'''“ ('''.S''') haben müssen. Ein kleines „s“ führt dazu, dass der Compiler die Includes ignoriert.

Erstellen Sie im Ordner '''src/''' die folgenden sechs Dateien:
'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Stellt sicher, dass der Linker dies an den Anfang des Kernel-Images setzt
.globl _start // Hier beginnt die Ausführung

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Stack-Pointer initialisieren
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Bit 9 auf 0 setzen
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Bit 9 auf 1 setzen
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 zyklen)
{
volatile u32 i;
for (i = 0; i < zyklen; i++)
{
// Leere Schleife zur Verzögerung
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Hinweis''': Sobald Sie diese Dateien gespeichert haben, wird Ihnen VS Code im „Probleme“-Tab diverse Fehler anzeigen. Der Code ist mit roten, gewellten Linien unterlegt. Das ist völlig normal, da dem Compiler aktuell die Header-Dateien (.h) fehlen und er die Verweise nicht auflösen kann.

[[Datei:Source prob.png|200x200px]]

=== Das Include-Verzeichnis (include/) ===
Um die Fehler zu beheben, legen wir nun die Header-Dateien an. Erstellen Sie dazu im Hauptverzeichnis Ihres Projekts einen neuen Ordner namens '''include'''. Legen Sie darin die folgenden sechs Dateien ab:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO-Definitionen für den Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Startadresse des Hauptprogramms
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 zyklen);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

Sobald alle Header-Dateien im include-Ordner abgespeichert sind, verschwinden die roten Linien in VS Code automatisch. Die GUI hat die Bezüge erfolgreich erkannt.

[[Datei:Null prob.png|200x200px]]

=== Linkerscript und Makefile erstellen ===

Damit aus dem Quellcode ein ausführbares Bare-Metal-Image für den Raspberry Pi 5 gebaut werden kann, benötigen wir ein ''Linkerscript'' und die Steuerungsdatei für '''GNU Make'''. Beide Dateien werden direkt im Hauptverzeichnis (Root) Ihres Projekts angelegt.
==== linker.ld ====
Dieses Skript definiert die genaue Anordnung der Code-Segmente im Arbeitsspeicher des Raspberry Pi 5.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
==== Makefile ====
Das '''Makefile''' automatisiert den Aufruf des Compilers und Linkers. Beachten Sie, dass hier explizit die Architektur des Raspberry Pi 5 ('''-mcpu=cortex-a76''') angesprochen wird.
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Wichtiger Hinweis''' zu Makefiles: Verwende keine Leerzeichen um Einrückungen zu erstellen. Dies mag '''make''' nicht. Verwende stattdessen immer ein '''TAB'''.

Vergessen Sie am Ende nicht, alle geöffneten Dateien im VS-Code-Menü über ''Datei -> Alles speichern'' zu sichern. Das Projekt ist nun vollständig konfiguriert und bereit für den ersten Build- und Debugging-Lauf!

== Hardware vorbereiten und Debugging in der GUI ==
=== Hardware vorbereiten und SD-Karte einrichten ===
Da wir den Code direkt auf der echten Hardware testen, müssen wir die SD-Karte des Raspberry Pi 5 vorbereiten. Das Betriebssystem (EEPROM/Firmware) des Pi 5 muss wissen, dass wir ein Bare-Metal-Programm via JTAG/SWD debuggen möchten.

Formatieren Sie eine MicroSD-Karte auf FAT32 und kopieren Sie folgende drei Dateien in das Hauptverzeichnis (Root) der Karte:

'''kernel_2712.img''' (Diese Datei wird gleich beim ersten Kompilieren erzeugt).
'''bcm2712-rpi-5-b.dtb''' (Der originale Device-Tree-Blob aus der offiziellen Raspberry Pi Firmware)
'''.config.txt''' (Die Konfigurationsdatei für die Firmware).

Erstellen Sie die '''config.txt''' mit exakt folgendem Inhalt:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 Was bewirkt diese Konfiguration?

'''kernel_address=0x80000''' setzt die Startadresse im RAM fest, an die unser Kernel geladen wird.

'''enable_jtag_gpio=1''' schaltet die GPIO-Pins des Raspberry Pi 5 in den JTAG-/SWD-Modus um. Dadurch wird die Kommunikation mit der Raspberry Pi Debug Probe überhaupt erst möglich.

Hier kannst du den kompletten Inhalt runterladen:

Hardware verbinden:
* Stecken Sie die vorbereitete SD-Karte in den Raspberry Pi 5.
* Verbinden Sie die Raspberry Pi Debug Probe über das mitgelieferte 3-Pol-UART/Debug-Kabel mit dem dedizierten Debug-Port des Raspberry Pi 5 (befindet sich zwischen den Micro-HDMI-Ports).
* Schließen Sie die Debug Probe per USB-Kabel an Ihren Windows-Rechner an.
* Schalten Sie den Raspberry Pi 5 ein (Stromversorgung anschließen).

Durch das aktivierte JTAG-Interface wartet der Prozessor nun an der Startadresse auf die Verbindung und Befehle des Debuggers.

=== Programm kompilieren und Debugger starten ===
Dank unserer Vorbereitungen in Visual Studio Code können wir den gesamten Build- und Flash-Prozess mit Tastenkombinationen steuern.

'''Schritt 1:'''

''Kompilieren'': Drücken Sie die Tastenkombination '''STRG + UMSCHALT + B'''. VS Code führt nun im Hintergrund das Makefile aus ('''make all'''). Im Projektverzeichnis entstehen dadurch die Dateien '''kernel_2712.elf''' (für den Debugger inklusive Symbolen) und '''kernel_2712.img''' (das reine Binärformat).

'''Schritt 2:'''

''Debugger starten'': Drücken Sie die Taste '''F5'''.

Nun passiert Folgendes vollautomatisch:

* OpenOCD baut die Verbindung zum Raspberry Pi 5 über die Debug Probe auf.
* Der GDB-Debugger wird gestartet.
* Das neu kompilierte Programm wird direkt in den RAM des Raspberry Pi 5 geladen (load).
* Der Programmzähler des Prozessors wird auf die Startadresse 0x80000 gezwungen.

Da wir in der '''launch.json''' festgelegt haben, dass der Debugger beim Start anhalten soll, stoppt die Ausführung exakt am ersten Befehl. In unserem Sourcecode springt der Cursor direkt in die Datei '''boot.S''' zum Label '''_start:'''

[[Datei:Debug1.png|300x300px]]

=== Bedienung des Debuggers in VS Code ===
Sobald der Debugger aktiv ist, verändert sich die Benutzeroberfläche von VS Code. Am oberen Bildschirmrand erscheint eine schwebende Debug-Steuerungsleiste.

[[Datei:ObDebug.png|300x300px]]

Die Steuerelemente der GUI:

{| class="wikitable"
|+ Steuerelemente
|-
! Icon / Symbol !! Aktion !! Tastenkürzel !! Beschreibung
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Hält das laufende Programm sofort an der aktuellen Stelle an.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Fortsetzen || F5 || Lässt das Programm normal weiterlaufen (bis zum nächsten Breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Einzelschritt (Step Over) || F10 || Führt die aktuelle Zeile aus. Springt bei Funktionen nicht in die Funktion hinein.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Einzelschritt (Step Into) || F11 || Springt direkt in eine Funktion hinein, um sie Zeile für Zeile zu prüfen.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Herausspringen (Step Out) || UMSCHALT + F11 || Führt den Rest der aktuellen Funktion aus und stoppt direkt nach der Rückkehr.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Neustart || STRG + UMSCHALT + F5 || Lädt das Programm neu auf den Pi und startet den Debug-Vorgang von vorne.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stoppen || UMSCHALT +F5 || Beendet die Debug-Sitzung und schließt die Verbindung zum Pi.5
|}

==== Die Debugger-Ansichten nutzen ====
Der größte Vorteil einer professionellen GUI gegenüber der GDB-Kommandozeile ist die visuelle Aufbereitung aller Prozessor-Informationen auf der linken Seite des Bildschirms:

* Variablen-Fenster (Variables): Hier werden Ihnen lokale und globale Variablen automatisch angezeigt. Sie sehen sofort, welchen Wert sie aktuell besitzen. Sie können Werte hier während des Haltepunkts sogar per Doppelklick manipulieren, um Testfälle zu simulieren!

* Überwachungs-Fenster (Watch): Wenn Sie bestimmte Variablen oder Registeradressen permanent im Auge behalten wollen, können Sie diese hier hinzufügen.

* Aufrufliste (Call Stack): Zeigt Ihnen genau, durch welche Funktionen das Programm gelaufen ist, um an den aktuellen Punkt zu gelangen.

* Register-Fenster (Cortex-Debug): Ein Highlight für Bare-Metal-Entwickler. Hier sehen Sie die CPU-Register des ARM Cortex-A76 Cores (X0 bis X30, SP, PC, etc.) im Echtzeit-Zugriff. Ändert sich ein Registerwert nach einem Einzelschritt, wird dieser farblich hervorgehoben.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Breakpoints (Haltepunkte) per Mausklick setzen ====
Das Eintippen von Speicheradressen in GDB gehört der Vergangenheit an. In VS Code bewegen Sie einfach die Maus links neben die Zeilennummern im Sourcecode (z. B. in der kernel.c in der Zeile ''LED_on();''). Ein schwach roter Punkt erscheint. Mit einem einfachen Linksklick aktivieren Sie den Breakpoint (er wird kräftig rot). Wenn Sie nun '''F5''' (Fortsetzen) drücken, läuft das Programm so lange, bis es genau diese Zeile erreicht, und friert die CPU ein. Ein weiterer Klick auf den Punkt entfernt den Haltepunkt wieder.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Zusammenfassung ==
Damit haben Sie eine vollwertige, professionelle Entwicklungsumgebung mit Hardware-Debugging für den Raspberry Pi 5 eingerichtet!

Unser erstes Programm in C (PI4)

2026-06-05T10:25:36Z

Satyria: /* Kompilieren und Ausführen */

== Einführung ==
In diesem Kurs werden wir die Grundlagen der Programmierung des Raspberry Pi 4 erlernen. Ähnlich wie bei der Programmierung des Raspberry Pi 5, gibt es einige Unterschiede, hauptsächlich bedingt durch die Unterstützung von USB und die umfangreichere Dokumentation für den Raspberry Pi 4. Für diesen Kurs habe ich Material vom Raspberry Pi 5 angepasst, um die Programmierung des Raspberry Pi 4 zu erläutern.

Ein Terminal wurde programmiert, das sich sehr gut zum Debuggen eignet. Dies werden wir in unserem Kurs ebenfalls verwenden.

-----
== Ziel unseres ersten Programms ==
Unser erstes Programm wird eine einfache Endlosschleife enthalten. Dies dient als Basis für weitere Experimente und Versuche. Ich werde erklären, wie ein solches Programm erstellt, kompiliert und ausgeführt wird.

== Erstellung des Sourcecodes ==
Leider kommen wir bei Bare-Metal-Programmierung in C nicht um Assembler herum. Auch wenn das Assemblerprogramm zunächst nicht viel tut, wird es später beispielsweise für die Interrupt-Programmierung benötigt. Erstelle zunächst das Verzeichnis "src", in der wir unseren Sourcecode ablegen werden.

=== Assembler-Code (boot.S) ===

Öffnen Sie ein Textprogramm und schreiben Sie folgendes erstes Assemblerprogramm:

<syntaxhighlight lang="asm">
//
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

mov sp, #0x80000 // Create a stack of 512KB (524288 bytes)
b main // Branch to "main"
</syntaxhighlight>

Speichern Sie die Datei im Standardverzeichnis unter Windows: C:\msys64\home\xxx (wobei xxx in der Regel Ihr Benutzername ist). Unter Linux können Sie die Datei im Home-Verzeichnis speichern. Geben Sie der Datei den Namen boot.S. Die Endung .S kennzeichnet die Datei als Assembler-Sourcecode.

=== C-Code (main.c) ===

Nun erstellen wir eine main.c Datei für unser erstes Programm:

<syntaxhighlight lang="C">
//
// main.c
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

int main (void)
{
while (1){}
}
</syntaxhighlight>

Hier wird eine einfache Endlosschleife erzeugt.

== Kompilieren des Programms mit Make ==
Um unser Programm zu kompilieren, muss zunächst die Programmierumgebung eingerichtet werden. Verwenden Sie hierzu die entsprechenden Anleitungen. Diese funktionieren auch für den Raspberry Pi 4:

[[Programmierumgebung erstellen (Konsole)]]

[[Programmierumgebung erstellen (64-Bit)]]

Erstellen Sie dann ein Makefile, welches im Root-Verzeichnis des Projektes abgelegt wird:

<syntaxhighlight lang="makefile">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

Speichern Sie diese Datei unter dem Namen Makefile.

Wenn Sie mehr über den Inhalt erfahren möchten, schauen Sie unter "[[Arbeiten mit Make und Linker-Script]]" nach.

== Linker-Script (linker.ld) ==
Erstellen Sie das folgende Linker-Script, welches wir unter [[Arbeiten mit Make und Linker-Script]] beschrieben haben. Dieses wird, wie das Makefile in das Root-Verzeichnis abgelegt:

<syntaxhighlight lang="shell">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text*)
_etext = .;
}
.rodata : {
*(.rodata*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data*)
}
.bss : {
__bss_start = .;
*(.bss*)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
Speichern Sie diese Datei unter dem Namen linker.ld.

== Kompilieren und Ausführen ==
Bevor wir kompilieren, prüfe deine Verzeichnisstruktur:
<syntaxhighlight lang="shell">
C:.
| linker.ld
| makefile
|
\---src
boot.S
main.c
</syntaxhighlight>
Nun können wir unser erstes Programm kompilieren:

<syntaxhighlight lang="shell">
make
</syntaxhighlight>

Damit unser Kernel funktionsfähig ist, muss der Kernel auf eine SD-Karte, die in FAT32 formatiert ist, kopiert werden. Zusätzlich benötigt der Raspberry Pi 4 folgende Dateien auf der SD-Karte:

* bootcode.bin
* start.elf
* config.txt
* kernel8.img (Ihr kompiliertes Programm)

Den Source-Code können Sie als ZIP-Datei [https://www.satyria.de/arm/sources/RPI4/C/1.zip hier] herunterladen.

-----

{| style="width: 100%;
| style="width: 33%;" |
| style="width: 33%; text-align:center;" | [[Hauptseite|< Hauptseite >]]
| style="width: 33%; text-align:right;" | [[Lass die LED leuchten in C (PI4)|Weiter (Lass die LED leuchten in C (PI4)) >]]
|}

Unser erstes Programm in C (PI4)

2026-06-05T10:21:01Z

Satyria: /* Linker-Script (linker.ld) */

== Einführung ==
In diesem Kurs werden wir die Grundlagen der Programmierung des Raspberry Pi 4 erlernen. Ähnlich wie bei der Programmierung des Raspberry Pi 5, gibt es einige Unterschiede, hauptsächlich bedingt durch die Unterstützung von USB und die umfangreichere Dokumentation für den Raspberry Pi 4. Für diesen Kurs habe ich Material vom Raspberry Pi 5 angepasst, um die Programmierung des Raspberry Pi 4 zu erläutern.

Ein Terminal wurde programmiert, das sich sehr gut zum Debuggen eignet. Dies werden wir in unserem Kurs ebenfalls verwenden.

-----
== Ziel unseres ersten Programms ==
Unser erstes Programm wird eine einfache Endlosschleife enthalten. Dies dient als Basis für weitere Experimente und Versuche. Ich werde erklären, wie ein solches Programm erstellt, kompiliert und ausgeführt wird.

== Erstellung des Sourcecodes ==
Leider kommen wir bei Bare-Metal-Programmierung in C nicht um Assembler herum. Auch wenn das Assemblerprogramm zunächst nicht viel tut, wird es später beispielsweise für die Interrupt-Programmierung benötigt. Erstelle zunächst das Verzeichnis "src", in der wir unseren Sourcecode ablegen werden.

=== Assembler-Code (boot.S) ===

Öffnen Sie ein Textprogramm und schreiben Sie folgendes erstes Assemblerprogramm:

<syntaxhighlight lang="asm">
//
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

mov sp, #0x80000 // Create a stack of 512KB (524288 bytes)
b main // Branch to "main"
</syntaxhighlight>

Speichern Sie die Datei im Standardverzeichnis unter Windows: C:\msys64\home\xxx (wobei xxx in der Regel Ihr Benutzername ist). Unter Linux können Sie die Datei im Home-Verzeichnis speichern. Geben Sie der Datei den Namen boot.S. Die Endung .S kennzeichnet die Datei als Assembler-Sourcecode.

=== C-Code (main.c) ===

Nun erstellen wir eine main.c Datei für unser erstes Programm:

<syntaxhighlight lang="C">
//
// main.c
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

int main (void)
{
while (1){}
}
</syntaxhighlight>

Hier wird eine einfache Endlosschleife erzeugt.

== Kompilieren des Programms mit Make ==
Um unser Programm zu kompilieren, muss zunächst die Programmierumgebung eingerichtet werden. Verwenden Sie hierzu die entsprechenden Anleitungen. Diese funktionieren auch für den Raspberry Pi 4:

[[Programmierumgebung erstellen (Konsole)]]

[[Programmierumgebung erstellen (64-Bit)]]

Erstellen Sie dann ein Makefile, welches im Root-Verzeichnis des Projektes abgelegt wird:

<syntaxhighlight lang="makefile">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

Speichern Sie diese Datei unter dem Namen Makefile.

Wenn Sie mehr über den Inhalt erfahren möchten, schauen Sie unter "[[Arbeiten mit Make und Linker-Script]]" nach.

== Linker-Script (linker.ld) ==
Erstellen Sie das folgende Linker-Script, welches wir unter [[Arbeiten mit Make und Linker-Script]] beschrieben haben. Dieses wird, wie das Makefile in das Root-Verzeichnis abgelegt:

<syntaxhighlight lang="shell">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text*)
_etext = .;
}
.rodata : {
*(.rodata*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data*)
}
.bss : {
__bss_start = .;
*(.bss*)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
Speichern Sie diese Datei unter dem Namen linker.ld.

== Kompilieren und Ausführen ==
Nun können wir unser erstes Programm kompilieren:

<syntaxhighlight lang="shell">
make
</syntaxhighlight>

Damit unser Kernel funktionsfähig ist, muss der Kernel auf eine SD-Karte, die in FAT32 formatiert ist, kopiert werden. Zusätzlich benötigt der Raspberry Pi 4 folgende Dateien auf der SD-Karte:

* bootcode.bin
* start.elf
* config.txt
* kernel8.img (Ihr kompiliertes Programm)

Den Source-Code können Sie als ZIP-Datei [https://www.satyria.de/arm/sources/RPI4/C/1.zip hier] herunterladen.

-----

{| style="width: 100%;
| style="width: 33%;" |
| style="width: 33%; text-align:center;" | [[Hauptseite|< Hauptseite >]]
| style="width: 33%; text-align:right;" | [[Lass die LED leuchten in C (PI4)|Weiter (Lass die LED leuchten in C (PI4)) >]]
|}

Unser erstes Programm in C (PI4)

2026-06-05T10:19:55Z

Satyria: /* Kompilieren des Programms mit Make */

== Einführung ==
In diesem Kurs werden wir die Grundlagen der Programmierung des Raspberry Pi 4 erlernen. Ähnlich wie bei der Programmierung des Raspberry Pi 5, gibt es einige Unterschiede, hauptsächlich bedingt durch die Unterstützung von USB und die umfangreichere Dokumentation für den Raspberry Pi 4. Für diesen Kurs habe ich Material vom Raspberry Pi 5 angepasst, um die Programmierung des Raspberry Pi 4 zu erläutern.

Ein Terminal wurde programmiert, das sich sehr gut zum Debuggen eignet. Dies werden wir in unserem Kurs ebenfalls verwenden.

-----
== Ziel unseres ersten Programms ==
Unser erstes Programm wird eine einfache Endlosschleife enthalten. Dies dient als Basis für weitere Experimente und Versuche. Ich werde erklären, wie ein solches Programm erstellt, kompiliert und ausgeführt wird.

== Erstellung des Sourcecodes ==
Leider kommen wir bei Bare-Metal-Programmierung in C nicht um Assembler herum. Auch wenn das Assemblerprogramm zunächst nicht viel tut, wird es später beispielsweise für die Interrupt-Programmierung benötigt. Erstelle zunächst das Verzeichnis "src", in der wir unseren Sourcecode ablegen werden.

=== Assembler-Code (boot.S) ===

Öffnen Sie ein Textprogramm und schreiben Sie folgendes erstes Assemblerprogramm:

<syntaxhighlight lang="asm">
//
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

mov sp, #0x80000 // Create a stack of 512KB (524288 bytes)
b main // Branch to "main"
</syntaxhighlight>

Speichern Sie die Datei im Standardverzeichnis unter Windows: C:\msys64\home\xxx (wobei xxx in der Regel Ihr Benutzername ist). Unter Linux können Sie die Datei im Home-Verzeichnis speichern. Geben Sie der Datei den Namen boot.S. Die Endung .S kennzeichnet die Datei als Assembler-Sourcecode.

=== C-Code (main.c) ===

Nun erstellen wir eine main.c Datei für unser erstes Programm:

<syntaxhighlight lang="C">
//
// main.c
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

int main (void)
{
while (1){}
}
</syntaxhighlight>

Hier wird eine einfache Endlosschleife erzeugt.

== Kompilieren des Programms mit Make ==
Um unser Programm zu kompilieren, muss zunächst die Programmierumgebung eingerichtet werden. Verwenden Sie hierzu die entsprechenden Anleitungen. Diese funktionieren auch für den Raspberry Pi 4:

[[Programmierumgebung erstellen (Konsole)]]

[[Programmierumgebung erstellen (64-Bit)]]

Erstellen Sie dann ein Makefile, welches im Root-Verzeichnis des Projektes abgelegt wird:

<syntaxhighlight lang="makefile">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

Speichern Sie diese Datei unter dem Namen Makefile.

Wenn Sie mehr über den Inhalt erfahren möchten, schauen Sie unter "[[Arbeiten mit Make und Linker-Script]]" nach.

== Linker-Script (linker.ld) ==
Erstellen Sie das folgende Linker-Script, welches wir unter [[Arbeiten mit Make und Linker-Script]] beschrieben haben:

<syntaxhighlight lang="shell">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text*)
_etext = .;
}
.rodata : {
*(.rodata*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data*)
}
.bss : {
__bss_start = .;
*(.bss*)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
Speichern Sie diese Datei unter dem Namen linker.ld.

== Kompilieren und Ausführen ==
Nun können wir unser erstes Programm kompilieren:

<syntaxhighlight lang="shell">
make
</syntaxhighlight>

Damit unser Kernel funktionsfähig ist, muss der Kernel auf eine SD-Karte, die in FAT32 formatiert ist, kopiert werden. Zusätzlich benötigt der Raspberry Pi 4 folgende Dateien auf der SD-Karte:

* bootcode.bin
* start.elf
* config.txt
* kernel8.img (Ihr kompiliertes Programm)

Den Source-Code können Sie als ZIP-Datei [https://www.satyria.de/arm/sources/RPI4/C/1.zip hier] herunterladen.

-----

{| style="width: 100%;
| style="width: 33%;" |
| style="width: 33%; text-align:center;" | [[Hauptseite|< Hauptseite >]]
| style="width: 33%; text-align:right;" | [[Lass die LED leuchten in C (PI4)|Weiter (Lass die LED leuchten in C (PI4)) >]]
|}

Unser erstes Programm in C (PI4)

2026-06-05T10:18:34Z

Satyria: /* Erstellung des Sourcecodes */

== Einführung ==
In diesem Kurs werden wir die Grundlagen der Programmierung des Raspberry Pi 4 erlernen. Ähnlich wie bei der Programmierung des Raspberry Pi 5, gibt es einige Unterschiede, hauptsächlich bedingt durch die Unterstützung von USB und die umfangreichere Dokumentation für den Raspberry Pi 4. Für diesen Kurs habe ich Material vom Raspberry Pi 5 angepasst, um die Programmierung des Raspberry Pi 4 zu erläutern.

Ein Terminal wurde programmiert, das sich sehr gut zum Debuggen eignet. Dies werden wir in unserem Kurs ebenfalls verwenden.

-----
== Ziel unseres ersten Programms ==
Unser erstes Programm wird eine einfache Endlosschleife enthalten. Dies dient als Basis für weitere Experimente und Versuche. Ich werde erklären, wie ein solches Programm erstellt, kompiliert und ausgeführt wird.

== Erstellung des Sourcecodes ==
Leider kommen wir bei Bare-Metal-Programmierung in C nicht um Assembler herum. Auch wenn das Assemblerprogramm zunächst nicht viel tut, wird es später beispielsweise für die Interrupt-Programmierung benötigt. Erstelle zunächst das Verzeichnis "src", in der wir unseren Sourcecode ablegen werden.

=== Assembler-Code (boot.S) ===

Öffnen Sie ein Textprogramm und schreiben Sie folgendes erstes Assemblerprogramm:

<syntaxhighlight lang="asm">
//
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

mov sp, #0x80000 // Create a stack of 512KB (524288 bytes)
b main // Branch to "main"
</syntaxhighlight>

Speichern Sie die Datei im Standardverzeichnis unter Windows: C:\msys64\home\xxx (wobei xxx in der Regel Ihr Benutzername ist). Unter Linux können Sie die Datei im Home-Verzeichnis speichern. Geben Sie der Datei den Namen boot.S. Die Endung .S kennzeichnet die Datei als Assembler-Sourcecode.

=== C-Code (main.c) ===

Nun erstellen wir eine main.c Datei für unser erstes Programm:

<syntaxhighlight lang="C">
//
// main.c
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

int main (void)
{
while (1){}
}
</syntaxhighlight>

Hier wird eine einfache Endlosschleife erzeugt.

== Kompilieren des Programms mit Make ==
Um unser Programm zu kompilieren, muss zunächst die Programmierumgebung eingerichtet werden. Verwenden Sie hierzu die entsprechenden Anleitungen. Diese funktionieren auch für den Raspberry Pi 4:

[[Programmierumgebung erstellen (Konsole)]]

[[Programmierumgebung erstellen (64-Bit)]]

Erstellen Sie dann ein Makefile, angepasst für den Raspberry Pi 4:

<syntaxhighlight lang="makefile">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

Speichern Sie diese Datei unter dem Namen Makefile.

Wenn Sie mehr über den Inhalt erfahren möchten, schauen Sie unter "[[Arbeiten mit Make und Linker-Script]]" nach.

== Linker-Script (linker.ld) ==
Erstellen Sie das folgende Linker-Script, welches wir unter [[Arbeiten mit Make und Linker-Script]] beschrieben haben:

<syntaxhighlight lang="shell">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text*)
_etext = .;
}
.rodata : {
*(.rodata*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data*)
}
.bss : {
__bss_start = .;
*(.bss*)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
Speichern Sie diese Datei unter dem Namen linker.ld.

== Kompilieren und Ausführen ==
Nun können wir unser erstes Programm kompilieren:

<syntaxhighlight lang="shell">
make
</syntaxhighlight>

Damit unser Kernel funktionsfähig ist, muss der Kernel auf eine SD-Karte, die in FAT32 formatiert ist, kopiert werden. Zusätzlich benötigt der Raspberry Pi 4 folgende Dateien auf der SD-Karte:

* bootcode.bin
* start.elf
* config.txt
* kernel8.img (Ihr kompiliertes Programm)

Den Source-Code können Sie als ZIP-Datei [https://www.satyria.de/arm/sources/RPI4/C/1.zip hier] herunterladen.

-----

{| style="width: 100%;
| style="width: 33%;" |
| style="width: 33%; text-align:center;" | [[Hauptseite|< Hauptseite >]]
| style="width: 33%; text-align:right;" | [[Lass die LED leuchten in C (PI4)|Weiter (Lass die LED leuchten in C (PI4)) >]]
|}

Unser erstes Programm in C (PI4)

2026-06-05T10:17:03Z

Satyria: /* Kompilieren des Programms mit Make */

== Einführung ==
In diesem Kurs werden wir die Grundlagen der Programmierung des Raspberry Pi 4 erlernen. Ähnlich wie bei der Programmierung des Raspberry Pi 5, gibt es einige Unterschiede, hauptsächlich bedingt durch die Unterstützung von USB und die umfangreichere Dokumentation für den Raspberry Pi 4. Für diesen Kurs habe ich Material vom Raspberry Pi 5 angepasst, um die Programmierung des Raspberry Pi 4 zu erläutern.

Ein Terminal wurde programmiert, das sich sehr gut zum Debuggen eignet. Dies werden wir in unserem Kurs ebenfalls verwenden.

-----
== Ziel unseres ersten Programms ==
Unser erstes Programm wird eine einfache Endlosschleife enthalten. Dies dient als Basis für weitere Experimente und Versuche. Ich werde erklären, wie ein solches Programm erstellt, kompiliert und ausgeführt wird.

== Erstellung des Sourcecodes ==
Leider kommen wir bei Bare-Metal-Programmierung in C nicht um Assembler herum. Auch wenn das Assemblerprogramm zunächst nicht viel tut, wird es später beispielsweise für die Interrupt-Programmierung benötigt.

=== Assembler-Code (boot.S) ===

Öffnen Sie ein Textprogramm und schreiben Sie folgendes erstes Assemblerprogramm:

<syntaxhighlight lang="GAS">
//
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

.section .init // Ensure the linker places this at the beginning of the kernel image
.globl _start // Generates a global label
_start: // The label _start (entry address)

mov sp, #0x80000 // Create a stack of 512KB (524288 bytes)
b main // Branch to "main"
</syntaxhighlight>

Speichern Sie die Datei im Standardverzeichnis unter Windows: C:\msys64\home\xxx (wobei xxx in der Regel Ihr Benutzername ist). Unter Linux können Sie die Datei im Home-Verzeichnis speichern. Geben Sie der Datei den Namen boot.S. Die Endung .S kennzeichnet die Datei als Assembler-Sourcecode.

=== C-Code (main.c) ===

Nun erstellen wir eine main.c Datei für unser erstes Programm:

<syntaxhighlight lang="C">
//
// main.c
// The first program for RPI4
// 20.02.2025 www.satyria.de
//

int main (void)
{
while (1){}
}
</syntaxhighlight>

Hier wird eine einfache Endlosschleife erzeugt.

== Kompilieren des Programms mit Make ==
Um unser Programm zu kompilieren, muss zunächst die Programmierumgebung eingerichtet werden. Verwenden Sie hierzu die entsprechenden Anleitungen. Diese funktionieren auch für den Raspberry Pi 4:

[[Programmierumgebung erstellen (Konsole)]]

[[Programmierumgebung erstellen (64-Bit)]]

Erstellen Sie dann ein Makefile, angepasst für den Raspberry Pi 4:

<syntaxhighlight lang="makefile">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -I ./include -O0 -g

CFLAGS = -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -DAARCH=64 -mcpu=cortex-a72 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel8.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel8.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel8.elf -Map kernel8.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel8.elf kernel8.img

clean:
ifeq ($(MSYSTEM),)
# --- Native Windows Umgebung (CMD / PowerShell) ---
# @cls
@if exist kernel8.elf del /q /f kernel8.elf
@if exist kernel8.img del /q /f kernel8.img
@if exist kernel8.map del /q /f kernel8.map
@if exist src\*.o del /q /f src\*.o
else
# --- MSYS2 / Unix-ähnliche Umgebung ---
/bin/rm -f kernel8.elf kernel8.map src/*.o *.img > /dev/null 2> /dev/null || true
endif

new:
ifeq ($(MSYSTEM),)
@cls
else
/bin/clear
endif
</syntaxhighlight>

Speichern Sie diese Datei unter dem Namen Makefile.

Wenn Sie mehr über den Inhalt erfahren möchten, schauen Sie unter "[[Arbeiten mit Make und Linker-Script]]" nach.

== Linker-Script (linker.ld) ==
Erstellen Sie das folgende Linker-Script, welches wir unter [[Arbeiten mit Make und Linker-Script]] beschrieben haben:

<syntaxhighlight lang="shell">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text*)
_etext = .;
}
.rodata : {
*(.rodata*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data*)
}
.bss : {
__bss_start = .;
*(.bss*)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>
Speichern Sie diese Datei unter dem Namen linker.ld.

== Kompilieren und Ausführen ==
Nun können wir unser erstes Programm kompilieren:

<syntaxhighlight lang="shell">
make
</syntaxhighlight>

Damit unser Kernel funktionsfähig ist, muss der Kernel auf eine SD-Karte, die in FAT32 formatiert ist, kopiert werden. Zusätzlich benötigt der Raspberry Pi 4 folgende Dateien auf der SD-Karte:

* bootcode.bin
* start.elf
* config.txt
* kernel8.img (Ihr kompiliertes Programm)

Den Source-Code können Sie als ZIP-Datei [https://www.satyria.de/arm/sources/RPI4/C/1.zip hier] herunterladen.

-----

{| style="width: 100%;
| style="width: 33%;" |
| style="width: 33%; text-align:center;" | [[Hauptseite|< Hauptseite >]]
| style="width: 33%; text-align:right;" | [[Lass die LED leuchten in C (PI4)|Weiter (Lass die LED leuchten in C (PI4)) >]]
|}

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:33:55Z

Satyria: /* Preparing the Hardware and Setting Up the SD Card */

Many developers desire a professional way to perform bare-metal development directly within a graphical user interface (GUI). In this guide, I will show you how to set up such a development environment. As our IDE (Integrated Development Environment), we will use Visual Studio Code from Microsoft, which is released under the open-source MIT license.

To communicate directly with the Raspberry Pi 5 and debug programs, you will additionally need a '''Raspberry Pi Debug Probe'''. This is connected to a Windows PC via USB and to the Raspberry Pi 5 via the debug pins.

== Software Requirements ==
As mentioned earlier, we will use Visual Studio Code as our GUI. The software can be downloaded for free from the official website:

👉 https://code.visualstudio.com/

Additionally, we need the official toolchain from ARM to be able to compile code for the AArch64 architecture of the Raspberry Pi 5. It is available for download here:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Note: At the time of writing this tutorial, version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' was used. Since the toolchain is under continuous development, the version number of your download may vary slightly.

For the connection between the PC and the Debug Probe, we use OpenOCD (Open On-Chip Debugger). A pre-compiled Windows version is provided by the xPack project:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direct download link for the version used: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Finally, we also need the build tool '''GNU Make''', which we will install directly via the Windows console in the next step.
== Installation and Setup ==
=== Setting Up the Toolchain ===
Since Windows can occasionally have issues with very long path names, we first rename the downloaded toolchain archive to '''toolchain.zip'''.

Extract the ZIP archive completely.

Create a new directory directly on your system drive: '''C:\tools'''.

Copy the entire contents of the extracted toolchain folder into this directory, so that the folder structure starts directly with '''C:\tools\bin'''.

=== Setting Up and Configuring OpenOCD ===
Extract the OpenOCD ZIP archive.

In the extracted folder, you will find the subdirectory '''xpack-openocd-0.12.0-7''' (or your more recent version). Simply rename this folder to '''openocd'''.

Move the entire '''openocd''' folder to '''C:\tools''', so that the path becomes '''C:\tools\openocd'''.

Next, check if the file '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' exists. This is usually included by default. If it is missing, create this file with the following content:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>

Since older or standard OpenOCD releases lack a suitable target profile for the new Broadcom BCM2712 chip of the Raspberry Pi 5, we need to create it manually. To do this, create a new file at the path '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' and insert the following content:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# These addresses were read from the ROM table via the 'dap info 0' command
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== Installing GNU Make ===
On Windows, a package for '''GNU Make''' is available, which can be conveniently installed via the integrated package manager. Open a terminal (Command Prompt or PowerShell) and enter the following command:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
The program is installed by default in the directory '''C:\Program Files (x86)\GnuWin32\bin'''. To ensure that '''Make''' works smoothly with our other tools, copy the entire contents of this bin folder into our previously created directory '''C:\tools\bin'''.

=== Adjusting the "Path" Environment Variable ===
In order for Windows and Visual Studio Code to find the installed tools (compiler, Make, and OpenOCD) system-wide via the console, we need to add the executables to the system path.

Press the '''Windows key''' and type "''environment variables''" in the search field.

Select the option "''Edit the system environment variables''" and click the "''Environment Variables...''" button at the bottom of the next window.

[[Datei:Path1.png|300x300px]]

In the "''User variables''" or "''System variables''" section, look for the entry '''Path''' (or PATH) and select Edit.

[[Datei:Path2.png|300x300px]]

Add the following two paths to the list as separate, new lines:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Confirm all open windows with '''OK'''.

[[Datei:Path3.png|300x300px]]

The basic toolchain is now successfully installed and set up. In the next part, we will focus on configuring Visual Studio Code for the actual bare-metal project.

=== Setting Up Visual Studio Code ===
Now that the basic toolchain is installed, we will set up the development environment in Visual Studio Code.

First, complete the installation of Visual Studio Code using the installer you downloaded earlier.

==== Installing VS Code Extensions ====
Open Visual Studio Code. To make bare-metal development as comfortable as possible, we will first install some essential extensions. Click on the Extensions icon in the left menu bar (or press CTRL + SHIFT + X) and search for the following extensions:

* C/C++ (by Microsoft): Provides syntax highlighting and code completion (IntelliSense) for C/C++.
* C/C++ Extension Pack (optional): Comes with additional useful tools for C development.
* Cortex-Debug (by marus25): The key extension that allows us to debug directly on the Raspberry Pi 5 via OpenOCD.
* Arm Assembly (by dan-c-underwood): Provides excellent support and highlighting for ARM assembly code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Changing the User Interface Language to German ====
If your VS Code is in English and you prefer the German interface, for example:

Press '''CTRL + SHIFT + P''' to open the Command Palette. Type ''Configure Display Language'' and press '''Enter'''.

Select "Deutsch" (German). (If it is not listed, you can install it directly from there).

Restart VS Code.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Creating and Opening the Project Directory ====
Now create a directory on your hard drive where your bare-metal project will reside. In this example, we will use the path '''D:\projekt1'''. In VS Code, select ''File -> Open Folder...'' and choose the directory '''D:\projekt1'''. Confirm the security prompt asking if you trust the authors of the folder by clicking "''Yes, I trust the authors''".

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Creating the .vscode Configuration Files ====

To let VS Code know which compiler to use and how to start the debugger, we need to create a configuration directory. In the main directory of your project, create a new folder with the exact name '''.vscode''' (don't forget the dot at the beginning!). Right-click on the newly created '''.vscode''' folder and create the following three files one after the other.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Copy the corresponding JSON code into each of them:

* '''c_cpp_properties.json''': This file configures code completion (IntelliSense) so that VS Code understands the ARM-specific commands and headers.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': This file controls the debugger (Cortex-Debug). It ensures that your code is loaded onto the Raspberry Pi 5 via OpenOCD and that the processor is stopped exactly at the start address.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Overrides the default "reset halt" command from VS Code
"overrideResetCommands": [
"monitor halt"
],

// Commands that are executed directly after connecting
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Forces the processor directly to the start address
],

"preLaunchTask": "Compile"
}
]
}
</syntaxhighlight>
* '''tasks.json''': This defines the automated build process. Before the debugger starts, this task automatically calls make.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Compile",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Save all configurations by clicking ''File -> Save All'' in the menu.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Note on Apparent Error Messages ====
After saving the '''c_cpp_properties.json''', you will probably notice a small red "'''2'''" in the file explorer or in the "Problems" tab (at the bottom of VS Code). This indicates active warnings. If you click on the message, you will see the reason: VS Code is complaining that the two directory paths '''${workspaceFolder}/include''' and '''${workspaceFolder}/src''' do not exist.

[[Datei:Prob1.png|200x200px]]

💡Don't worry: This is completely correct! Since we started with an empty project, these folders simply don't exist yet. As soon as you create the '''src''' and '''include''' folders later in your project, this warning will disappear automatically.

Tip: If VS Code does not immediately register newly created folders, you can quickly refresh the development environment. To do this, press '''F1''', type ''Reload Window'', and confirm with '''Enter'''. This reloads the interface without interrupting your work.

== Source Code, Linker Script, and Makefile ==
=== The Source Code Directory (src/) ===
To practically test our setup, we will use a minimalist LED blinking example in C and Assembly ([[Lass die LED leuchten in C (PI5)]]). This project uses a split into multiple files so that you can directly experience cross-references in the code and the convenience of a professional GUI.

In the main directory of your project (e.g., '''D:\projekt1'''), create a new folder named '''src'''.

💡 Important note for assembly files: Make sure that assembly files that use the C preprocessor (such as including header files via '''#include''') strictly have the file extension with a capital "'''S'''" ('''.S'''). A lowercase "s" will cause the compiler to ignore the includes.

Create the following six files in the '''src/''' folder:

'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Ensures that the linker places this at the beginning of the kernel image
.globl _start // Execution starts here

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Initialize stack pointer
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Set bit 9 to 0
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Set bit 9 to 1
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 cycles)
{
volatile u32 i;
for (i = 0; i < cycles; i++)
{
// Empty loop for delay
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Note''': As soon as you save these files, VS Code will display various errors in the "Problems" tab. The code will be underlined with red, wavy lines. This is completely normal because the compiler currently lacks the header files (.h) and cannot resolve the references.

[[Datei:Source prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 cycles);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

As soon as all header files are saved in the include folder, the red lines in VS Code will disappear automatically. The GUI has successfully recognized the references.

[[Datei:Null prob.png|200x200px]]

=== Creating the Linker Script and Makefile ===

In order to build an executable bare-metal image for the Raspberry Pi 5 from the source code, we need a ''linker script'' and the control file for '''GNU Make'''. Both files are created directly in the main directory (root) of your project.

==== linker.ld ====
This script defines the exact layout of the code segments in the Raspberry Pi 5's memory.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>

==== Makefile ====
The '''Makefile''' automates the invocation of the compiler and linker. Note that it explicitly targets the architecture of the Raspberry Pi 5 ('''-mcpu=cortex-a76''').
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Important note''' regarding Makefiles: Do not use spaces for indentation. '''make''' will not accept this. Always use a '''TAB''' character instead.

Finally, do not forget to save all open files via ''File -> Save All'' in the VS Code menu. The project is now fully configured and ready for its first build and debugging run!

== Preparing the Hardware and Debugging in the GUI ==
=== Preparing the Hardware and Setting Up the SD Card ===
Since we are testing the code directly on the real hardware, we need to prepare the Raspberry Pi 5's SD card. The operating system (EEPROM/firmware) of the Pi 5 needs to know that we want to debug a bare-metal program via JTAG/SWD.

Format a MicroSD card as FAT32 and copy the following three files into the root directory of the card:

'''kernel_2712.img''' (This file will be generated during the first compilation).

'''bcm2712-rpi-5-b.dtb''' (The original device tree blob from the official Raspberry Pi firmware)

'''config.txt''' (The configuration file for the firmware).

Create the '''config.txt''' with the exact following content:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 What does this configuration do?

'''kernel_address=0x80000''' sets the start address in RAM where our kernel will be loaded.

'''enable_jtag_gpio=1''' switches the Raspberry Pi 5's GPIO pins into JTAG/SWD mode. This is what makes communication with the Raspberry Pi Debug Probe possible in the first place.

Connecting the hardware:
* Insert the prepared SD card into the Raspberry Pi 5.
* Connect the Raspberry Pi Debug Probe to the dedicated debug port of the Raspberry Pi 5 (located between the Micro-HDMI ports) using the supplied 3-pin UART/debug cable.
* Connect the Debug Probe to your Windows PC via a USB cable.
* Power on the Raspberry Pi 5 (connect the power supply).

With the JTAG interface enabled, the processor now waits at the start address for the debugger to connect and issue commands.

=== Compiling the Program and Starting the Debugger ===
Thanks to our preparations in Visual Studio Code, we can control the entire build and flash process using keyboard shortcuts.

'''Step 1:'''

''Compile'': Press the keyboard shortcut '''CTRL + SHIFT + B'''. VS Code will now run the Makefile ('''make all''') in the background. This will generate the files '''kernel_2712.elf''' (for the debugger, including symbols) and '''kernel_2712.img''' (the raw binary format) in the project directory.

'''Step 2:'''

''Start Debugger'': Press the '''F5''' key.

The following now happens fully automatically:

* OpenOCD establishes the connection to the Raspberry Pi 5 via the Debug Probe.
* The GDB debugger is started.
* The newly compiled program is loaded directly into the Raspberry Pi 5's RAM (load).
* The processor's program counter is forced to the start address 0x80000.

Since we specified in the '''launch.json''' that the debugger should halt on startup, execution stops exactly at the first instruction. In our source code, the cursor jumps directly to the '''boot.S''' file at the '''_start:''' label.

[[Datei:Debug1.png|300x300px]]

=== Operating the Debugger in VS Code ===
As soon as the debugger is active, the VS Code user interface changes. A floating debug control bar appears at the top of the screen.

[[Datei:ObDebug.png|300x300px]]

The GUI controls:

{| class="wikitable"
|+ Controls
|-
! Icon / Symbol !! Action !! Keyboard Shortcut !! Description
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Immediately halts the running program at the current location.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Continue || F5 || Resumes normal program execution (until the next breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Step Over || F10 || Executes the current line. Does not step into functions.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Step Into || F11 || Steps directly into a function to examine it line by line.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Step Out || SHIFT + F11 || Executes the rest of the current function and stops immediately after returning.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Restart || CTRL + SHIFT + F5 || Reloads the program onto the Pi and starts the debugging process from the beginning.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stop || SHIFT + F5 || Ends the debug session and closes the connection to the Pi 5.
|}

==== Using the Debugger Views ====
The biggest advantage of a professional GUI over the GDB command line is the visual presentation of all processor information on the left side of the screen:

* Variables Window: Local and global variables are automatically displayed here. You can immediately see their current values. You can even manipulate these values with a double-click while halted to simulate test cases!

* Watch Window: If you want to keep a permanent eye on specific variables or register addresses, you can add them here.

* Call Stack: Shows you exactly which functions the program has gone through to reach the current point.

* Registers Window (Cortex-Debug): A highlight for bare-metal developers. Here you can see the CPU registers of the ARM Cortex-A76 core (X0 to X30, SP, PC, etc.) with real-time access. If a register value changes after a single step, it is highlighted in color.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Setting Breakpoints with a Mouse Click ====
Typing memory addresses into GDB is a thing of the past. In VS Code, simply move your mouse to the left of the line numbers in the source code (e.g., in kernel.c on the line ''LED_on();''). A faint red dot will appear. With a simple left-click, you activate the breakpoint (it turns solid red). If you now press '''F5''' (Continue), the program runs until it reaches exactly this line and freezes the CPU. Another click on the dot removes the breakpoint again.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Summary ==
You have now set up a fully-fledged, professional development environment with hardware debugging for the Raspberry Pi 5!

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:32:44Z

Satyria:

Many developers desire a professional way to perform bare-metal development directly within a graphical user interface (GUI). In this guide, I will show you how to set up such a development environment. As our IDE (Integrated Development Environment), we will use Visual Studio Code from Microsoft, which is released under the open-source MIT license.

To communicate directly with the Raspberry Pi 5 and debug programs, you will additionally need a '''Raspberry Pi Debug Probe'''. This is connected to a Windows PC via USB and to the Raspberry Pi 5 via the debug pins.

== Software Requirements ==
As mentioned earlier, we will use Visual Studio Code as our GUI. The software can be downloaded for free from the official website:

👉 https://code.visualstudio.com/

Additionally, we need the official toolchain from ARM to be able to compile code for the AArch64 architecture of the Raspberry Pi 5. It is available for download here:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Note: At the time of writing this tutorial, version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' was used. Since the toolchain is under continuous development, the version number of your download may vary slightly.

For the connection between the PC and the Debug Probe, we use OpenOCD (Open On-Chip Debugger). A pre-compiled Windows version is provided by the xPack project:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direct download link for the version used: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Finally, we also need the build tool '''GNU Make''', which we will install directly via the Windows console in the next step.
== Installation and Setup ==
=== Setting Up the Toolchain ===
Since Windows can occasionally have issues with very long path names, we first rename the downloaded toolchain archive to '''toolchain.zip'''.

Extract the ZIP archive completely.

Create a new directory directly on your system drive: '''C:\tools'''.

Copy the entire contents of the extracted toolchain folder into this directory, so that the folder structure starts directly with '''C:\tools\bin'''.

=== Setting Up and Configuring OpenOCD ===
Extract the OpenOCD ZIP archive.

In the extracted folder, you will find the subdirectory '''xpack-openocd-0.12.0-7''' (or your more recent version). Simply rename this folder to '''openocd'''.

Move the entire '''openocd''' folder to '''C:\tools''', so that the path becomes '''C:\tools\openocd'''.

Next, check if the file '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' exists. This is usually included by default. If it is missing, create this file with the following content:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>

Since older or standard OpenOCD releases lack a suitable target profile for the new Broadcom BCM2712 chip of the Raspberry Pi 5, we need to create it manually. To do this, create a new file at the path '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' and insert the following content:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# These addresses were read from the ROM table via the 'dap info 0' command
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== Installing GNU Make ===
On Windows, a package for '''GNU Make''' is available, which can be conveniently installed via the integrated package manager. Open a terminal (Command Prompt or PowerShell) and enter the following command:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
The program is installed by default in the directory '''C:\Program Files (x86)\GnuWin32\bin'''. To ensure that '''Make''' works smoothly with our other tools, copy the entire contents of this bin folder into our previously created directory '''C:\tools\bin'''.

=== Adjusting the "Path" Environment Variable ===
In order for Windows and Visual Studio Code to find the installed tools (compiler, Make, and OpenOCD) system-wide via the console, we need to add the executables to the system path.

Press the '''Windows key''' and type "''environment variables''" in the search field.

Select the option "''Edit the system environment variables''" and click the "''Environment Variables...''" button at the bottom of the next window.

[[Datei:Path1.png|300x300px]]

In the "''User variables''" or "''System variables''" section, look for the entry '''Path''' (or PATH) and select Edit.

[[Datei:Path2.png|300x300px]]

Add the following two paths to the list as separate, new lines:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Confirm all open windows with '''OK'''.

[[Datei:Path3.png|300x300px]]

The basic toolchain is now successfully installed and set up. In the next part, we will focus on configuring Visual Studio Code for the actual bare-metal project.

=== Setting Up Visual Studio Code ===
Now that the basic toolchain is installed, we will set up the development environment in Visual Studio Code.

First, complete the installation of Visual Studio Code using the installer you downloaded earlier.

==== Installing VS Code Extensions ====
Open Visual Studio Code. To make bare-metal development as comfortable as possible, we will first install some essential extensions. Click on the Extensions icon in the left menu bar (or press CTRL + SHIFT + X) and search for the following extensions:

* C/C++ (by Microsoft): Provides syntax highlighting and code completion (IntelliSense) for C/C++.
* C/C++ Extension Pack (optional): Comes with additional useful tools for C development.
* Cortex-Debug (by marus25): The key extension that allows us to debug directly on the Raspberry Pi 5 via OpenOCD.
* Arm Assembly (by dan-c-underwood): Provides excellent support and highlighting for ARM assembly code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Changing the User Interface Language to German ====
If your VS Code is in English and you prefer the German interface, for example:

Press '''CTRL + SHIFT + P''' to open the Command Palette. Type ''Configure Display Language'' and press '''Enter'''.

Select "Deutsch" (German). (If it is not listed, you can install it directly from there).

Restart VS Code.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Creating and Opening the Project Directory ====
Now create a directory on your hard drive where your bare-metal project will reside. In this example, we will use the path '''D:\projekt1'''. In VS Code, select ''File -> Open Folder...'' and choose the directory '''D:\projekt1'''. Confirm the security prompt asking if you trust the authors of the folder by clicking "''Yes, I trust the authors''".

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Creating the .vscode Configuration Files ====

To let VS Code know which compiler to use and how to start the debugger, we need to create a configuration directory. In the main directory of your project, create a new folder with the exact name '''.vscode''' (don't forget the dot at the beginning!). Right-click on the newly created '''.vscode''' folder and create the following three files one after the other.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Copy the corresponding JSON code into each of them:

* '''c_cpp_properties.json''': This file configures code completion (IntelliSense) so that VS Code understands the ARM-specific commands and headers.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': This file controls the debugger (Cortex-Debug). It ensures that your code is loaded onto the Raspberry Pi 5 via OpenOCD and that the processor is stopped exactly at the start address.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Overrides the default "reset halt" command from VS Code
"overrideResetCommands": [
"monitor halt"
],

// Commands that are executed directly after connecting
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Forces the processor directly to the start address
],

"preLaunchTask": "Compile"
}
]
}
</syntaxhighlight>
* '''tasks.json''': This defines the automated build process. Before the debugger starts, this task automatically calls make.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Compile",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Save all configurations by clicking ''File -> Save All'' in the menu.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Note on Apparent Error Messages ====
After saving the '''c_cpp_properties.json''', you will probably notice a small red "'''2'''" in the file explorer or in the "Problems" tab (at the bottom of VS Code). This indicates active warnings. If you click on the message, you will see the reason: VS Code is complaining that the two directory paths '''${workspaceFolder}/include''' and '''${workspaceFolder}/src''' do not exist.

[[Datei:Prob1.png|200x200px]]

💡Don't worry: This is completely correct! Since we started with an empty project, these folders simply don't exist yet. As soon as you create the '''src''' and '''include''' folders later in your project, this warning will disappear automatically.

Tip: If VS Code does not immediately register newly created folders, you can quickly refresh the development environment. To do this, press '''F1''', type ''Reload Window'', and confirm with '''Enter'''. This reloads the interface without interrupting your work.

== Source Code, Linker Script, and Makefile ==
=== The Source Code Directory (src/) ===
To practically test our setup, we will use a minimalist LED blinking example in C and Assembly ([[Lass die LED leuchten in C (PI5)]]). This project uses a split into multiple files so that you can directly experience cross-references in the code and the convenience of a professional GUI.

In the main directory of your project (e.g., '''D:\projekt1'''), create a new folder named '''src'''.

💡 Important note for assembly files: Make sure that assembly files that use the C preprocessor (such as including header files via '''#include''') strictly have the file extension with a capital "'''S'''" ('''.S'''). A lowercase "s" will cause the compiler to ignore the includes.

Create the following six files in the '''src/''' folder:

'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Ensures that the linker places this at the beginning of the kernel image
.globl _start // Execution starts here

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Initialize stack pointer
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Set bit 9 to 0
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Set bit 9 to 1
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 cycles)
{
volatile u32 i;
for (i = 0; i < cycles; i++)
{
// Empty loop for delay
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Note''': As soon as you save these files, VS Code will display various errors in the "Problems" tab. The code will be underlined with red, wavy lines. This is completely normal because the compiler currently lacks the header files (.h) and cannot resolve the references.

[[Datei:Source prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 cycles);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

As soon as all header files are saved in the include folder, the red lines in VS Code will disappear automatically. The GUI has successfully recognized the references.

[[Datei:Null prob.png|200x200px]]

=== Creating the Linker Script and Makefile ===

In order to build an executable bare-metal image for the Raspberry Pi 5 from the source code, we need a ''linker script'' and the control file for '''GNU Make'''. Both files are created directly in the main directory (root) of your project.

==== linker.ld ====
This script defines the exact layout of the code segments in the Raspberry Pi 5's memory.
<syntaxhighlight lang="C">
ENTRY(_start)

SECTIONS
{
.init : {
*(.init)
}
.text : {
*(.text)
*(.text.*)
_etext = .;
}

.rodata : {
*(.rodata)
*(.rodata.*)
}
.init_array : {
__init_start = .;
KEEP(*(.init_array*))
__init_end = .;
}
.ARM.exidx : {
__exidx_start = .;
*(.ARM.exidx*)
__exidx_end = .;
}
.eh_frame : {
*(.eh_frame*)
}
.data : {
*(.data)
}
.bss : {
__bss_start = .;
*(.bss)
*(COMMON)
__bss_end = .;
}
}
__bss_size = (__bss_end - __bss_start) >> 3;
</syntaxhighlight>

==== Makefile ====
The '''Makefile''' automates the invocation of the compiler and linker. Note that it explicitly targets the architecture of the Raspberry Pi 5 ('''-mcpu=cortex-a76''').
<syntaxhighlight lang="make">
CSRCS := $(wildcard src/*.c)
CPPSRCS := $(wildcard src/*.cpp)
ASRCS := $(wildcard src/*.S)
COBJS := $(CSRCS:.c=.o)
CPPOBJS := $(CPPSRCS:.cpp=.o)
AOBJS := $(ASRCS:.S=.o)
AllOBJS := $(COBJS) $(CPPOBJS) $(AOBJS)
LOADADDR = 0x80000

GCCFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -O0 -ffreestanding \
-nostartfiles -nostdlib -nostdinc -g -I ./include

AFLAGS = -mcpu=cortex-a76 -mlittle-endian -I ./include -O0 -g

CFLAGS = -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char -ffreestanding -g \
-I ./include -O0 -fno-exceptions

CPPFLAGS = -fno-exceptions -fno-rtti -nostdinc++ -mcpu=cortex-a76 -mlittle-endian -Wall -fsigned-char \
-ffreestanding -g -I ./include -O0 -mstrict-align -std=c++14 -Wno-aligned-new

all: clean new kernel_2712.img

%.o: %.S
@echo "as $@"
@aarch64-none-elf-gcc $(AFLAGS) -c $< -o $@

%.o: %.c
@echo "gcc $@"
@aarch64-none-elf-gcc $(CFLAGS) -c $< -o $@

%.o: %.cpp
@echo "g++ $@"
@aarch64-none-elf-g++ $(CPPFLAGS) -c $< -o $@

kernel_2712.img: $(AllOBJS)
@echo "============================================================================="
@echo "Linking..."
@aarch64-none-elf-ld -o kernel_2712.elf -Map kernel_2712.map -nostdlib \
--section-start=.init=$(LOADADDR) --no-warn-rwx-segments \
-g -T linker.ld $(AllOBJS)
aarch64-none-elf-objcopy -O binary kernel_2712.elf kernel_2712.img

clean:
@if exist kernel_2712.elf del /q /f kernel_2712.elf
@if exist kernel_2712.img del /q /f kernel_2712.img
@if exist kernel_2712.map del /q /f kernel_2712.map
@if exist src\*.o del /q /f src\*.o

new:
@cls
</syntaxhighlight>

'''Important note''' regarding Makefiles: Do not use spaces for indentation. '''make''' will not accept this. Always use a '''TAB''' character instead.

Finally, do not forget to save all open files via ''File -> Save All'' in the VS Code menu. The project is now fully configured and ready for its first build and debugging run!

== Preparing the Hardware and Debugging in the GUI ==
=== Preparing the Hardware and Setting Up the SD Card ===
Since we are testing the code directly on the real hardware, we need to prepare the Raspberry Pi 5's SD card. The operating system (EEPROM/firmware) of the Pi 5 needs to know that we want to debug a bare-metal program via JTAG/SWD.

Format a MicroSD card as FAT32 and copy the following three files into the root directory of the card:

'''kernel_2712.img''' (This file will be generated during the first compilation).
'''bcm2712-rpi-5-b.dtb''' (The original device tree blob from the official Raspberry Pi firmware)
'''config.txt''' (The configuration file for the firmware).

Create the '''config.txt''' with the exact following content:
<syntaxhighlight>
arm_64bit=1
kernel_address=0x80000
enable_jtag_gpio=1
kernel=kernel_2712.img
framebuffer_depth=32
</syntaxhighlight>

💡 What does this configuration do?

'''kernel_address=0x80000''' sets the start address in RAM where our kernel will be loaded.

'''enable_jtag_gpio=1''' switches the Raspberry Pi 5's GPIO pins into JTAG/SWD mode. This is what makes communication with the Raspberry Pi Debug Probe possible in the first place.

Connecting the hardware:
* Insert the prepared SD card into the Raspberry Pi 5.
* Connect the Raspberry Pi Debug Probe to the dedicated debug port of the Raspberry Pi 5 (located between the Micro-HDMI ports) using the supplied 3-pin UART/debug cable.
* Connect the Debug Probe to your Windows PC via a USB cable.
* Power on the Raspberry Pi 5 (connect the power supply).

With the JTAG interface enabled, the processor now waits at the start address for the debugger to connect and issue commands.

=== Compiling the Program and Starting the Debugger ===
Thanks to our preparations in Visual Studio Code, we can control the entire build and flash process using keyboard shortcuts.

'''Step 1:'''

''Compile'': Press the keyboard shortcut '''CTRL + SHIFT + B'''. VS Code will now run the Makefile ('''make all''') in the background. This will generate the files '''kernel_2712.elf''' (for the debugger, including symbols) and '''kernel_2712.img''' (the raw binary format) in the project directory.

'''Step 2:'''

''Start Debugger'': Press the '''F5''' key.

The following now happens fully automatically:

* OpenOCD establishes the connection to the Raspberry Pi 5 via the Debug Probe.
* The GDB debugger is started.
* The newly compiled program is loaded directly into the Raspberry Pi 5's RAM (load).
* The processor's program counter is forced to the start address 0x80000.

Since we specified in the '''launch.json''' that the debugger should halt on startup, execution stops exactly at the first instruction. In our source code, the cursor jumps directly to the '''boot.S''' file at the '''_start:''' label.

[[Datei:Debug1.png|300x300px]]

=== Operating the Debugger in VS Code ===
As soon as the debugger is active, the VS Code user interface changes. A floating debug control bar appears at the top of the screen.

[[Datei:ObDebug.png|300x300px]]

The GUI controls:

{| class="wikitable"
|+ Controls
|-
! Icon / Symbol !! Action !! Keyboard Shortcut !! Description
|-
| [[Datei:Debug Pause.png|20px|link=]] || Pause || F6 || Immediately halts the running program at the current location.
|-
| [[Datei:Debug Weiter.png|20px|link=]] || Continue || F5 || Resumes normal program execution (until the next breakpoint).
|-
| [[Datei:Debug EinzelschrittStepOver.png|20px|link=]] || Step Over || F10 || Executes the current line. Does not step into functions.
|-
| [[Datei:Debug EinzelschrittStepInto.png|20px|link=]] || Step Into || F11 || Steps directly into a function to examine it line by line.
|-
| [[Datei:Debug Herausspringen.png|20px|link=]] || Step Out || SHIFT + F11 || Executes the rest of the current function and stops immediately after returning.
|-
| [[Datei:Debug Neustart.png|20px|link=]] || Restart || CTRL + SHIFT + F5 || Reloads the program onto the Pi and starts the debugging process from the beginning.
|-
| [[Datei:Debug Stop.png|20px|link=]] || Stop || SHIFT + F5 || Ends the debug session and closes the connection to the Pi 5.
|}

==== Using the Debugger Views ====
The biggest advantage of a professional GUI over the GDB command line is the visual presentation of all processor information on the left side of the screen:

* Variables Window: Local and global variables are automatically displayed here. You can immediately see their current values. You can even manipulate these values with a double-click while halted to simulate test cases!

* Watch Window: If you want to keep a permanent eye on specific variables or register addresses, you can add them here.

* Call Stack: Shows you exactly which functions the program has gone through to reach the current point.

* Registers Window (Cortex-Debug): A highlight for bare-metal developers. Here you can see the CPU registers of the ARM Cortex-A76 core (X0 to X30, SP, PC, etc.) with real-time access. If a register value changes after a single step, it is highlighted in color.

[[Datei:Debuger Ansicht.png|300x200px]]

==== Setting Breakpoints with a Mouse Click ====
Typing memory addresses into GDB is a thing of the past. In VS Code, simply move your mouse to the left of the line numbers in the source code (e.g., in kernel.c on the line ''LED_on();''). A faint red dot will appear. With a simple left-click, you activate the breakpoint (it turns solid red). If you now press '''F5''' (Continue), the program runs until it reaches exactly this line and freezes the CPU. Another click on the dot removes the breakpoint again.

[[Datei:Breakpoint1.png|200x200px]]
[[Datei:Breakpoint2.png|200x200px]]

== Summary ==
You have now set up a fully-fledged, professional development environment with hardware debugging for the Raspberry Pi 5!

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:28:29Z

Satyria:

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:25:31Z

Satyria: /* Source Code, Linker Script, and Makefile */

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:23:19Z

Satyria: /* The Include Directory (include/) */

Many developers desire a professional way to perform bare-metal development directly within a graphical user interface (GUI). In this guide, I will show you how to set up such a development environment. As our IDE (Integrated Development Environment), we will use Visual Studio Code from Microsoft, which is released under the open-source MIT license.

To communicate directly with the Raspberry Pi 5 and debug programs, you will additionally need a '''Raspberry Pi Debug Probe'''. This is connected to a Windows PC via USB and to the Raspberry Pi 5 via the debug pins.

== Software Requirements ==
As mentioned earlier, we will use Visual Studio Code as our GUI. The software can be downloaded for free from the official website:

👉 https://code.visualstudio.com/

Additionally, we need the official toolchain from ARM to be able to compile code for the AArch64 architecture of the Raspberry Pi 5. It is available for download here:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Note: At the time of writing this tutorial, version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' was used. Since the toolchain is under continuous development, the version number of your download may vary slightly.

For the connection between the PC and the Debug Probe, we use OpenOCD (Open On-Chip Debugger). A pre-compiled Windows version is provided by the xPack project:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direct download link for the version used: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Finally, we also need the build tool '''GNU Make''', which we will install directly via the Windows console in the next step.
== Installation and Setup ==
=== Setting Up the Toolchain ===
Since Windows can occasionally have issues with very long path names, we first rename the downloaded toolchain archive to '''toolchain.zip'''.

Extract the ZIP archive completely.

Create a new directory directly on your system drive: '''C:\tools'''.

Copy the entire contents of the extracted toolchain folder into this directory, so that the folder structure starts directly with '''C:\tools\bin'''.

=== Setting Up and Configuring OpenOCD ===
Extract the OpenOCD ZIP archive.

In the extracted folder, you will find the subdirectory '''xpack-openocd-0.12.0-7''' (or your more recent version). Simply rename this folder to '''openocd'''.

Move the entire '''openocd''' folder to '''C:\tools''', so that the path becomes '''C:\tools\openocd'''.

Next, check if the file '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' exists. This is usually included by default. If it is missing, create this file with the following content:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>

Since older or standard OpenOCD releases lack a suitable target profile for the new Broadcom BCM2712 chip of the Raspberry Pi 5, we need to create it manually. To do this, create a new file at the path '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' and insert the following content:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# These addresses were read from the ROM table via the 'dap info 0' command
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== Installing GNU Make ===
On Windows, a package for '''GNU Make''' is available, which can be conveniently installed via the integrated package manager. Open a terminal (Command Prompt or PowerShell) and enter the following command:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
The program is installed by default in the directory '''C:\Program Files (x86)\GnuWin32\bin'''. To ensure that '''Make''' works smoothly with our other tools, copy the entire contents of this bin folder into our previously created directory '''C:\tools\bin'''.

=== Adjusting the "Path" Environment Variable ===
In order for Windows and Visual Studio Code to find the installed tools (compiler, Make, and OpenOCD) system-wide via the console, we need to add the executables to the system path.

Press the '''Windows key''' and type "''environment variables''" in the search field.

Select the option "''Edit the system environment variables''" and click the "''Environment Variables...''" button at the bottom of the next window.

[[Datei:Path1.png|300x300px]]

In the "''User variables''" or "''System variables''" section, look for the entry '''Path''' (or PATH) and select Edit.

[[Datei:Path2.png|300x300px]]

Add the following two paths to the list as separate, new lines:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Confirm all open windows with '''OK'''.

[[Datei:Path3.png|300x300px]]

The basic toolchain is now successfully installed and set up. In the next part, we will focus on configuring Visual Studio Code for the actual bare-metal project.

=== Setting Up Visual Studio Code ===
Now that the basic toolchain is installed, we will set up the development environment in Visual Studio Code.

First, complete the installation of Visual Studio Code using the installer you downloaded earlier.

==== Installing VS Code Extensions ====
Open Visual Studio Code. To make bare-metal development as comfortable as possible, we will first install some essential extensions. Click on the Extensions icon in the left menu bar (or press CTRL + SHIFT + X) and search for the following extensions:

* C/C++ (by Microsoft): Provides syntax highlighting and code completion (IntelliSense) for C/C++.
* C/C++ Extension Pack (optional): Comes with additional useful tools for C development.
* Cortex-Debug (by marus25): The key extension that allows us to debug directly on the Raspberry Pi 5 via OpenOCD.
* Arm Assembly (by dan-c-underwood): Provides excellent support and highlighting for ARM assembly code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Changing the User Interface Language to German ====
If your VS Code is in English and you prefer the German interface, for example:

Press '''CTRL + SHIFT + P''' to open the Command Palette. Type ''Configure Display Language'' and press '''Enter'''.

Select "Deutsch" (German). (If it is not listed, you can install it directly from there).

Restart VS Code.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Creating and Opening the Project Directory ====
Now create a directory on your hard drive where your bare-metal project will reside. In this example, we will use the path '''D:\projekt1'''. In VS Code, select ''File -> Open Folder...'' and choose the directory '''D:\projekt1'''. Confirm the security prompt asking if you trust the authors of the folder by clicking "''Yes, I trust the authors''".

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Creating the .vscode Configuration Files ====

To let VS Code know which compiler to use and how to start the debugger, we need to create a configuration directory. In the main directory of your project, create a new folder with the exact name '''.vscode''' (don't forget the dot at the beginning!). Right-click on the newly created '''.vscode''' folder and create the following three files one after the other.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Copy the corresponding JSON code into each of them:

* '''c_cpp_properties.json''': This file configures code completion (IntelliSense) so that VS Code understands the ARM-specific commands and headers.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': This file controls the debugger (Cortex-Debug). It ensures that your code is loaded onto the Raspberry Pi 5 via OpenOCD and that the processor is stopped exactly at the start address.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Overrides the default "reset halt" command from VS Code
"overrideResetCommands": [
"monitor halt"
],

// Commands that are executed directly after connecting
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Forces the processor directly to the start address
],

"preLaunchTask": "Compile"
}
]
}
</syntaxhighlight>
* '''tasks.json''': This defines the automated build process. Before the debugger starts, this task automatically calls make.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Compile",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Save all configurations by clicking ''File -> Save All'' in the menu.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Note on Apparent Error Messages ====
After saving the '''c_cpp_properties.json''', you will probably notice a small red "'''2'''" in the file explorer or in the "Problems" tab (at the bottom of VS Code). This indicates active warnings. If you click on the message, you will see the reason: VS Code is complaining that the two directory paths '''${workspaceFolder}/include''' and '''${workspaceFolder}/src''' do not exist.

[[Datei:Prob1.png|200x200px]]

💡Don't worry: This is completely correct! Since we started with an empty project, these folders simply don't exist yet. As soon as you create the '''src''' and '''include''' folders later in your project, this warning will disappear automatically.

Tip: If VS Code does not immediately register newly created folders, you can quickly refresh the development environment. To do this, press '''F1''', type ''Reload Window'', and confirm with '''Enter'''. This reloads the interface without interrupting your work.

== Source Code, Linker Script, and Makefile ==
=== The Source Code Directory (src/) ===
To practically test our setup, we will use a minimalist LED blinking example in C and Assembly ([[Lass die LED leuchten in C (PI5)]]). This project uses a split into multiple files so that you can directly experience cross-references in the code and the convenience of a professional GUI.

In the main directory of your project (e.g., '''D:\projekt1'''), create a new folder named '''src'''.

💡 Important note for assembly files: Make sure that assembly files that use the C preprocessor (such as including header files via '''#include''') strictly have the file extension with a capital "'''S'''" ('''.S'''). A lowercase "s" will cause the compiler to ignore the includes.

Create the following six files in the '''src/''' folder:

'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Ensures that the linker places this at the beginning of the kernel image
.globl _start // Execution starts here

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Initialize stack pointer
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Set bit 9 to 0
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Set bit 9 to 1
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 cycles)
{
volatile u32 i;
for (i = 0; i < cycles; i++)
{
// Empty loop for delay
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Note''': As soon as you save these files, VS Code will display various errors in the "Problems" tab. The code will be underlined with red, wavy lines. This is completely normal because the compiler currently lacks the header files (.h) and cannot resolve the references.

[[Datei:Source prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:
'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//
#ifndef _base_h
#define _base_h
#define RPI_BASE 0x107C000000UL
// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)
#endif
</syntaxhighlight>
'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//
#ifndef _config_h
#define _config_h
#define MEGABYTE 0x100000
#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)
#endif
</syntaxhighlight>
'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//
#ifndef _ms_led_h
#define _ms_led_h
void LED_off(void);
void LED_on(void);
#endif
</syntaxhighlight>
'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//
#ifndef _ms_time_h
#define _ms_time_h
#include "types.h"
void wait(u32 cycles);
#endif
</syntaxhighlight>
'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//
#ifndef _ms_types_h
#define _ms_types_h
typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;
typedef signed char s8;
typedef signed short s16;
typedef signed int s32;
typedef unsigned long u64;
typedef signed long s64;
typedef long intptr;
typedef unsigned long uintptr;
typedef unsigned long size_t;
typedef long ssize_t;
typedef char boolean;
#define ALIGN(n) attribute((aligned (n)))
#define FALSE 0
#define TRUE 1
#endif
</syntaxhighlight>
'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//
#ifndef _ms_util_h
#define _ms_util_h
#include "types.h"
void write32(u64 a, u32 b);
u32 read32(u64 a);
#endif
</syntaxhighlight>
As soon as all header files are saved in the include folder, the red lines in VS Code will disappear automatically. The GUI has successfully recognized the references.
[[Datei:Null prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 cycles);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

As soon as all header files are saved in the include folder, the red lines in VS Code will disappear automatically. The GUI has successfully recognized the references.

[[Datei:Null prob.png|200x200px]]

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:18:23Z

Satyria: /* Important: Note on Apparent Error Messages */

Many developers desire a professional way to perform bare-metal development directly within a graphical user interface (GUI). In this guide, I will show you how to set up such a development environment. As our IDE (Integrated Development Environment), we will use Visual Studio Code from Microsoft, which is released under the open-source MIT license.

To communicate directly with the Raspberry Pi 5 and debug programs, you will additionally need a '''Raspberry Pi Debug Probe'''. This is connected to a Windows PC via USB and to the Raspberry Pi 5 via the debug pins.

== Software Requirements ==
As mentioned earlier, we will use Visual Studio Code as our GUI. The software can be downloaded for free from the official website:

👉 https://code.visualstudio.com/

Additionally, we need the official toolchain from ARM to be able to compile code for the AArch64 architecture of the Raspberry Pi 5. It is available for download here:

👉 [https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ARM GNU Toolchain Downloads]

Note: At the time of writing this tutorial, version ''arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-aarch64-none-elf.zip'' was used. Since the toolchain is under continuous development, the version number of your download may vary slightly.

For the connection between the PC and the Debug Probe, we use OpenOCD (Open On-Chip Debugger). A pre-compiled Windows version is provided by the xPack project:

👉 [https://xpack-dev-tools.github.io/openocd-xpack/ xPack OpenOCD Website]

Direct download link for the version used: [https://github.com/xpack-dev-tools/openocd-xpack/releases/download/v0.12.0-7/xpack-openocd-0.12.0-7-win32-x64.zip xPack OpenOCD v0.12.0-7]

Finally, we also need the build tool '''GNU Make''', which we will install directly via the Windows console in the next step.
== Installation and Setup ==
=== Setting Up the Toolchain ===
Since Windows can occasionally have issues with very long path names, we first rename the downloaded toolchain archive to '''toolchain.zip'''.

Extract the ZIP archive completely.

Create a new directory directly on your system drive: '''C:\tools'''.

Copy the entire contents of the extracted toolchain folder into this directory, so that the folder structure starts directly with '''C:\tools\bin'''.

=== Setting Up and Configuring OpenOCD ===
Extract the OpenOCD ZIP archive.

In the extracted folder, you will find the subdirectory '''xpack-openocd-0.12.0-7''' (or your more recent version). Simply rename this folder to '''openocd'''.

Move the entire '''openocd''' folder to '''C:\tools''', so that the path becomes '''C:\tools\openocd'''.

Next, check if the file '''C:\tools\openocd\openocd\scripts\interface\cmsis-dap.cfg''' exists. This is usually included by default. If it is missing, create this file with the following content:
<syntaxhighlight>
adapter driver cmsis-dap
</syntaxhighlight>

Since older or standard OpenOCD releases lack a suitable target profile for the new Broadcom BCM2712 chip of the Raspberry Pi 5, we need to create it manually. To do this, create a new file at the path '''C:\tools\openocd\openocd\scripts\target\bcm2712.cfg''' and insert the following content:
<syntaxhighlight>
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME bcm2712
}

if { [info exists CHIPCORES] } {
set _cores $CHIPCORES
} else {
set _cores 4
}

if { [info exists USE_SMP] } {
set _USE_SMP $USE_SMP
} else {
set _USE_SMP 0
}

if { [info exists DAP_TAPID] } {
set _DAP_TAPID $DAP_TAPID
} else {
set _DAP_TAPID 0x4ba00477
}

transport select swd

swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID -irlen 4
adapter speed 4000

dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu

# MEM-AP for direct access
target create $_CHIPNAME.ap mem_ap -dap $_CHIPNAME.dap -ap-num 0

# These addresses were read from the ROM table via the 'dap info 0' command
set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}

set _smp_command "target smp"

for { set _core 0 } { $_core < $_cores } { incr _core } {
set _CTINAME $_CHIPNAME.cti$_core
set _TARGETNAME $_CHIPNAME.cpu$_core

cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -ap-num 0 -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME

set _smp_command "$_smp_command $_TARGETNAME"
}

if {$_USE_SMP} {
eval $_smp_command
}

# Default target is cpu0
targets $_CHIPNAME.cpu0
</syntaxhighlight>

=== Installing GNU Make ===
On Windows, a package for '''GNU Make''' is available, which can be conveniently installed via the integrated package manager. Open a terminal (Command Prompt or PowerShell) and enter the following command:
<syntaxhighlight>
winget install GnuWin32.Make
</syntaxhighlight>
The program is installed by default in the directory '''C:\Program Files (x86)\GnuWin32\bin'''. To ensure that '''Make''' works smoothly with our other tools, copy the entire contents of this bin folder into our previously created directory '''C:\tools\bin'''.

=== Adjusting the "Path" Environment Variable ===
In order for Windows and Visual Studio Code to find the installed tools (compiler, Make, and OpenOCD) system-wide via the console, we need to add the executables to the system path.

Press the '''Windows key''' and type "''environment variables''" in the search field.

Select the option "''Edit the system environment variables''" and click the "''Environment Variables...''" button at the bottom of the next window.

[[Datei:Path1.png|300x300px]]

In the "''User variables''" or "''System variables''" section, look for the entry '''Path''' (or PATH) and select Edit.

[[Datei:Path2.png|300x300px]]

Add the following two paths to the list as separate, new lines:
<syntaxhighlight>
C:\tools\bin
C:\tools\openocd\bin
</syntaxhighlight>
Confirm all open windows with '''OK'''.

[[Datei:Path3.png|300x300px]]

The basic toolchain is now successfully installed and set up. In the next part, we will focus on configuring Visual Studio Code for the actual bare-metal project.

=== Setting Up Visual Studio Code ===
Now that the basic toolchain is installed, we will set up the development environment in Visual Studio Code.

First, complete the installation of Visual Studio Code using the installer you downloaded earlier.

==== Installing VS Code Extensions ====
Open Visual Studio Code. To make bare-metal development as comfortable as possible, we will first install some essential extensions. Click on the Extensions icon in the left menu bar (or press CTRL + SHIFT + X) and search for the following extensions:

* C/C++ (by Microsoft): Provides syntax highlighting and code completion (IntelliSense) for C/C++.
* C/C++ Extension Pack (optional): Comes with additional useful tools for C development.
* Cortex-Debug (by marus25): The key extension that allows us to debug directly on the Raspberry Pi 5 via OpenOCD.
* Arm Assembly (by dan-c-underwood): Provides excellent support and highlighting for ARM assembly code.

[[Datei:Erw1.png|200x200px]]
[[Datei:Erw2.png|200x200px]]
[[Datei:Erw3.png|200x200px]]
[[Datei:Erw4.png|200x200px]]

==== Optional: Changing the User Interface Language to German ====
If your VS Code is in English and you prefer the German interface, for example:

Press '''CTRL + SHIFT + P''' to open the Command Palette. Type ''Configure Display Language'' and press '''Enter'''.

Select "Deutsch" (German). (If it is not listed, you can install it directly from there).

Restart VS Code.

[[Datei:Lang1.png|200x200px]]
[[Datei:Lang2.png|200x200px]]
[[Datei:Lang3.png|200x200px]]
[[Datei:Lang4.png|200x200px]]

==== Creating and Opening the Project Directory ====
Now create a directory on your hard drive where your bare-metal project will reside. In this example, we will use the path '''D:\projekt1'''. In VS Code, select ''File -> Open Folder...'' and choose the directory '''D:\projekt1'''. Confirm the security prompt asking if you trust the authors of the folder by clicking "''Yes, I trust the authors''".

[[Datei:Proj1.png|200x200px]]
[[Datei:Proj2.png|200x200px]]

==== Creating the .vscode Configuration Files ====

To let VS Code know which compiler to use and how to start the debugger, we need to create a configuration directory. In the main directory of your project, create a new folder with the exact name '''.vscode''' (don't forget the dot at the beginning!). Right-click on the newly created '''.vscode''' folder and create the following three files one after the other.

[[Datei:Konf1.png|200x200px]]
[[Datei:Konf2.png|200x200px]]

Copy the corresponding JSON code into each of them:

* '''c_cpp_properties.json''': This file configures code completion (IntelliSense) so that VS Code understands the ARM-specific commands and headers.
<syntaxhighlight lang="json">
{
"configurations": [
{
"name": "Bare-Metal (Pi 5)",
"includePath": [
"${workspaceFolder}/include",
"${workspaceFolder}/src"
],
"compilerPath": "C:/tools/bin/aarch64-none-elf-gcc.exe",
"cStandard": "c11",
"cppStandard": "c++14",
"intelliSenseMode": "windows-gcc-arm64"
}
],
"version": 4
}
</syntaxhighlight>
* '''launch.json''': This file controls the debugger (Cortex-Debug). It ensures that your code is loaded onto the Raspberry Pi 5 via OpenOCD and that the processor is stopped exactly at the start address.
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "Bare-Metal Debug (Pi 5)",
"cwd": "${workspaceFolder}",
"executable": "${workspaceFolder}/kernel_2712.elf",
"request": "launch",
"type": "cortex-debug",
"runToEntryPoint": "0x80000",
"servertype": "openocd",
"searchDir": [
"C:/tools/openocd/openocd/scripts"
],
"configFiles": [
"interface/cmsis-dap.cfg",
"target/bcm2712.cfg"
],
"gdbPath": "C:/tools/bin/aarch64-none-elf-gdb.exe",
"serverpath": "C:/tools/openocd/bin/openocd.exe",

"openOCDLaunchCommands": [
"transport select swd",
"adapter speed 1000"
],

// Overrides the default "reset halt" command from VS Code
"overrideResetCommands": [
"monitor halt"
],

// Commands that are executed directly after connecting
"overrideLaunchCommands": [
"monitor halt",
"load",
"monitor reg pc 0x80000" // Forces the processor directly to the start address
],

"preLaunchTask": "Compile"
}
]
}
</syntaxhighlight>
* '''tasks.json''': This defines the automated build process. Before the debugger starts, this task automatically calls make.
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Compile",
"type": "shell",
"command": "make",
"args": ["all"],
"options": {
"env": {
"PATH": "${env:PATH};C:\\tools\\bin"
}
},
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
</syntaxhighlight>
Save all configurations by clicking ''File -> Save All'' in the menu.

[[Datei:AllesSpeichern.png|200x200px]]
[[Datei:Konfübersicht.png|200x200px]]

==== Important: Note on Apparent Error Messages ====
After saving the '''c_cpp_properties.json''', you will probably notice a small red "'''2'''" in the file explorer or in the "Problems" tab (at the bottom of VS Code). This indicates active warnings. If you click on the message, you will see the reason: VS Code is complaining that the two directory paths '''${workspaceFolder}/include''' and '''${workspaceFolder}/src''' do not exist.

[[Datei:Prob1.png|200x200px]]

💡Don't worry: This is completely correct! Since we started with an empty project, these folders simply don't exist yet. As soon as you create the '''src''' and '''include''' folders later in your project, this warning will disappear automatically.

Tip: If VS Code does not immediately register newly created folders, you can quickly refresh the development environment. To do this, press '''F1''', type ''Reload Window'', and confirm with '''Enter'''. This reloads the interface without interrupting your work.

== Source Code, Linker Script, and Makefile ==
=== The Source Code Directory (src/) ===
To practically test our setup, we will use a minimalist LED blinking example in C and Assembly ([[Lass die LED leuchten in C (PI5)]]). This project uses a split into multiple files so that you can directly experience cross-references in the code and the convenience of a professional GUI.

In the main directory of your project (e.g., '''D:\projekt1'''), create a new folder named '''src'''.

💡 Important note for assembly files: Make sure that assembly files that use the C preprocessor (such as including header files via '''#include''') strictly have the file extension with a capital "'''S'''" ('''.S'''). A lowercase "s" will cause the compiler to ignore the includes.

Create the following six files in the '''src/''' folder:

'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Ensures that the linker places this at the beginning of the kernel image
.globl _start // Execution starts here

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Initialize stack pointer
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Set bit 9 to 0
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Set bit 9 to 1
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 cycles)
{
volatile u32 i;
for (i = 0; i < cycles; i++)
{
// Empty loop for delay
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Note''': As soon as you save these files, VS Code will display various errors in the "Problems" tab. The code will be underlined with red, wavy lines. This is completely normal because the compiler currently lacks the header files (.h) and cannot resolve the references.

[[Datei:Source prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 cycles);

#endif
== Source Code, Linker Script, and Makefile ==
=== The Source Code Directory (src/) ===
To practically test our setup, we will use a minimalist LED blinking example in C and Assembly ([[Lass die LED leuchten in C (PI5)]]). This project uses a split into multiple files so that you can directly experience cross-references in the code and the convenience of a professional GUI.

In the main directory of your project (e.g., '''D:\projekt1'''), create a new folder named '''src'''.

💡 Important note for assembly files: Make sure that assembly files that use the C preprocessor (such as including header files via '''#include''') strictly have the file extension with a capital "'''S'''" ('''.S'''). A lowercase "s" will cause the compiler to ignore the includes.

Create the following six files in the '''src/''' folder:

'''src/boot.S''':
<syntaxhighlight lang="asm">
// boot.S
//

#include "config.h"

.section .init // Ensures that the linker places this at the beginning of the kernel image
.globl _start // Execution starts here

_start:
ldr x0, =MEM_KERNEL_STACK
mov sp, x0 // Initialize stack pointer
b sysinit
</syntaxhighlight>

'''src/kernel.c''':
<syntaxhighlight lang="C">
// kernel.c
//

#include "led.h"
#include "time.h"

int main (void)
{
while(1)
{
LED_off();
wait(0x3F0000);
LED_on();
wait(0x3F0000);
}
}
</syntaxhighlight>

'''src/led.c''':
<syntaxhighlight lang="C">
// led.c
//

#include "base.h"
#include "util.h"
#include "types.h"

void LED_off(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg &= ~0x200; // Set bit 9 to 0
write32(ARM_GPIO2_DATA0, reg);
}

void LED_on(void)
{
u32 reg = read32(ARM_GPIO2_DATA0);
reg |= 0x200; // Set bit 9 to 1
write32(ARM_GPIO2_DATA0, reg);
}
</syntaxhighlight>

'''src/sysinit.S''':
<syntaxhighlight lang="asm">
// sysinit.S
//

.section .text
.globl sysinit

sysinit:
b main
</syntaxhighlight>

'''src/time.c''':
<syntaxhighlight lang="C">
// time.c
//

#include "types.h"

void wait(u32 cycles)
{
volatile u32 i;
for (i = 0; i < cycles; i++)
{
// Empty loop for delay
}
}
</syntaxhighlight>

'''src/util.S''':
<syntaxhighlight lang="asm">
// util.S
//

.globl write32
write32:
stp x29, x30, [sp, -16]!
mov x29, sp
str w1, [x0]
ldp x29, x30, [sp], 16
ret

.globl read32
read32:
stp x29, x30, [sp, -16]!
mov x29, sp
ldr w0, [x0]
ldp x29, x30, [sp], 16
ret
</syntaxhighlight>

'''Note''': As soon as you save these files, VS Code will display various errors in the "Problems" tab. The code will be underlined with red, wavy lines. This is completely normal because the compiler currently lacks the header files (.h) and cannot resolve the references.

[[Datei:Source prob.png|200x200px]]

=== The Include Directory (include/) ===
To fix the errors, we will now create the header files. To do this, create a new folder named '''include''' in the main directory of your project. Place the following six files inside it:

'''include/base.h''':
<syntaxhighlight lang="C">
// base.h
//

#ifndef _base_h
#define _base_h

#define RPI_BASE 0x107C000000UL

// GPIO definitions for the Pi 5
#define ARM_GPIO2_BASE (RPI_BASE + 0x1517C00)
#define ARM_GPIO2_DATA0 (ARM_GPIO2_BASE + 0x04)

#endif
</syntaxhighlight>

'''include/config.h''':
<syntaxhighlight lang="C">
// config.h
//

#ifndef _config_h
#define _config_h

#define MEGABYTE 0x100000

#define MEM_KERNEL_START 0x80000 // Start address of the main program
#define KERNEL_MAX_SIZE (2 * MEGABYTE)
#define MEM_KERNEL_END (MEM_KERNEL_START + KERNEL_MAX_SIZE)
#define KERNEL_STACK_SIZE 0x20000
#define MEM_KERNEL_STACK (MEM_KERNEL_END + KERNEL_STACK_SIZE)

#endif
</syntaxhighlight>

'''include/led.h''':
<syntaxhighlight lang="C">
// led.h
//

#ifndef _ms_led_h
#define _ms_led_h

void LED_off(void);
void LED_on(void);

#endif
</syntaxhighlight>

'''include/time.h''':
<syntaxhighlight lang="C">
// time.h
//

#ifndef _ms_time_h
#define _ms_time_h

#include "types.h"

void wait(u32 cycles);

#endif
</syntaxhighlight>

'''include/types.h''':
<syntaxhighlight lang="C">
// types.h
//

#ifndef _ms_types_h
#define _ms_types_h

typedef unsigned char u8;
typedef unsigned short u16;
typedef unsigned int u32;

typedef signed char s8;
typedef signed short s16;
typedef signed int s32;

typedef unsigned long u64;
typedef signed long s64;

typedef long intptr;
typedef unsigned long uintptr;

typedef unsigned long size_t;
typedef long ssize_t;

typedef char boolean;

#define ALIGN(n) __attribute__((aligned (n)))

#define FALSE 0
#define TRUE 1

#endif
</syntaxhighlight>

'''include/util.h''':
<syntaxhighlight lang="C">
// util.h
//

#ifndef _ms_util_h
#define _ms_util_h

#include "types.h"

void write32(u64 a, u32 b);
u32 read32(u64 a);

#endif
</syntaxhighlight>

As soon as all header files are saved in the include folder, the red lines in VS Code will disappear automatically. The GUI has successfully recognized the references.

[[Datei:Null prob.png|200x200px]]

Professional GUI with Debugging for Bare-Metal on the Raspberry Pi 5

2026-06-03T16:17:32Z

Satyria: /* Important: Note on Apparent Error Messages */