diff --git a/README.md b/README.md index dbc55ea..f0a6ee7 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,12 @@ Publiczny manifest wspólnego workspace EDU. Repo opisuje serie i karty pracy dostępne dla `stemctl`. Nie przechowuje tokenów, lokalnych ścieżek użytkownika ani plików roboczych ucznia. +Widoczność karty w katalogu nie jest uprawnieniem do jej wykonania. W +zarządzanej usłudze nauczyciel uruchamia kartę przez `teactl`, a `stemctl` +ucznia może otworzyć i wykonać tylko wersję wskazaną bieżącym +`CardRunGrant`. Bezpośrednie przeglądanie katalogu pozostaje funkcją +developerską i standalone. + `workspace.json.series` zawiera wyłącznie aktywne serie obsługiwane przez `stemctl`. `workspace.json.catalog_subjects` zasila drzewo UI także seriami planowanymi, ale nie udostępnia ich poleceniom pobierania. Pozycję można dodać diff --git a/catalog/freertos-c.json b/catalog/freertos-c.json index 8aaaeb2..db50423 100644 --- a/catalog/freertos-c.json +++ b/catalog/freertos-c.json @@ -3,7 +3,7 @@ "title": "FreeRTOS C", "catalog_only": true, "cards": [ - {"id": "FC01", "repo": "lab-rv32i-freertos-heap4", "number": "01", "title": "heap_1–heap_5 and heap_4 mechanics", "status": "existing"}, + {"id": "FC01", "repo": "lab-rv32i-freertos-heap4", "number": "01", "title": "heap_4: From Linear Cursor to Reusable Blocks", "status": "existing"}, {"id": "FC02", "repo": "lab-rv32i-freertos-c-first-task", "number": "02", "title": "First Task, TCB and Task Stack", "status": "existing"}, {"id": "FC03", "repo": "lab-rv32i-freertos-c-scheduler", "number": "03", "title": "Tick, Scheduler, Priorities and Time Slicing", "status": "existing"}, {"id": "FC04", "repo": "lab-rv32i-freertos-c-delay-state", "number": "04", "title": "Delay, Blocking and Task States", "status": "existing"}, @@ -14,9 +14,9 @@ {"id": "FC09", "repo": "lab-rv32i-freertos-c-event-groups", "number": "09", "title": "Event Groups and Multi-event Synchronization", "status": "existing"}, {"id": "FC10", "repo": "lab-rv32i-freertos-c-notifications", "number": "10", "title": "Direct-to-task Notifications", "status": "existing"}, {"id": "FC11", "repo": "lab-rv32i-freertos-c-static-allocation", "number": "11", "title": "Static Allocation and Bounded Storage", "status": "existing"}, - {"id": "FC12", "repo": "lab-rv32i-freertos-c-diagnostics", "number": "12", "title": "Assertions, Hooks, Stack Checks and Runtime Diagnostics", "status": "planned"}, - {"id": "FC13", "repo": "lab-rv32i-freertos-c-uart", "number": "13", "title": "UART Interrupt-to-task Pipeline", "status": "planned"}, - {"id": "FC14", "repo": "lab-rv32i-freertos-c-gpio-timer", "number": "14", "title": "GPIO, Hardware Timer and Deferred Work", "status": "planned"}, - {"id": "FC15", "repo": "lab-rv32i-freertos-c-integration", "number": "15", "title": "Integrated Deterministic FreeRTOS C Application", "status": "planned"} + {"id": "FC12", "repo": "lab-rv32i-freertos-c-diagnostics", "number": "12", "title": "Assertions, Hooks, Stack Checks and Runtime Diagnostics", "status": "existing"}, + {"id": "FC13", "repo": "lab-rv32i-freertos-c-uart", "number": "13", "title": "UART Interrupt-to-task Pipeline", "status": "existing"}, + {"id": "FC14", "repo": "lab-rv32i-freertos-c-gpio-timer", "number": "14", "title": "GPIO, Hardware Timer and Deferred Work", "status": "existing"}, + {"id": "FC15", "repo": "lab-rv32i-freertos-c-integration", "number": "15", "title": "Integrated Deterministic FreeRTOS C Application", "status": "existing"} ] } diff --git a/catalog/freertos-cpp.json b/catalog/freertos-cpp.json index 09888fb..ab965d6 100644 --- a/catalog/freertos-cpp.json +++ b/catalog/freertos-cpp.json @@ -3,20 +3,20 @@ "title": "FreeRTOS C++", "catalog_only": true, "cards": [ - {"id": "K02", "repo": "lab-rv32i-freertos-task-stack-vector", "number": "02", "title": "First Task, Stack, Tick, Scheduler and Vector V0", "status": "existing"}, - {"id": "K03", "repo": "lab-rv32i-freertos-vector-raii", "number": "03", "title": "Vector V1 — Destructor, Move, Ownership and RAII", "status": "planned"}, - {"id": "K04", "repo": "lab-rv32i-freertos-scheduler-states", "number": "04", "title": "Scheduler States, Priorities and Typed Ticks", "status": "planned"}, - {"id": "K05", "repo": "lab-rv32i-freertos-heap-models", "number": "05", "title": "C++ Heap Bridge, Heap Models and HeapStats", "status": "planned"}, - {"id": "K06", "repo": "lab-rv32i-freertos-allocator-resource", "number": "06", "title": "MemoryResource and FreeRtosAllocator", "status": "planned"}, - {"id": "K07", "repo": "lab-rv32i-freertos-task-wrapper", "number": "07", "title": "TaskHandle_t, Explicit Start and Static Trampoline", "status": "planned"}, - {"id": "K08", "repo": "lab-rv32i-freertos-static-task", "number": "08", "title": "DynamicTask, StaticTask, Deletion and Lifetime", "status": "planned"}, - {"id": "K09", "repo": "lab-rv32i-freertos-kernel-facade", "number": "09", "title": "Scheduler Facade and Scoped Kernel Guards", "status": "planned"}, - {"id": "K10", "repo": "lab-rv32i-freertos-queue", "number": "10", "title": "Queue and StaticQueue", "status": "planned"}, - {"id": "K11", "repo": "lab-rv32i-freertos-mutex", "number": "11", "title": "Mutex, LockGuard and Priority Inheritance", "status": "planned"}, - {"id": "K12", "repo": "lab-rv32i-freertos-semaphore-notify", "number": "12", "title": "Semaphores and Task Notifications", "status": "planned"}, - {"id": "K13", "repo": "lab-rv32i-freertos-event-group", "number": "13", "title": "EventGroup and Coordinated State", "status": "planned"}, - {"id": "K14", "repo": "lab-rv32i-freertos-sw-timer", "number": "14", "title": "Software Timer and the Timer Daemon Task", "status": "planned"}, - {"id": "K15", "repo": "lab-rv32i-freertos-isr-drivers", "number": "15", "title": "Explicit FromISR, UART and GPIO Wrappers", "status": "planned"}, - {"id": "K16", "repo": "lab-rv32i-freertos-integration", "number": "16", "title": "Integrated Real-time Application and Evidence", "status": "planned"} + {"id": "K02", "repo": "lab-rv32i-freertos-task-stack-vector", "number": "02", "title": "C++ Task Wrapper, CRTP and Lifecycle", "status": "existing"}, + {"id": "K03", "repo": "lab-rv32i-freertos-vector-raii", "number": "03", "title": "Vector V1 — Destructor, Move, Ownership and RAII", "status": "existing"}, + {"id": "K04", "repo": "lab-rv32i-freertos-scheduler-states", "number": "04", "title": "Scheduler States, Priorities and Typed Ticks", "status": "existing"}, + {"id": "K05", "repo": "lab-rv32i-freertos-heap-models", "number": "05", "title": "C++ Heap Bridge, Heap Models and HeapStats", "status": "existing"}, + {"id": "K06", "repo": "lab-rv32i-freertos-allocator-resource", "number": "06", "title": "MemoryResource and FreeRtosAllocator", "status": "existing"}, + {"id": "K07", "repo": "lab-rv32i-freertos-task-wrapper", "number": "07", "title": "TaskHandle_t, Explicit Start and Static Trampoline", "status": "existing"}, + {"id": "K08", "repo": "lab-rv32i-freertos-static-task", "number": "08", "title": "DynamicTask, StaticTask, Deletion and Lifetime", "status": "existing"}, + {"id": "K09", "repo": "lab-rv32i-freertos-kernel-facade", "number": "09", "title": "Scheduler Facade and Scoped Kernel Guards", "status": "existing"}, + {"id": "K10", "repo": "lab-rv32i-freertos-queue", "number": "10", "title": "Queue and StaticQueue", "status": "existing"}, + {"id": "K11", "repo": "lab-rv32i-freertos-mutex", "number": "11", "title": "Mutex, LockGuard and Priority Inheritance", "status": "existing"}, + {"id": "K12", "repo": "lab-rv32i-freertos-semaphore-notify", "number": "12", "title": "Semaphores and Task Notifications", "status": "existing"}, + {"id": "K13", "repo": "lab-rv32i-freertos-event-group", "number": "13", "title": "EventGroup and Coordinated State", "status": "existing"}, + {"id": "K14", "repo": "lab-rv32i-freertos-sw-timer", "number": "14", "title": "Software Timer and the Timer Daemon Task", "status": "existing"}, + {"id": "K15", "repo": "lab-rv32i-freertos-isr-drivers", "number": "15", "title": "Explicit FromISR, UART and GPIO Wrappers", "status": "existing"}, + {"id": "K16", "repo": "lab-rv32i-freertos-integration", "number": "16", "title": "Integrated Real-time Application and Evidence", "status": "existing"} ] } diff --git a/plans/informatyka/c.md b/plans/informatyka/c.md index d973557..316ecbf 100644 --- a/plans/informatyka/c.md +++ b/plans/informatyka/c.md @@ -1,6 +1,6 @@ # C — Freestanding RV32I and K&R -Status: 8 kart istniejących lub rozpoczętych, 5 planowanych. +Status: C01–C13 gotowe; seria C zakończona przed rozpoczęciem serii C++. ```text C · Freestanding RV32I and K&R @@ -23,5 +23,62 @@ RV32I ASM jest osobną serią-prerekwizytem. C01–C03 tworzą przejście z freestanding assemblera do środowiska C, ale pozostają kartami serii C, ponieważ ich wynikiem jest rozumienie uruchomienia i ABI programu C. +## Układ każdego przykładu: A1–A8 + +Każdy przykład źródłowy w karcie serii C jest osobnym taskiem i jawnie +odpowiada na komplet pytań A1–A8: + +```text +A1 CONTEXT granica systemu i odpowiedzialność przykładu +A2 STRUCTURE typy, obiekty, reprezentacja i ownership +A3 DISPATCH granica wywołania, callbacku albo ISR +A4 APPLICATION konkretne funkcje, dane i inwariant przykładu +A5 FLOW kolejność wykonania oraz checkpointy +A6 STATE stan, lifetime i przejścia wartości +A7 RUNTIME ABI, rejestry, adresy, sekcje ELF i wynik pomiaru +A8 PATTERNS nazwana, rzeczywiście wielokrotnego użytku decyzja +``` + +A1–A8 jest profilem pytań, a nie nakazem tworzenia ośmiu dekoracyjnych +diagramów. Każda pozycja ma status `enabled` albo `unavailable`. Widok +`enabled` musi wnosić odrębny dowód; `unavailable` zawiera konkretny powód. +Wartościowy opis tekstowy jest pełnoprawnym widokiem. Diagram powstaje tylko +wtedy, gdy relacja, kolejność lub stan są mniej czytelne w krótkim tekście. + +Dla C04–C06 nowe źródło JSON, TeX, HTML i nowy PDF są dodawane obok +historycznych kart. Oryginalne `doc/main.tex`, PDF-y oraz przykłady w +`src/tasks/` pozostają niezmienionym materiałem referencyjnym. + Pełne cele C10–C13 i granica roku znajdują się w `series/inf/lab-rv32i-c-pointers-arrays/guidelines/year-01-interrupts-to-year-02-freertos.md`. + +## Stan odbioru serii C — 2026-07-20 + +Każda karta ma wygenerowane źródło JSON, widok web i nowy PDF. Odbiór +potwierdza dokładną kolejność A1–A8 w każdym tasku, jawne uzasadnienie każdego +N/D, poprawny JSON i JavaScript, poprawność PDF według `qpdf` oraz brak pustych, +anonimowych i przepełnionych stron. Przykłady uruchamialne przeszły właściwe +testy hostowe i/lub wyrocznie Hazard3. + +```text +karta przykłady bloki A1–A8 +C01 3 24 +C02 4 32 +C03 2 16 +C04 12 96 +C05 8 64 +C06 11 88 +C07 12 96 +C08 4 32 +C09 5 40 +C10 3 24 +C11 3 24 +C12 3 24 +C13 4 32 +RAZEM 74 592 +``` + +PDF-y mają łącznie 180 stron. Spośród 592 widoków 508 ma stan `enabled`, a 84 +ma stan `unavailable` z konkretnym powodem. Historyczne źródła C04–C06 nadal są +materiałem referencyjnym: nowy układ nie nadpisuje `doc/main.tex`, starych +PDF-ów ani przykładów w `src/tasks/`. diff --git a/plans/informatyka/freertos-c.md b/plans/informatyka/freertos-c.md index f346472..b0c8dd2 100644 --- a/plans/informatyka/freertos-c.md +++ b/plans/informatyka/freertos-c.md @@ -1,8 +1,8 @@ # FreeRTOS C — book-led card sequence -Status: FC01–FC02 exist; FC03 is the next implementation; FC04–FC15 are -planned. This series uses only the FreeRTOS C API. C++ wrappers belong to a -later, separate series. +Status: FC01–FC15 istnieją; blok 15 kart FreeRTOS C jest kompletny i stanowi +zamknięty fundament przed serią FreeRTOS C++. Każda karta używa publicznego +API C, a końcowa FC15 scala mechanizmy w jeden deterministyczny eksperyment. ## Primary source and ordering rule @@ -62,7 +62,7 @@ simulator. ```text FreeRTOS C — 15 cards -├── FC01 · Heap schemes and heap_4 block mechanics +├── FC01 · heap_4: from a linear cursor to reusable blocks ├── FC02 · First task, typed context, TCB and task stack ├── FC03 · Tick, priorities, preemption and time slicing ├── FC04 · Delay, blocking, task states and deletion @@ -79,22 +79,37 @@ FreeRTOS C — 15 cards └── FC15 · Integrated deterministic FreeRTOS C application ``` -## FC01 — Heap schemes and heap_4 block mechanics +## FC01 — `heap_4`: from a linear cursor to reusable blocks -**Book basis:** 3.1–3.4: `heap_1`–`heap_5`, heap utilities, allocation -failure and static allocation introduction. +**Duration:** one 30-minute lesson. +**Direct predecessor:** C07, K&R 5.4 Task04 — `allocbuf[64]`, `allocp`, +`alloc(5)`, `alloc(7)` and cursor offsets `0 -> 5 -> 12`. + +**Book basis:** the `heap_4` and heap-statistics parts of Chapter 3. The other +FreeRTOS heap implementations are a one-minute map of alternatives, not +parallel lesson content. + +- Opening problem: the linear project cannot release the first 5-byte area + while preserving the later 7-byte area, cannot remember reusable holes and + recovers the arena only with a whole-arena reset. +- New model: a block header, an address-ordered free list, first-fit selection, + splitting and coalescing of physically adjacent free blocks. - Raw API: `pvPortMalloc`, `vPortFree`, `xPortGetFreeHeapSize`, `xPortGetMinimumEverFreeHeapSize`, `vPortGetHeapStats`. -- Main task: compare allocator policies, then walk allocation, split, free - and coalescing in `heap_4`. -- Blocks: A1 allocator boundary; A2 block/list layout; A5 allocation flow; - A6 free/allocated block state; A7 heap addresses and statistics. -- Exercise: predict the free-list shape for a new allocate/free order. -- Hazard3/GDB proof: block headers, aligned sizes and coalesced neighbors - agree with the final heap statistics. -- Main pitfall: treating the minimum-ever-free value as current free space or - assuming all heap implementations support free/coalescing. +- Task 1 and Task 2 are short teacher-led models with a student prediction; + they are not separate build/debug sessions during the lesson. +- Task 3 is the only central student replay: real upstream `heap_4.c`, two + stable checkpoints, fragmentation metrics, recovery and OOM. +- Pico 2 W supplies one prebuilt RP2350 hardware observation. `heap_4` is the + allocator selected and linked by the project, not a hardware feature of the + microcontroller. +- Acceptance: the student names the three additions over the linear allocator + (header, free list, coalescing), predicts `2 free blocks -> 1 free block`, + and distinguishes current free bytes, largest free block and minimum-ever + free bytes. +- Main pitfall: assuming that a large sum of free bytes guarantees one large + allocation, or that minimum-ever-free increases after `free`. ## FC02 — First task, typed context, TCB and task stack @@ -367,10 +382,12 @@ Every new card must contain: 8. HTML and TeX generated from one `card_source.json`; 9. no PDF generation and no commit unless explicitly requested. -## Implementation order +## Completed implementation order ```text -FC03 scheduler +FC01 heap_4 +→ FC02 first task +→ FC03 scheduler → FC04 state/delay → FC05 queues → FC06 software timers @@ -385,5 +402,7 @@ FC03 scheduler → FC15 integration ``` -Ukończenie FC15 jest pierwszą z dwóch bramek wejścia do FreeRTOS C++; drugą -jest ukończenie właściwych kart językowych C++/OOP. +Obie bramki wejścia do FreeRTOS C++ są spełnione: FC15 zamyka tor systemowy C, +a właściwe karty językowe C++/OOP dostarczają model własności, RAII, szablony i +statyczne trampoline. Następnym etapem jest audyt i realizacja serii FreeRTOS +C++ karta po karcie, bez mieszania wrapperów z implementacją kernela w C. diff --git a/plans/informatyka/freertos-cpp.md b/plans/informatyka/freertos-cpp.md index 8d27c60..8280e02 100644 --- a/plans/informatyka/freertos-cpp.md +++ b/plans/informatyka/freertos-cpp.md @@ -1,14 +1,18 @@ # FreeRTOS C++ — plan kart -Status: K02 istnieje i jest bieżącą kartą; K03–K16 są planem. +Status: K02–K16 są gotowe; blok 15 kart jest kompletny. Każda karta ma +freestanding build C++17, test hosta, kontrolę ABI, wykonanie na Hazard3 oraz +sprawdzony PDF. Źródła i artefakty używają wspólnej numeracji Kxx/16. Karta `heap_4` należy do serii FreeRTOS C. FreeRTOS C++ zaczyna się dopiero po ukończeniu dwóch torów prowadzonych równolegle: FreeRTOS C oraz C++. K02 -porównuje znany już surowy task C z freestanding wrapperem C++ i Vector V0. +wprowadza freestanding wrapper `Task`, CRTP i statyczny trampoline. +K03 pokazuje krótki, celowo niepełny Vector V0 bez ukrytego wymagania wykonania +osobnej karty, a następnie buduje z niego move-only Vector V1 z RAII. ```text FreeRTOS C++ -├── K02 · First Task, Stack, Tick, Scheduler and Vector V0 +├── K02 · C++ Task Wrapper, CRTP and Lifecycle ├── K03 · Vector V1 — Destructor, Move, Ownership and RAII ├── K04 · Scheduler States, Priorities and Typed Ticks ├── K05 · C++ Heap Bridge, Heap Models and HeapStats @@ -32,7 +36,7 @@ freestanding, bez wyjątków, RTTI i zależności od hosted `libstdc++`. Każda karta linkuje również do osobnej serii OOP, gdy wrapper rzeczywiście realizuje wzorzec lub idiom wymagający osobnego omówienia. -Szczegółowy plan bieżącej K02 oraz kontrolowane porównanie z FC02: +Materiały wejściowe K02 oraz kontrolowane porównanie z FC02: - [K02 Task01 — A1–A8 plan](../../../../series/freertos/lab-rv32i-freertos-task-stack-vector/doc/task01-a1-a8-plan.md) - [FC02/K02 — paired first-task experiment](freertos-first-task-a1-a8.md) diff --git a/series/freertos-c.json b/series/freertos-c.json index 54ef038..44ae190 100644 --- a/series/freertos-c.json +++ b/series/freertos-c.json @@ -14,7 +14,7 @@ "id": "FC01", "repo": "lab-rv32i-freertos-heap4", "branch": "main", - "title": "heap_1–heap_5 and heap_4 mechanics" + "title": "heap_4: From Linear Cursor to Reusable Blocks" }, { "id": "FC02", @@ -75,6 +75,30 @@ "repo": "lab-rv32i-freertos-c-static-allocation", "branch": "main", "title": "Static Allocation and Bounded Storage" + }, + { + "id": "FC12", + "repo": "lab-rv32i-freertos-c-diagnostics", + "branch": "main", + "title": "Assertions, Hooks, Stack Checks and Runtime Diagnostics" + }, + { + "id": "FC13", + "repo": "lab-rv32i-freertos-c-uart", + "branch": "main", + "title": "UART Interrupt-to-task Pipeline" + }, + { + "id": "FC14", + "repo": "lab-rv32i-freertos-c-gpio-timer", + "branch": "main", + "title": "GPIO, Hardware Timer and Deferred Work" + }, + { + "id": "FC15", + "repo": "lab-rv32i-freertos-c-integration", + "branch": "main", + "title": "Integrated Deterministic FreeRTOS C Application" } ] } diff --git a/series/freertos-cpp.json b/series/freertos-cpp.json index cffa8c7..be6f88b 100644 --- a/series/freertos-cpp.json +++ b/series/freertos-cpp.json @@ -15,6 +15,90 @@ "repo": "lab-rv32i-freertos-task-stack-vector", "branch": "main", "title": "C++ Task wrapper: OOP and lifecycle" + }, + { + "id": "K03", + "repo": "lab-rv32i-freertos-vector-raii", + "branch": "main", + "title": "Vector V1: destructor, move, ownership and RAII" + }, + { + "id": "K04", + "repo": "lab-rv32i-freertos-scheduler-states", + "branch": "main", + "title": "Scheduler states, priorities and typed ticks" + }, + { + "id": "K05", + "repo": "lab-rv32i-freertos-heap-models", + "branch": "main", + "title": "C++ heap bridge, heap models and HeapStats" + }, + { + "id": "K06", + "repo": "lab-rv32i-freertos-allocator-resource", + "branch": "main", + "title": "MemoryResource and FreeRtosAllocator" + }, + { + "id": "K07", + "repo": "lab-rv32i-freertos-task-wrapper", + "branch": "main", + "title": "TaskHandle_t, explicit start and static trampoline" + }, + { + "id": "K08", + "repo": "lab-rv32i-freertos-static-task", + "branch": "main", + "title": "DynamicTask, StaticTask, deletion and lifetime" + }, + { + "id": "K09", + "repo": "lab-rv32i-freertos-kernel-facade", + "branch": "main", + "title": "Scheduler facade and scoped kernel guards" + }, + { + "id": "K10", + "repo": "lab-rv32i-freertos-queue", + "branch": "main", + "title": "Queue and StaticQueue" + }, + { + "id": "K11", + "repo": "lab-rv32i-freertos-mutex", + "branch": "main", + "title": "Mutex, LockGuard and priority inheritance" + }, + { + "id": "K12", + "repo": "lab-rv32i-freertos-semaphore-notify", + "branch": "main", + "title": "Semaphores and task notifications" + }, + { + "id": "K13", + "repo": "lab-rv32i-freertos-event-group", + "branch": "main", + "title": "EventGroup and coordinated state" + }, + { + "id": "K14", + "repo": "lab-rv32i-freertos-sw-timer", + "branch": "main", + "title": "Software timer and the timer daemon task" + }, + { + "id": "K15", + "repo": "lab-rv32i-freertos-isr-drivers", + "branch": "main", + "title": "Explicit FromISR, UART and GPIO wrappers" + }, + { + "id": "K16", + "repo": "lab-rv32i-freertos-integration", + "branch": "main", + "title": "Integrated real-time application and evidence" } ] }