# 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.