stem-launcher/doc/debug-documentation-guidelines.md

Wytyczne dokumentowania debugowania

Cel

Zrzut debuggera jest dowodem pomiaru, nie dekoracją. Ma pozwolić uczniowi połączyć jedną operację w C z instrukcjami RISC-V, rejestrami, ramką stosu i konkretnymi bajtami w RAM.

Kadr dowodowy

• Używaj rzeczywistej sesji stemctl debug z karty, symulatora albo płytki.
• Zatrzymaj program w jednym nazwanym punkcie: breakpoint, checkpoint albo instrukcja bezpośrednio przed obserwowaną operacją.
• Zachowaj wspólny układ: dashboard Termdebug/GDB po lewej, źródło C po prawej, listing .lst pod źródłem. Listing musi być zsynchronizowany z PC.
• Pokaż tylko dane potrzebne do tezy: wywołanie w C, odpowiadającą instrukcję, argument w rejestrze, fragment stosu albo pamięć w RAM.
• Dołącz podpis z platformą, taskiem i stanem pomiaru, na przykład „przed pierwszym przydziałem pamięci”.

Oznaczenia

• Stosuj najwyżej cztery krótkie oznaczenia numeryczne na jednym kadrze.
• Każdy numer ma odpowiadać jednemu zdaniu w podpisie lub legendzie.
• Bieżący kolor oznaczeń to czerwony: oznacza „zatrzymaj się i sprawdź”. Paleta może później ulec zmianie, ale numeracja i podpis muszą pozostać zrozumiałe bez koloru.
• Nie zasłaniaj kodu ani nie zmieniaj jego treści. Zachowaj surowy zrzut jako źródło, a adnotowany obraz zapisz jako osobny plik.

Wstawienie do karty

• Zasoby zapisuj w doc/assets/, np. task04-first-allocation-annotated.png.
• W doc/main.tex umieść obraz blisko instrukcji, której dotyczy, oraz dodaj zwięzły podpis wyjaśniający numery.
• Po zmianie zbuduj PDF skryptem scripts/render_pdf.sh i sprawdź stronę wynikową w rozmiarze A4.
• W materiałach dla ucznia używaj słowa RAM, nie skrótu „SRAM”.

Przykład referencyjny

Karta inf/pointers, Task04: alloc_local(5) przed pierwszym przydziałem. Kadr pokazuje wywołanie C, li a0,5 i jal alloc_local, wartość a0=5 oraz pusty allocbuf. Taki obraz dokumentuje związek źródła, ABI i pamięci bez zastępowania go opisem narracyjnym.