Seminar oreboot Mainboard-Portierung und Board-Support

Inhaltsverzeichnis

• Einordnung
• Kompetenzziele
• Seminarinhalte
• Praxisübungen
• Methodik
• Zielgruppe
• Vorkenntnisse

Einordnung

Das Seminar vermittelt eine vollständige Methode für neue Mainboards: technische Vorprüfung, Struktur des Boardpfads, frühe und späte Stufe, Linker und Build, UART, DRAM, Storage, Device Tree, Payload, Tests, Dokumentation und reviewfähige Übergabe.

Kompetenzziele

• Dokumentationslage, Bootwege, Speicher und Recovery vor Beginn bewerten.
• Mainboardverzeichnis und Stufen mit minimalen Abhängigkeiten anlegen.
• Bring-up in UART-, DRAM-, Storage-, SBI- und Kernelmeilensteine zerlegen.
• SoC- und boardspezifischen Code sauber von generischen Treibern trennen.
• Hardwaretests, Negativfälle und Recovery in eine Abnahmematrix überführen.
• Änderungen upstream-fähig dokumentieren und warten.

Seminarinhalte

Modul 1: Boarddokumentation und technische Vorprüfung

1. Schritt 1: Unterlagen ordnen

   SoC-Handbuch, Board-Schaltplan, Speicherbestückung, Bootschalter, Pinbelegung und bekannte Errata werden versionsbezogen erfasst.

2. Schritt 2: Bootkonfiguration prüfen

   Straps, eFuses, Bootreihenfolge, Recovery-Modi und Sicherheitszustände werden für das konkrete Board dokumentiert.

3. Schritt 3: Messpunkte festlegen

   UART, JTAG, Reset, Versorgungsschienen, Takte und wichtige Chip-Select-Signale werden für das Labor zugänglich gemacht.

4. Schritt 4: Risiken bewerten

   Fehlende Dokumentation, geschlossene Initialisierungsbestandteile, nicht rücksetzbare Optionen und schwer zugängliche Flashbausteine werden vor Beginn markiert.

Modul 2: Quellbaum, Mainboards und Build-Zusammenhang

1. Schritt 1: Verzeichnisstruktur lesen

   Workspace, Architekturcode, SoC-Unterstützung, Mainboard-Verzeichnisse, Bibliotheken und Werkzeuge werden funktional zugeordnet.

2. Schritt 2: Boardpfad nachvollziehen

   Die Trennung von früher Stufe und Hauptstufe sowie die Rollen von Cargo-Konfiguration, Linkerskript, Build-Skript und Makefile werden untersucht.

3. Schritt 3: Abhängigkeiten prüfen

   Crates, Features, Zielarchitektur und lokale Pfade werden auf Reproduzierbarkeit, unnötige Kopplung und Plattformabhängigkeit geprüft.

4. Schritt 4: Änderungsumfang planen

   Neue Treiber, SoC-Bausteine, Boarddateien, Dokumentation und Tests werden als getrennte, reviewfähige Arbeitspakete vorbereitet.

Modul 3: Mainboard-Portierung und schrittweises Bring-up

1. Schritt 1: Minimalziel definieren

   Erster serieller Marker, stabiler DRAM, lesbares Bootmedium, SBI-Übergabe und Kernelstart werden als aufeinanderfolgende Meilensteine festgelegt.

2. Schritt 2: Boardstruktur anlegen

   Frühe Stufe, Hauptstufe, Cargo-Dateien, Linkerskripte, Build-Skript, Makefile und Device Tree werden mit minimalen Abhängigkeiten erstellt.

3. Schritt 3: Hardware einzeln aktivieren

   Clock, Reset, Pinmux, UART, Timer, DRAM und Storage werden nacheinander aktiviert und nach jedem Schritt geprüft.

4. Schritt 4: Port stabilisieren

   Fehlerpfade, Timeouts, Dokumentation, reproduzierbarer Build, Emulations- oder Hardwaretests und Reviewaufteilung werden ergänzt.

Modul 4: Resetvektor, Assemblereinstieg und Linkerskript

1. Schritt 1: Einstiegspunkt festlegen

   Resetadresse, Symbolname, Ausrichtungsanforderungen und der Übergang vom Assemblereinstieg zu Rust werden eindeutig definiert.

2. Schritt 2: Minimalzustand herstellen

   Stackzeiger, globale Pointer, BSS-Löschung, erforderliche Register und mehrere Harts werden kontrolliert initialisiert.

3. Schritt 3: Sektionen platzieren

   Code, schreibgeschützte Daten, initialisierte Daten, BSS, Stack und eingebettete Binärdaten werden passenden Speicherbereichen zugewiesen.

4. Schritt 4: Abbild prüfen

   Map-Datei und Disassemblierung werden genutzt, um Einstieg, Sprungweiten, Adressen und unerwartete Laufzeitabhängigkeiten zu kontrollieren.

