{
  "card": {
    "number": "12",
    "slug": "uart-polling-interrupts",
    "title": "UART — polling i przerwania RX",
    "topic": "MMIO UART, external IRQ oraz jednokomórkowa skrzynka ISR do main",
    "status": "Gotowa",
    "version": "v00.01",
    "revision_date": "2026-07-20T00:00:00+02:00"
  },
  "scope_headers": ["Typ", "Task", "Idea", "Waga"],
  "front": {
    "goal": "Uczeń odróżnia polling rejestru statusu od odbioru sterowanego zdarzeniem. Dla ścieżki przerwania wskazuje osobno: bajt w RX FIFO, stan linii external IRQ 16, selekcję przez kontroler Hazard3, wywołanie ISR i efekt konsumowany później przez main.",
    "scope": "Karta korzysta z laboratoryjnego modelu UART Hazard3. Rejestr \\texttt{TB\\_UART\\_TEST\\_RX} jest wyłącznie kontrolowanym bodźcem testbench; nie występuje w produkcyjnym UART ani na RP2350. Po wstrzyknięciu bajtu Task02 i Task03 przechodzą jednak przez rzeczywisty kontroler external IRQ, \\texttt{mtvec}, dispatcher i \\texttt{mret} modelowanego rdzenia."
  },
  "learning": {
    "reasoning_label": "Źródło to nie handler",
    "reasoning": "Uczeń rozpisuje cztery oddzielne etapy: stan FIFO, pending i enable, decyzję dispatchera oraz zmianę stanu aplikacji.",
    "practice_label": "Dowód na Hazard3",
    "practice": "Uczeń uruchamia trzy obrazy RV32I, odczytuje status UART, numer IRQ, bajty i liczniki oraz wiąże je z listingiem i kodem wyjścia.",
    "criterion": "Wszystkie trzy programy kończą się kodem 0 w Hazard3. Task01 odczytuje P przez polling: status 0x3 przed i 0x2 po odczycie. Task02 przed globalnym enable widzi pending=1, handler numeru 16 odczytuje R przy statusie 0x13, a po obsłudze pending=0. Task03 obsługuje trzy IRQ, przyjmuje A i C, odrzuca B zgodnie z drop-newest i kończy z accepted=2, dropped=1.",
    "requirement": "Obsługa MMIO i przerwania UART z jawnym rozdzieleniem bodźca testbench, stanu peryferium, kontrolera przerwań, ISR i normalnego kodu."
  },
  "sections": [
    {
      "title": "Polling pyta o stan w rytmie programu",
      "content_tex": "Rejestr \\texttt{STATUS.RX\\_AVAIL} opisuje niepusty RX FIFO, a odczyt \\texttt{DATA} usuwa jeden bajt. W Task01 przerwanie RX pozostaje wyłączone: program sam wykonuje kolejne odczyty statusu. Jest to poprawne dla prostego, krótkiego oczekiwania, lecz czas CPU zależy od częstotliwości odpytywania. Zapis \\texttt{TB\\_UART\\_TEST\\_RX='P'} jest bodźcem laboratoryjnym, nie częścią sterownika produkcyjnego."
    },
    {
      "title": "RX IRQ jest ścieżką pięciu stanów",
      "content_tex": "W Task02 bajt trafia do FIFO i model podnosi external IRQ 16 tylko wtedy, gdy \\texttt{CTRL.RX\\_IRQ\\_EN=1}. Kontroler Hazard3 próbkuje i udostępnia bieżący poziom pending; \\texttt{mstatus.MIE}, \\texttt{mie.MEIE} i enable linii decydują, czy rdzeń wejdzie do wektora. Dispatcher odczytuje \\texttt{meinext}, wybiera wpis 16 z tablicy i wykonuje \\texttt{jalr}. Odczyt DATA opróżnia FIFO, więc linia poziomowa i widoczny pending opadają; dopiero \\texttt{mret} wraca do normalnego kodu."
    },
    {
      "title": "ISR przekazuje minimum, main nadaje znaczenie",
      "content_tex": "Task03 nie analizuje komendy w ISR. Handler zawsze opróżnia DATA, a potem albo zapisuje bajt do jednej komórki, albo zwiększa licznik odrzuceń, gdy komórka jest pełna. Polityka \\texttt{drop-newest} jest celowo jawna i mierzalna. To nie jest kolejka ani synchronizacja RTOS: pojedyncze 32-bitowe obiekty \\texttt{volatile} i kontrolowana kolejność wystarczają wyłącznie dla tego jednego rdzenia i tego przykładu."
    }
  ],
  "tasks": [
    {
      "id": "task01",
      "chapter": "MMIO",
      "title": "Polling jednego bajtu",
      "idea_tex": "STATUS, DATA i kontrolowany RX stimulus",
      "priority": "kluczowe",
      "key": true,
      "prompt_tex": "Przewidź bity statusu przed i po odczycie P. Wskaż, która operacja tworzy bodziec testbench, która tylko obserwuje FIFO, a która usuwa bajt. Potwierdź także zapis T do rejestru TX.",
      "criterion": "Hazard3: status_before=0x3, rx_byte='P'=80, status_after=0x2, tx_byte='T'=84, osobna linia T w logu testbencha, pass=1 i kod wyjścia 0.",
      "evidence_tex": "Tabela bitów STATUS przed i po DATA, odczyt globali Task01, wskazanie transakcji MMIO w listingu RV32I oraz kod wyjścia Hazard3.",
      "worksheet_step2": "Status i bajt w modelu UART",
      "worksheet_step3": "Transakcje MMIO RV32I i kod wyjścia",
      "viewpoints": [
        {
          "id": "A1",
          "status": "enabled",
          "title": "CONTEXT — polling w granicy modelu",
          "content_tex": "Odpowiedzialność przykładu zaczyna się od kontrolowanego wstrzyknięcia P do RX FIFO i kończy na odczycie P oraz zapisie T do TX. Nie konfiguruje kontrolera przerwań. \\texttt{TEST\\_RX} należy wyłącznie do testbench; DATA, STATUS i CTRL modelują interfejs peryferium."
        },
        {
          "id": "A2",
          "status": "enabled",
          "title": "STRUCTURE — cztery rejestry i FIFO",
          "content_tex": "Pod bazą UART0 leżą DATA +0, STATUS +4, CTRL +8 i testowy \\texttt{TEST\\_RX} +12. FIFO nie jest bezpośrednio adresowalne: \\texttt{RX\\_AVAIL} mówi tylko, czy zawiera co najmniej jeden bajt, a DATA zwraca i usuwa element czołowy."
        },
        {
          "id": "A3",
          "status": "unavailable",
          "title": "DISPATCH",
          "reason": "RX IRQ pozostaje wyłączone, więc nie ma wejścia przez mtvec, wyboru ISR ani pośredniego jalr; wszystkie funkcje są wywołaniami bezpośrednimi normalnego kodu."
        },
        {
          "id": "A4",
          "status": "enabled",
          "title": "APPLICATION — przewidywanie bitów",
          "content_tex": "Bez klienta TCP status po wstrzyknięciu P ma wartość 0x3: \\texttt{RX\\_AVAIL} i \\texttt{TX\\_READY}. \\texttt{RX\\_IRQ} jest zerem, bo CTRL nie włącza źródła. Po odczycie DATA FIFO jest puste, więc zostaje 0x2. Znaki mają wartości P=80 i T=84."
        },
        {
          "id": "A5",
          "status": "enabled",
          "title": "FLOW — inject, status, data, status, tx",
          "content_tex": "Kolejność jest częścią dowodu: wyłącz IRQ, wstrzyknij P, odczytaj pierwszy status, odczytaj DATA, odczytaj drugi status, zapisz T. Zamiana DATA z pierwszym statusem zniszczyłaby obserwację \\texttt{RX\\_AVAIL=1}."
        },
        {
          "id": "A6",
          "status": "enabled",
          "title": "STATE — EMPTY do P do EMPTY",
          "content_tex": "RX FIFO przechodzi \\texttt{EMPTY -> ['P'] -> EMPTY}. Status jest funkcją tego stanu i nie przechowuje osobnej kopii flagi. Zapis TX jest widoczny jako T w logu testbencha; bez klienta TCP model nie zachowuje tego bajtu w kolejce sieciowej. Nie zmienia to stanu RX."
        },
        {
          "id": "A7",
          "status": "enabled",
          "title": "RUNTIME — adresy 0xc00002xx",
          "content_tex": "W listingu znajdź zapisy i odczyty pod bazą \\texttt{0xc0000200}. W checkpointcie globale mają wartości 3, 80, 2 i 84. Kod 0 pochodzi z pełnego gate, a nie z samego faktu, że program dotarł do \\texttt{\\_exit}."
        },
        {
          "id": "A8",
          "status": "enabled",
          "title": "PATTERNS — status-before-data",
          "content_tex": "Nazwany wzorzec polling RX brzmi: sprawdź availability, dopiero potem odczytaj destructive DATA. Jest prosty i deterministyczny, ale zużywa czas CPU, jeśli pętla oczekiwania nie ma ograniczenia ani innej pracy."
        }
      ]
    },
    {
      "id": "task02",
      "chapter": "IRQ",
      "title": "Odbiór R przez external IRQ 16",
      "idea_tex": "FIFO, pending, enable, dispatcher i mret",
      "priority": "kluczowe",
      "key": true,
      "prompt_tex": "Rozpisz osobno bity CTRL, pending linii 16, mstatus.MIE, mie.MEIE i enable kontrolera. Przewidź stan przed globalnym enable, numer wybrany przez meinext oraz czynność, która usuwa źródło poziomowe.",
      "criterion": "Hazard3: pending_before_enable=1; jeden handler IRQ 16 widzi status 0x13 i byte='R'=82; po odczycie DATA pending_after=0, pass=1 i kod 0.",
      "evidence_tex": "Ślad źródło→pending→enable→dispatcher→ISR→resume, wartości globali w checkpointcie, fragment \\texttt{jalr} z \\texttt{irq\\_dispatch.S} i kod wyjścia Hazard3.",
      "worksheet_step2": "Macierz pending i enable przed ISR",
      "worksheet_step3": "Numer IRQ, status, bajt i powrót mret",
      "viewpoints": [
        {
          "id": "A1",
          "status": "enabled",
          "title": "CONTEXT — pięć granic odpowiedzialności",
          "content_tex": "\\texttt{TEST\\_RX} tworzy bodziec, UART utrzymuje FIFO i linię 16, kontroler Hazard3 utrzymuje pending/priority/enable, dispatcher wybiera wpis, a ISR odczytuje DATA. Normalny kod tylko konfiguruje, włącza globalny bit, czeka i ocenia dowód."
        },
        {
          "id": "A2",
          "status": "enabled",
          "title": "STRUCTURE — stan peryferium, CSR i tabela",
          "content_tex": "Stan obejmuje \\texttt{CTRL.RX\\_IRQ\\_EN}, niepusty FIFO, pending linii 16, tablicę \\texttt{\\_external\\_irq\\_table[16]}, priorytet, \\texttt{mie.MEIE} i \\texttt{mstatus.MIE}. Żaden pojedynczy bit nie wystarcza do wejścia w ISR."
        },
        {
          "id": "A3",
          "status": "enabled",
          "title": "DISPATCH — meinext do wpisu 16",
          "content_tex": "Wektor machine external IRQ wchodzi do \\texttt{isr\\_external\\_irq}. Odczyt \\texttt{meinext} zwraca gotowy offset tablicy — numer linii 16 przesunięty o dwa bity. Dispatcher dodaje go do bazy \\texttt{\\_external\\_irq\\_table} i wykonuje \\texttt{jalr} do \\texttt{task02\\_uart\\_handler}. To jest rzeczywisty wybór wykonawcy, nie zwykłe statyczne wywołanie."
        },
        {
          "id": "A4",
          "status": "enabled",
          "title": "APPLICATION — R i status 0x13",
          "content_tex": "Przed globalnym enable pending ma być 1, lecz licznik handlera nadal 0. Po enable ISR ma zobaczyć \\texttt{RX\\_AVAIL}, \\texttt{TX\\_READY} i \\texttt{RX\\_IRQ}, czyli 0x13, odczytać R=82 i opublikować numer 16."
        },
        {
          "id": "A5",
          "status": "enabled",
          "title": "FLOW — konfiguracja przed globalnym enable",
          "content_tex": "Najpierw MIE jest wyzerowane, potem ustawiane są handler, priorytet, enable linii, MEIE i CTRL. Dopiero po wstrzyknięciu R i zmierzeniu pending program ustawia MIE. ISR czyta DATA, dispatcher odtwarza kontekst i wykonuje mret."
        },
        {
          "id": "A6",
          "status": "enabled",
          "title": "STATE — PENDING, ACTIVE, DRAINED",
          "content_tex": "Po bodźcu stan jest PENDING: FIFO zawiera R, linia 16 jest aktywna, lecz globalny gate blokuje wejście. Po MIE przechodzi do ACTIVE. Odczyt DATA tworzy DRAINED: FIFO pusty, linia i pending opadają, a licznik wynosi 1."
        },
        {
          "id": "A7",
          "status": "enabled",
          "title": "RUNTIME — mcause 0x8000000b i meinext 16",
          "content_tex": "Wejście sprzętowe ma machine external interrupt cause 11, czyli \\texttt{mcause=0x8000000b}; konkretną linię 16 wybiera dopiero kontroler przez meinext. Listing ma zawierać zapis tablicy, operacje CSR, pośredni jalr i mret."
        },
        {
          "id": "A8",
          "status": "enabled",
          "title": "PATTERNS — drain level-triggered source",
          "content_tex": "Dla źródła poziomowego ISR musi usunąć warunek w peryferium, tutaj opróżnić DATA. Samo wejście do handlera nie jest acknowledge. Gdyby FIFO pozostał niepusty, linia byłaby nadal aktywna i przerwanie wróciłoby po mret."
        }
      ]
    },
    {
      "id": "task03",
      "chapter": "ISR",
      "title": "Jednokomórkowa skrzynka drop-newest",
      "idea_tex": "krótki ISR, jawne przepełnienie i konsumpcja w main",
      "priority": "kluczowe",
      "key": true,
      "prompt_tex": "Prześledź A, B i C. Dla każdego bajtu zapisz stan FIFO, \\texttt{mailbox\\_full}, decyzję ISR i późniejszy odczyt main. Wyjaśnij, dlaczego B jest odrzucone, a mimo to DATA musi zostać odczytane.",
      "criterion": "Hazard3: irq_count=3, accepted=2, dropped=1, first_consumed='A'=65, second_consumed='C'=67, mailbox_full=0, pass=1 i kod 0.",
      "evidence_tex": "Tabela trzech zdarzeń A/B/C, liczniki ISR, dwie wartości odebrane przez main, stan końcowy skrzynki oraz kod wyjścia Hazard3.",
      "worksheet_step2": "Ślad ISR dla A, B i C",
      "worksheet_step3": "Konsumpcja main, liczniki i kod wyjścia",
      "viewpoints": [
        {
          "id": "A1",
          "status": "enabled",
          "title": "CONTEXT — ISR transportuje, main konsumuje",
          "content_tex": "Handler odpowiada za szybkie opróżnienie DATA i próbę publikacji jednego bajtu. Nie interpretuje komendy. Main odpowiada za konsumpcję. Gdy skrzynka jest pełna, kontrakt jawnie odrzuca najnowszy bajt i liczy stratę."
        },
        {
          "id": "A2",
          "status": "enabled",
          "title": "STRUCTURE — payload, flaga i telemetria",
          "content_tex": "Skrzynkę tworzą \\texttt{mailbox\\_byte} i \\texttt{mailbox\\_full}. Osobne liczniki irq, accepted i dropped nie sterują algorytmem; są telemetrią dowodu. Każdy obiekt ma szerokość 32 bitów i jest volatile w tym jednordzeniowym kontrakcie bare-metal."
        },
        {
          "id": "A3",
          "status": "enabled",
          "title": "DISPATCH — ten sam IRQ, inny odbiorca",
          "content_tex": "Linia 16 przechodzi przez ten sam dispatcher co Task02, lecz wpis tablicy wskazuje \\texttt{task03\\_uart\\_handler}. Dynamiczny wybór kończy się pośrednim jalr; decyzja accepted/drop odbywa się dopiero wewnątrz handlera na podstawie danych."
        },
        {
          "id": "A4",
          "status": "enabled",
          "title": "APPLICATION — A przyjęte, B odrzucone, C przyjęte",
          "content_tex": "Po A skrzynka jest pełna i accepted=1. B wywołuje drugie IRQ, DATA zostaje opróżnione, lecz payload A pozostaje, a dropped rośnie do 1. Main pobiera A. Po C pusta skrzynka znów przyjmuje dane; main pobiera C."
        },
        {
          "id": "A5",
          "status": "enabled",
          "title": "FLOW — drain przed decyzją publish/drop",
          "content_tex": "ISR najpierw odczytuje DATA, dzięki czemu usuwa źródło poziomowe niezależnie od stanu skrzynki. Następnie zwiększa \\texttt{irq\\_count} i wybiera publikację albo drop. Main czeka na konkretną liczbę obsług, a nie na sam upływ pętli."
        },
        {
          "id": "A6",
          "status": "enabled",
          "title": "STATE — EMPTY, FULL(A), FULL(A), EMPTY, FULL(C), EMPTY",
          "content_tex": "Pełny ślad skrzynki to \\texttt{EMPTY -> FULL(A) -> FULL(A) -> EMPTY -> FULL(C) -> EMPTY}. Drugie przejście nie zmienia payloadu, ale zmienia licznik dropped; dlatego stan domenowy i telemetria muszą być czytane razem."
        },
        {
          "id": "A7",
          "status": "enabled",
          "title": "RUNTIME — trzy wejścia i trzy mret",
          "content_tex": "Checkpoint ma pokazać irq=3, accepted=2, dropped=1, 65, 67 i full=0. W listingu wskaż trzy klasy operacji: MMIO DATA, zapisy globali przez ISR oraz odtworzenie kontekstu i mret w dispatcherze."
        },
        {
          "id": "A8",
          "status": "enabled",
          "title": "PATTERNS — bounded mailbox z jawną utratą",
          "content_tex": "Jednokomórkowa skrzynka ogranicza czas i pamięć ISR. Jej ważną częścią jest polityka przeciążenia i licznik strat. Nie należy nazywać jej kolejką; nie zachowuje serii zdarzeń i nie zastępuje synchronizacji wielordzeniowej ani RTOS."
        }
      ]
    }
  ]
}