feat(L04): add RV32I decoder and register file card

2026-07-21 16:54:03 +02:00
commit ecd7adc0ae
42 changed files with 7255 additions and 0 deletions
@@ -0,0 +1,41 @@
+# L04 · The RISC-V ISA and Instruction Decoder
+
+Karta zamienia 32-bitowe słowo instrukcji w jawny kontrakt sterowania rdzenia.
+Uczeń dekoduje pola RV32I, rozpoznaje klasę opcode i buduje bank 32 rejestrów,
+w którym `x0` zawsze zwraca zero.
+
+## Taski i mierzalne wyniki
+
+| Task | Zakres | PASS |
+| --- | --- | --- |
+| `task01_instruction_fields` | pola instrukcji I-type oraz sign extension | `ffc30293 → opcode=13 rd=5 rs1=6 imm=-4` |
+| `task02_opcode_decoder` | OP-IMM, OP, LOAD, STORE, BRANCH, JAL/JALR | dokładnie jedna klasa dla legalnego opcode, `illegal=1` dla `0x7f` |
+| `task03_register_file` | dwa porty odczytu, jeden zapisu, rejestr `x0` | zapis/odczyt `x5=12345678`, zapis `x0` zignorowany |
+
+## Uruchomienie
+
+```bash
+stemctl card use rv32i-asm L04
+stemctl tasks list
+stemctl test native-amd64 rv32i-asm L04 1
+stemctl test hazard3-sim rv32i-asm L04 1
+stemctl debug hazard3-sim rv32i-asm L04 3
+```
+
+Model AMD64 oblicza pola niezależnie od RTL. Właściwy pomiar SystemVerilog
+wykonuje Verilator w profilu `hazard3-sim`. Akcja `debug` zapisuje VCD w
+`.stem/artifacts`; karta nie przedstawia oczekiwanej liczby jako zmierzonej.
+
+Uczeń najpierw uzupełnia [answers/decoder-evidence.md](answers/decoder-evidence.md).
+Pełna mechaniczna kolejność znajduje się w [lesson-flow.yaml](lesson-flow.yaml).
+
+## Inwarianty
+
+- sign extension kopiuje bit `instr[31]` do starszych 20 bitów;
+- legalny opcode wybiera dokładnie jedną klasę sterowania;
+- nieznany opcode nie włącza żadnej operacji i ustawia `illegal`;
+- zapis następuje na zboczu, odczyt jest kombinacyjny;
+- `x0` nie ma przechowywanego, modyfikowalnego stanu.
+
+Te inwarianty są wejściem L05: ALU dostanie operandy z banku rejestrów oraz
+rodzaj operacji wyznaczony przez dekoder.