Modul 5: Registerzugriffe, PAC und HAL

1. Schritt 1: Registermodell auswählen

   Manuelle Registerdefinition, generierter Peripheral Access Crate und Hardware-Abstraction-Layer werden nach Dokumentationslage und Wiederverwendbarkeit bewertet.

2. Schritt 2: Zugriffe typisieren

   Lesen, Schreiben, Read-Modify-Write, reservierte Bits und write-one-to-clear-Verhalten werden in sichere Bedienmuster überführt.

3. Schritt 3: Takt und Reset berücksichtigen

   Vor jedem Peripheriezugriff werden Clock-Gates, Resetleitungen, Pin-Multiplexing und notwendige Wartezeiten geprüft.

4. Schritt 4: Seiteneffekte testen

   Registerwerte, externe Signale, Timeout-Verhalten und Wiederholbarkeit werden mit serieller Diagnose und Messmitteln validiert.

Modul 6: UART als frühe Diagnose-Schnittstelle

1. Schritt 1: Signalweg klären

   SoC-Pins, Pegel, Adapter, Baudrate, Taktquelle und Massebezug werden vor dem ersten Zugriff geprüft.

2. Schritt 2: Minimalinitialisierung schreiben

   Clock-Gate, Reset, Pinmux, Teiler, Rahmenformat und FIFO werden mit möglichst wenigen Registerzugriffen gesetzt.

3. Schritt 3: Bootmarker definieren

   Kurze, eindeutige Marker kennzeichnen Reset, DRAM, Storage, SBI und Payload, ohne frühe Stufen unnötig zu vergrößern.

4. Schritt 4: Fehler robust erfassen

   Timeouts, unplausible Zeichen, falsche Taktrate und blockierende Ausgabe werden mit Alternativprüfungen eingegrenzt.

Modul 7: DRAM-Initialisierung und Speichertraining

1. Schritt 1: Parameter beschaffen

   Speichertyp, Takt, Topologie, Breite, Ranks, Timingwerte, Spannungen und Boardrouting werden aus belastbaren Hardwareangaben zusammengestellt.

2. Schritt 2: Controller vorbereiten

   Takt, Reset, PHY, Betriebsmodus, Timingregister und Initialisierungssequenz werden in einer kontrollierten Reihenfolge programmiert.

3. Schritt 3: Training überwachen

   Statusregister, Wartebedingungen, Timeouts und Fehlercodes werden mit frühen Diagnosemarkern sichtbar gemacht.

4. Schritt 4: Speicher validieren

   Adressleitungen, Datenmuster, verschiedene Größen, Cachezustände und Grenzbereiche werden vor dem Laden weiterer Stufen geprüft.

Modul 8: SPI-Flash und Firmwarezugriff

1. Schritt 1: Controller initialisieren

   Takt, Pin-Multiplexing, Chip-Select, Modus, Wortbreite und sichere Anfangsfrequenz werden gesetzt.

2. Schritt 2: Baustein identifizieren

   JEDEC-Kennung, Kapazität, Adressmodus, Statusregister und Schutzbits werden ausgelesen und plausibilisiert.

3. Schritt 3: Lesepfad implementieren

   Befehl, Adresse, Dummy-Zyklen, Transfergrenzen und Timeout werden in einen kleinen, testbaren Treiber überführt.

4. Schritt 4: Schreibschutz beachten

   Löschen, Programmieren, Busy-Prüfung, Verifikation und Recovery werden getrennt vom normalen Boot-Lesepfad behandelt.

Modul 9: SD- und eMMC-Zugriff

1. Schritt 1: Hostcontroller starten

   Clock, Reset, Pins, Versorgung und Identifikationsfrequenz werden vor der Kartenkommunikation geprüft.

2. Schritt 2: Medium identifizieren

   Resetfolge, Fähigkeiten, Kapazität, Blocklänge und Busbreite werden mit klaren Timeouts ermittelt.

3. Schritt 3: Blockleser aufbauen

   Einzel- und Mehrblockzugriff, DMA- oder PIO-Pfad, Alignment, Cachebehandlung und Fehlercodes werden implementiert.

4. Schritt 4: Bootdaten prüfen

   DTFS- oder Payloadbereiche werden blockweise gelesen, auf Grenzen geprüft und vor der Ausführung verifiziert.

Modul 10: Device Tree, DTB und Hardwarebeschreibung

1. Schritt 1: Hardwareknoten erfassen

   CPU, Speicher, UART, Timer, Interruptcontroller, Flash, SD-Schnittstelle und reservierte Speicherbereiche werden fachlich geprüft.

2. Schritt 2: Bootparameter pflegen

   Konsolenpfad, Kernelparameter, Initrd-Bereich und gewählte Knoten werden für die geplante Nutzlast konsistent gesetzt.

