Seminar oreboot auf Canaan K230: Portierungsworkshop

Inhaltsverzeichnis

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

Einordnung

Der Workshop überträgt die allgemeine oreboot-Portierungsmethodik auf eine K230-basierte CanMV-Zielplattform. Die Arbeit erfolgt vom dokumentierten Resetzustand über frühe Diagnose und Speicherinitialisierung bis zur SBI- und Linux-Übergabe.

Kompetenzziele

• K230-spezifische Boot-, Speicher- und Privilegannahmen für das Zielboard dokumentieren.
• Einen bestehenden Boardpfad reproduzierbar bauen und auf das Laborgerät übertragen.
• UART, frühe Stufe, DRAM, Storage, Device Tree und SBI in klaren Meilensteinen prüfen.
• Abweichungen zwischen Referenzpfad und konkreter Boardrevision systematisch behandeln.
• Einen belastbaren Bootnachweis bis zum Kernelstart erstellen.

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: Canaan K230 und CanMV-orientierter Boardpfad

1. Schritt 1: K230-Startumgebung einordnen

   Boot-ROM-Verhalten, RISC-V-Harts, frühe Speicherbereiche und verfügbare Recovery-Wege werden für das Zielboard zusammengestellt.

2. Schritt 2: Boarddateien abgleichen

   Vorhandene frühe und spätere Stufen, Linkerannahmen, Device Tree und Payloadpositionen werden gegen das konkrete Board geprüft.

3. Schritt 3: Peripherie priorisieren

   UART, Clock, Reset, DRAM und das vorgesehene Bootmedium werden in einer bring-up-gerechten Reihenfolge bearbeitet.

4. Schritt 4: Boot bis Linux nachweisen

   Serielle Marker, SBI-Übergabe, Device Tree und Kernelstart werden als zusammenhängender Nachweis dokumentiert.

Modul 3: Entwicklungsumgebung und Rust-Toolchain

1. Schritt 1: Werkzeugbestand erfassen

   Rust-Toolchain, Cross-Compiler, Binutils, Device-Tree-Compiler, Emulator, serielle Werkzeuge und Flash-Hilfen werden versioniert dokumentiert.

2. Schritt 2: Zielplattform einrichten

   Target-Spezifikation, Runner, Linker, Rust-Quellenkomponenten und benötigte Cargo-Erweiterungen werden reproduzierbar konfiguriert.

3. Schritt 3: Build-Umgebung isolieren

   Pfadabhängigkeiten, Umgebungsvariablen, Cache-Verhalten und lokale Werkzeuge werden so festgelegt, dass mehrere Arbeitsplätze gleiche Artefakte erzeugen.

4. Schritt 4: Diagnose durchführen

   Fehlende Targets, Linkerfehler, inkompatible Nightly-Funktionen und Werkzeugsuchpfade werden anhand eines systematischen Prüfablaufs eingegrenzt.

Modul 4: 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 5: 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 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: 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 9: Übergabe an Kernel und Betriebssystem

1. Schritt 1: Einstiegsvertrag prüfen

   Architekturabhängige Register, Privilegstufe, Interruptzustand, Cachezustand und erwarteter Einstiegspunkt werden festgehalten.

2. Schritt 2: Speicher freigeben

   Firmwarebereiche, reservierter Speicher, Device Tree, Initramfs und Kernel werden ohne Überlappung an das Betriebssystem übergeben.

3. Schritt 3: Gerätebeschreibung abstimmen

   Aktivierte Hardware, Konsolenpfad, Speicherkapazität, Interrupts und Bootargumente werden auf Konsistenz geprüft.

4. Schritt 4: Startnachweis führen

   Letzter Firmwaremarker, erster Kernelmarker, erkannter Speicher, Initialisierung der Konsole und Eintritt in den Userspace werden protokolliert.

Modul 10: 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.

Praxisübungen

• Eine K230-Boardakte mit Bootmodus, Speicherkarte, Recovery und Messpunkten erstellen.
• Frühe Firmware mit eindeutigen UART-Markern bauen und laden.
• DRAM- und Payloadbereiche anhand von Map-Datei und Speicherprüfung verifizieren.
• Device Tree und SBI-Übergabe für einen kontrollierten Kernelstart abstimmen.
• Einen fehlgeschlagenen Start über Recovery wiederherstellen und dokumentieren.

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

Firmwareentwickler, Embedded-Linux-Entwickler, RISC-V-Plattformteams, Board-Support und technische Integrationsverantwortliche.

Vorkenntnisse

Sichere Grundlagen in Rust oder systemnaher Programmierung, RISC-V-Grundkenntnisse, Erfahrung mit serieller Konsole und Cross-Builds. Ein geeignetes K230-Laborsystem ist für den vollständigen Praxisteil erforderlich.