3. Schritt 3: DTB erzeugen und prüfen

   Quellbaum, Includes, Kompilierung, Deassemblierung und strukturelle Plausibilitätsprüfung werden als fester Arbeitsablauf ausgeführt.

4. Schritt 4: Übergabe verifizieren

   Adresse, Größe, Speicherüberlappung und tatsächlich vom Betriebssystem erkannte Hardware werden mit der Firmwarekonfiguration abgeglichen.

Modul 11: SBI und RustSBI als Übergabeschicht

1. Schritt 1: SBI-Rolle festlegen

   Timer, Interprozessorunterbrechung, Systemreset, Hartzustand und herstellerspezifische Erweiterungen werden zwischen Firmware und Supervisor getrennt.

2. Schritt 2: Plattformadapter anbinden

   Timerquelle, Interruptmechanismus, Resetpfad und Konsolenausgabe werden in die SBI-Implementierung integriert.

3. Schritt 3: Übergaberegister setzen

   Hart-ID, Device-Tree-Zeiger, Supervisor-Einstieg, Statusregister und Delegationen werden vor dem Moduswechsel verifiziert.

4. Schritt 4: SBI-Aufrufe prüfen

   Kernelanforderungen, Fehlercodes, nicht unterstützte Erweiterungen und Systemreset werden mit reproduzierbaren Tests bewertet.

Modul 12: Hardwarelabor und Abnahmemessungen

1. Schritt 1: Laborzustand standardisieren

   Versorgung, Adapter, Kabel, Bootschalter, Flashinhalt, Messgeräte und Hostsoftware werden vor jedem Versuch dokumentiert.

2. Schritt 2: Beobachtungspunkte verbinden

   Serielle Konsole, JTAG, Logikanalysator und Strommessung werden so vorbereitet, dass Bootphasen zeitlich zugeordnet werden können.

3. Schritt 3: Testfälle ausführen

   Kaltstart, Warmstart, wiederholter Reset, fehlendes Medium, beschädigtes Abbild und Recovery werden mit festen Erwartungswerten geprüft.

4. Schritt 4: Abnahme protokollieren

   Firmwarehash, Boardrevision, Messergebnis, Konsolenausgabe, Abweichung und Entscheidung werden in einem reproduzierbaren Prüfprotokoll zusammengeführt.

Modul 13: Upstream-Entwicklung und reviewfähige Änderungen

1. Schritt 1: Änderung zerlegen

   Infrastruktur, generischer Treiber, SoC-Unterstützung, Mainboardcode, Device Tree, Dokumentation und Tests werden in logisch getrennte Beiträge aufgeteilt.

2. Schritt 2: Commitqualität herstellen

   Jeder Commit erhält einen klaren Zweck, baut eigenständig, enthält keine Nebenänderungen und beschreibt beobachtbares Verhalten.

3. Schritt 3: Review vorbereiten

   Hardwarevoraussetzungen, Testablauf, Konsolenausgabe, bekannte Einschränkungen und Sicherheitsauswirkungen werden nachvollziehbar dokumentiert.

4. Schritt 4: Rückmeldungen einarbeiten

   Technische Einwände werden reproduziert, Änderungen gezielt überarbeitet und neue Testnachweise ohne unnötiges Umschreiben der Historie ergänzt.

Praxisübungen

• Eine Portierungsakte mit Zielbild, Risiken und Meilensteinen erstellen.
• Boardstruktur, Linkerlayout und minimalen Einstieg implementieren.
• UART sowie einen ausgewählten Storagepfad schrittweise aktivieren.
• DRAM- und Device-Tree-Annahmen mit Tests absichern.
• Boot bis SBI oder Kernel mit reproduzierbaren Markern nachweisen.
• Commit- und Teststruktur für eine reviewfähige Übergabe entwerfen.

Methodik

Fachliche Einordnung, kommentierte Demonstrationen und schrittweise Laboraufgaben werden eng miteinander verbunden. Jeder Arbeitsabschnitt beginnt mit einem überprüfbaren Zielzustand, wird anhand von Konsolen-, Build- oder Messdaten kontrolliert und endet mit einer dokumentierten Fehler- oder Abnahmeprüfung. Vorbereitete Negativfälle verhindern, dass ausschließlich der erfolgreiche Idealfall betrachtet wird.

Zielgruppe

Erfahrene Firmwareentwickler, SoC- und Board-Support, Embedded-Linux-Integration, technische Maintainer und Hardware-nahe Testteams.

Vorkenntnisse

Sichere systemnahe Programmierung, Rust- oder Embedded-C-Erfahrung, Linkerskripte, MMIO, serielle Diagnose und Grundkenntnisse der Zielarchitektur. Boardunterlagen und ein Recovery-Pfad sind erforderlich.