feat: add lab-rv32i-freertos-task-wrapper card

2026-07-21 19:14:20 +02:00
commit 50c425c88e
65 changed files with 33756 additions and 0 deletions
@@ -0,0 +1,80 @@
+# K07 — TaskHandle_t, explicit start and static trampoline
+
+## Position
+
+- Series: FreeRTOS C++
+- Lesson: L06, card K07
+- Duration: 30 minutes
+- One C++ owner object plus one raw verifier task
+- Dynamic FreeRTOS TCB/stack from real `heap_4.c`
+
+K02 introduced CRTP in a larger first-task experiment. K07 revisits the task
+boundary after the memory/resource cards and demands a precise identity proof:
+object, TCB/handle and task stack are separate things with separate lifetimes.
+
+## Outcome
+
+After 30 minutes the student can annotate every argument of `xTaskCreate`,
+explain why construction and start are separate, trace `void*` back to a typed
+member body, and prove stable object address without virtual dispatch.
+
+## Lesson plan — 30 minutes
+
+| Time | Mode | Evidence |
+| --- | --- | --- |
+| 0–5 | predict addresses | object vs handle/TCB vs task stack |
+| 5–10 | explicit start | constructor heap delta 0; start creates kernel objects |
+| 10–16 | C boundary | annotate entry, name, words, context, priority, handle-out |
+| 16–21 | trampoline | raw context equals object; static cast; private `run()` |
+| 21–26 | lifecycle | ready/running/completed, handle cleared, self-delete |
+| 26–30 | GDB/exit | stack local inside bounds; no move/vtable/destructor delete |
+
+## Stable identity contract
+
+```text
+object_before == object_after_start
+              == xTaskCreate context
+              == trampoline context
+              == this in run
+              == completed object
+
+handle_after_start == current handle == TCB address
+handle_after_start != C++ object address
+local variable address lies in task stack bounds
+```
+
+## Why explicit start
+
+The derived object is not complete while its base constructor runs. Starting
+there could let the scheduler enter `run()` against an incompletely constructed
+object. `start()` is a separate state transition invoked only after the complete
+owner exists. Duplicate start is rejected without another `xTaskCreate` call.
+
+## Wrapper contract
+
+- constructor stores name, stack words and priority only;
+- `start()` moves `constructed -> starting -> ready` and calls the C API;
+- static trampoline sets `running`, invokes `Derived::run()`, then records
+  `completed`, clears the handle and deletes the current kernel task;
+- copy and move are deleted because the context address must not change;
+- no destructor force-deletes a live task.
+
+## Acceptance
+
+- host test proves no constructor create call, one explicit create, stable
+  context, duplicate rejection and `start_failed` behavior;
+- ABI contains the static trampoline but no vtable/RTTI/hosted runtime;
+- Hazard3 shows object outside `ucHeap`, TCB in `ucHeap`, stack-local inside
+  reported task stack bounds;
+- counter result is 500500, wrapper ends completed with null handle;
+- all identity equalities and checkpoint 12 PASS hold.
+
+## Main traps
+
+1. `TaskHandle_t` is not the C++ object pointer; it identifies the TCB.
+2. Stack depth is in `StackType_t` words, not necessarily bytes.
+3. Moving a started wrapper invalidates the kernel's stored context.
+4. Starting in a constructor exposes a partial object.
+5. Hiding forced deletion in a destructor does not unwind arbitrary task-local
+   C++ objects and creates unsafe asynchronous lifetime coupling.
+
@@ -0,0 +1,344 @@
+% Generated from json/card_source.json by tools/render_card.py.
+% Do not edit manually; update the JSON and regenerate.
+
+\documentclass[12pt,a4paper]{article}
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage[utf8]{inputenc}
+\usepackage[polish]{babel}
+\usepackage{csquotes}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{xcolor}
+\usepackage[a4paper,left=2.15cm,right=2.15cm,top=0.5cm,bottom=0.5cm,headheight=24mm,headsep=3mm,includehead]{geometry}
+\usepackage{eso-pic}
+\usepackage{marginnote}
+\usepackage{array}
+\usepackage{tabularx}
+\usepackage{graphicx}
+\usepackage{pdflscape}
+\usepackage{float}
+\usepackage{silence}
+\WarningFilter{soulutf8}{This package is obsolete}
+\usepackage{pdfcomment}
+\usepackage{enumitem}
+\usepackage{needspace}
+\usepackage{fancyhdr}
+\usepackage{lastpage}
+\usepackage{microtype}
+\usepackage[most]{tcolorbox}
+\usepackage{qrcode}
+\IfFileExists{references.bib}{%
+  \usepackage[backend=biber,style=numeric,sorting=none]{biblatex}%
+  \addbibresource{references.bib}%
+}{}
+
+\hypersetup{hidelinks}
+
+\IfFileExists{build-meta.tex}{%
+  \input{build-meta.tex}%
+}{%
+  \newcommand{\BuildCommit}{lokalna}%
+}
+
+\newcommand{\DocumentAuthor}{M. Pabiszczak}
+\newcommand{\DocumentYear}{2026}
+\newcommand{\CardSeries}{freertos-cpp}
+\newcommand{\CardNumber}{07}
+\newcommand{\CardCount}{16}
+\newcommand{\CardSlug}{task-wrapper}
+\newcommand{\CardVersion}{v00.01}
+\newcommand{\DocumentUUID}{9bffead0-4341-4350-806d-e975b1a3a08f}
+
+\newcommand{\EmptyCheck}{\(\square\)}
+\newcommand{\EscAnswerLines}[1][3]{\par\noindent\dotfill\par\noindent\dotfill\par\noindent\dotfill}
+\newcommand{\EscWriteRow}[1][2.8em]{\rule{0pt}{#1}}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{0.45em}
+\setlength{\headheight}{24mm}
+\setlength{\headsep}{3mm}
+\setlength{\footskip}{8mm}
+\setlength{\marginparwidth}{1.5cm}
+\setlength{\marginparsep}{0.25cm}
+\renewcommand{\arraystretch}{1.22}
+% Margin separator lines disabled for layout trial.
+
+\newcommand{\ESCPageResourceHeader}{%
+  \begingroup%
+  \setlength{\parskip}{0pt}%
+  \setlength{\fboxsep}{0pt}%
+  \setlength{\fboxrule}{0.35pt}%
+  \setlength{\arrayrulewidth}{0.35pt}%
+  \noindent\fbox{%
+    \begin{minipage}[c][23.5mm][c]{\dimexpr\textwidth-2\fboxrule\relax}%
+      \begin{minipage}[c][23mm][c]{\dimexpr\linewidth-24mm-0.35pt\relax}%
+        \setlength{\tabcolsep}{0pt}%
+        \renewcommand{\arraystretch}{0}%
+        \begin{tabularx}{\linewidth}{@{}p{\dimexpr0.50000000\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.15126050\linewidth-\arrayrulewidth\relax}|X@{}}%
+          \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries TITLE}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{7.7}{7.9}\selectfont\ttfamily\bfseries TaskHandle\_t, jawny start i statyczny trampoline}\hspace{0.45mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries VER.}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{6.6}{6.8}\selectfont\ttfamily\bfseries v00.01}\hspace{0.45mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries DATETIME}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{6.4}{6.6}\selectfont\ttfamily\bfseries 2026-07-19T00:00:00+02:00}\hspace{0.45mm}}\par} \\%
+        \end{tabularx}%
+        \par\nointerlineskip%
+        \hrule height0.35pt%
+        \nointerlineskip%
+        \begin{tabularx}{\linewidth}{@{}p{\dimexpr0.50000000\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.25210084\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.14285714\linewidth-\arrayrulewidth\relax}|X@{}}%
+          \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries PROJECT}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{7.7}{7.9}\selectfont\ttfamily\bfseries Freestanding C++ nad FreeRTOS}\hspace{0.45mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries SERIES}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{6.4}{6.6}\selectfont\ttfamily\bfseries FreeRTOS C++}\hspace{0.45mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries CARD}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{6.4}{6.6}\selectfont\ttfamily\bfseries 07/16}\hspace{0.45mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{3.2}{3.4}\selectfont\ttfamily\bfseries SHEET}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{6.4}{6.6}\selectfont\ttfamily\bfseries \thepage/\pageref{LastPage}}\hspace{0.45mm}}\par} \\%
+        \end{tabularx}%
+        \par\nointerlineskip%
+        \hrule height0.35pt%
+        \nointerlineskip%
+        \begin{tabularx}{\linewidth}{@{}p{\dimexpr0.05882353\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.05042017\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.14705882\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.09243697\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.07563025\linewidth-\arrayrulewidth\relax}|p{\dimexpr0.07563025\linewidth-\arrayrulewidth\relax}|X@{}}%
+          \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries SUBJ.}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries Inf.}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries PROG.}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries —}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries CORE}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries —}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries SCOPE}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries —}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries LEVEL}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries —}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hspace{0.15mm}{\fontsize{2.85}{3}\selectfont\ttfamily\bfseries POS.}\par\nointerlineskip\vspace{0.12mm}\noindent\makebox[\linewidth][r]{{\fontsize{4.45}{4.65}\selectfont\ttfamily\bfseries —}\hspace{0.15mm}}\par} & \parbox[c][5.19414mm][c]{\linewidth}{\hbox to\linewidth{\hspace{0.35mm}{\fontsize{3.4}{3.75}\selectfont\ttfamily\bfseries GITEA UUID}\hfill{\fontsize{3.4}{3.75}\selectfont\ttfamily 9bffead0-4341-4350-806d-e975b1a3a08f}\hspace{0.35mm}}\par\nointerlineskip\hbox to\linewidth{\hspace{0.35mm}{\fontsize{3.4}{3.75}\selectfont\ttfamily\bfseries CARD UUID} {\fontsize{3.4}{3.75}\selectfont\ttfamily 9bffead0-4341-4350-806d-e975b1a3a08f}\hfill{\fontsize{3.4}{3.75}\selectfont\ttfamily\bfseries AUTHOR M. Pabiszczak}\hspace{0.35mm}}} \\%
+        \end{tabularx}%
+        \par\nointerlineskip%
+        \hrule height0.35pt%
+        \nointerlineskip%
+        \begin{tabularx}{\linewidth}{@{}X@{}}%
+          \parbox[c][3.46276mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{4.5}{4.85}\selectfont\ttfamily\bfseries GITEA} {\fontsize{4.5}{4.85}\selectfont\ttfamily\href{https://zsl-gitea.mpabi.pl/edu-freertos-cpp/lab-rv32i-freertos-task-wrapper}{\nolinkurl{https://zsl-gitea.mpabi.pl/edu-freertos-cpp/lab-rv32i-freertos-task-wrapper}}}} \\%
+        \end{tabularx}%
+        \par\nointerlineskip%
+        \hrule height0.35pt%
+        \nointerlineskip%
+        \begin{tabularx}{\linewidth}{@{}X@{}}%
+          \parbox[c][3.46276mm][c]{\linewidth}{\hspace{0.45mm}{\fontsize{4.5}{4.85}\selectfont\ttfamily\bfseries HTML} {\fontsize{4.5}{4.85}\selectfont\ttfamily\href{}{\nolinkurl{}}}} \\%
+        \end{tabularx}%
+      \end{minipage}%
+      \vrule width0.35pt%
+      \begin{minipage}[c][23mm][c]{24mm}\centering%
+        {\tiny QR wyłączony}%
+      \end{minipage}%
+    \end{minipage}%
+  }%
+  \endgroup%
+}
+
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[C]{\ESCPageResourceHeader}
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand{\footrulewidth}{0pt}
+
+\newcommand{\ESCMarginTag}[4]{%
+  \hspace*{#1}\textcolor{#2}{#3~#4}%
+}
+\newcommand{\ESCSectionBlockStart}{%
+  \Needspace{8\baselineskip}%
+  \par\vspace{0.35em}%
+  \noindent\textcolor{black!28}{\rule{\textwidth}{0.35pt}}%
+  \par\vspace{0.15em}%
+}
+\newcommand{\ESCSectionBlockEnd}{%
+  \par\vspace{0.25em}%
+  \noindent\textcolor{black!18}{\rule{\textwidth}{0.25pt}}%
+  \par\vspace{0.45em}%
+}
+\newcommand{\ESCTinyStepSeparator}{%
+  \par\vspace{0.10em}%
+  \noindent{\color{black!18}\leaders\hbox{\rule{0.60em}{0.22pt}\hspace{0.38em}}\hfill\kern0pt}%
+  \par\vspace{0.10em}%
+}
+\newtcolorbox{ESCTaskFrame}[1]{enhanced,breakable,arc=0pt,boxrule=0.35pt,colback=white,colframe=black,boxsep=0pt,left=1.4mm,right=1.4mm,top=0.8mm,bottom=0.8mm,colbacktitle=black!7,coltitle=black,title={\ttfamily\bfseries TASK\quad #1}}
+\newtcolorbox{ESCBlockFrame}[1]{enhanced,breakable,arc=0pt,boxrule=0.35pt,colback=white,colframe=black!55,boxsep=0pt,left=1.0mm,right=1.0mm,top=0.6mm,bottom=0.6mm,colbacktitle=black!4,coltitle=black,title={\ttfamily\bfseries BLOCK\quad #1}}
+\newtcolorbox{ESCStepFrame}[1]{enhanced,breakable,arc=0pt,boxrule=0.35pt,colback=white,colframe=black!28,boxsep=0pt,left=0.8mm,right=0.8mm,top=0.45mm,bottom=0.45mm,colbacktitle=black!2,coltitle=black,title={\ttfamily STEP\quad #1}}
+\newtcolorbox{ESCConclusionFrame}{enhanced,breakable,arc=0pt,boxrule=0.45pt,colback=blue!2,colframe=blue!45!black,boxsep=0pt,left=1.2mm,right=1.2mm,top=0.7mm,bottom=0.7mm,colbacktitle=blue!7,coltitle=black,title={\ttfamily\bfseries WNIOSEK}}
+
+\newcommand{\ESCLearningTreeWidget}{%
+  \reversemarginpar
+  \marginnote[%
+    \begin{minipage}{\marginparwidth}%
+    \raggedright
+    {\fontsize{3.55}{3.95}\selectfont\ttfamily
+      \begin{minipage}[t]{\marginparwidth}%
+      \raggedright
+      {\bfseries\textcolor{black!65}{TECH}\par}%
+      \vspace{0.08em}%
+      \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+      \hspace*{0.28em}\textcolor{orange!85!black}{EK~LOCAL~DBG.TASK}\textcolor{black!48}{\pdftooltip[width=\textwidth]{.01}{Śledzi obiekt, context, TCB/handle i stack przez trampoline.}}\par%
+      \hspace*{0.54em}\textcolor{blue!70!black}{KW~LOCAL~DBG.TASK}\textcolor{black!48}{\pdftooltip[width=\textwidth]{.01}{Pokazuje object equalities, handle=current=TCB, local w bounds i brak vtable.}}\par%
+      \end{minipage}%
+    }%
+    \end{minipage}%
+  ]{}
+  \normalmarginpar
+
+  \marginnote{%
+    \begin{minipage}{\marginparwidth}%
+    \raggedright
+    {\fontsize{3.55}{3.95}\selectfont\ttfamily
+    \hspace*{0.06cm}%
+      \begin{minipage}[t]{\dimexpr\marginparwidth-0.06cm\relax}%
+      \raggedright
+      {\bfseries\textcolor{black!65}{OG}\par}%
+      \vspace{0.08em}%
+      \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+      \hspace*{0.28em}\textcolor{green!50!black}{EN~LOCAL~EN~RTOS.LIFE}\textcolor{black!48}{\pdftooltip[width=\textwidth]{.01}{Analizuje explicit start, stabilny adres oraz completion/self-delete.}}\par%
+      \hspace*{0.54em}\textcolor{blue!70!black}{KW~LOCAL~KW~RTOS.LIFE}\textcolor{black!48}{\pdftooltip[width=\textwidth]{.01}{Uzasadnia brak startu w konstruktorze, copy/move i wymuszonego delete w destruktorze.}}\par%
+      \end{minipage}%
+    }%
+    \end{minipage}%
+  }
+
+}
+
+\begin{document}
+\sloppy
+
+\vspace{1.0em}
+\noindent{\Large\bfseries Cel karty}\par
+\vspace{0.35em}
+Uczeń prowadzi stabilny adres kompletnego obiektu przez xTaskCreate i statyczny trampoline do prywatnego run(), odróżniając obiekt, TCB/handle oraz task stack.
+
+\vspace{0.8em}
+\noindent\textcolor{black!25}{\rule{\textwidth}{0.35pt}}
+\vspace{0.7em}
+\noindent{\Large\bfseries Zakres karty}\par
+\vspace{0.35em}
+Konstruktor nie alokuje ani nie startuje. Wrapper jest non-copyable/non-movable, kończy body i self-delete; porównanie dynamicznego i statycznego storage należy do K08.
+
+\vspace{0.8em}
+\noindent\textcolor{black!25}{\rule{\textwidth}{0.35pt}}
+
+\clearpage
+
+\ESCSectionBlockStart
+\section{Explicit start i stany}
+\reversemarginpar
+\marginnote[%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+    \begin{minipage}[t]{\marginparwidth}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{TECH}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+]{}[-3.1em]
+\normalmarginpar
+
+\marginnote{%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+  \hspace*{0.06cm}%
+    \begin{minipage}[t]{\dimexpr\marginparwidth-0.06cm\relax}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{OG}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+}[-3.1em]
+
+
+\begingroup
+\scriptsize\ttfamily\color{black!60}\sloppy
+\noindent drzewka: \pdftooltip[width=\textwidth]{D1}{K07.WE01.OG.LOCAL.RTOS.LIFE.01 | WE 01: Explicit Task i trampoline. Zaprojektowanie jawnej,\textCR stabilnej granicy między taskiem FreeRTOS C i obiektem C++. | EN LOCAL RTOS.LIFE.01:\textCR Analizuje explicit start, stabilny adres oraz completion/self-delete. | KW LOCAL\textCR RTOS.LIFE.01: Uzasadnia brak startu w konstruktorze, copy/move i wymuszonego delete w\textCR destruktorze.}\par
+\vspace{0.10em}%
+\noindent K1: Pokaż zerowy heap delta konstruktora i zmianę przy start.\quad D1\par
+\ESCTinyStepSeparator
+\noindent K2: Odtwórz constructed--starting--ready--running--completed.\quad D1\par
+\par\vspace{0.18em}%
+\endgroup
+
+Konstruktor zapisuje konfigurację. Start dopiero po kompletnej konstrukcji tworzy TCB/stack i odrzuca duplikat.
+\ESCSectionBlockEnd
+
+\ESCSectionBlockStart
+\section{xTaskCreate i trampoline}
+\reversemarginpar
+\marginnote[%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+    \begin{minipage}[t]{\marginparwidth}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{TECH}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+]{}[-3.1em]
+\normalmarginpar
+
+\marginnote{%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+  \hspace*{0.06cm}%
+    \begin{minipage}[t]{\dimexpr\marginparwidth-0.06cm\relax}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{OG}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+}[-3.1em]
+
+
+\begingroup
+\scriptsize\ttfamily\color{black!60}\sloppy
+\noindent drzewka: \pdftooltip[width=\textwidth]{D1}{K07.WE01.TECH.LOCAL.DBG.TASK.01 | WE 01: Explicit Task i trampoline. Zaprojektowanie jawnej,\textCR stabilnej granicy między taskiem FreeRTOS C i obiektem C++. | EK LOCAL DBG.TASK.01: Śledzi\textCR obiekt, context, TCB/handle i stack przez trampoline. | KW LOCAL DBG.TASK.01: Pokazuje\textCR object equalities, handle=current=TCB, local w bounds i brak vtable.}\par
+\vspace{0.10em}%
+\noindent K1: Zapisz równość object/context/this/completed object.\quad D1\par
+\ESCTinyStepSeparator
+\noindent K2: Pokaż statyczny trampoline i brak vtable w ELF.\quad D1\par
+\par\vspace{0.18em}%
+\endgroup
+
+Rozpisz sześć argumentów C API, a następnie śledź typed object jako void* context do static trampoline i private run().
+\ESCSectionBlockEnd
+
+\ESCSectionBlockStart
+\section{TCB, handle i task stack}
+\reversemarginpar
+\marginnote[%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+    \begin{minipage}[t]{\marginparwidth}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{TECH}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+]{}[-3.1em]
+\normalmarginpar
+
+\marginnote{%
+  \begin{minipage}{\marginparwidth}%
+  \raggedright
+  {\fontsize{3.55}{3.95}\selectfont\ttfamily
+  \hspace*{0.06cm}%
+    \begin{minipage}[t]{\dimexpr\marginparwidth-0.06cm\relax}%
+    \raggedright
+    {\bfseries\textcolor{black!65}{OG}\par}%
+    \vspace{0.08em}%
+    \hspace*{0.00em}\textcolor{red}{WE~01}\textcolor{black!48}{}\par%
+    \end{minipage}%
+  }%
+  \end{minipage}%
+}[-3.1em]
+
+
+\begingroup
+\scriptsize\ttfamily\color{black!60}\sloppy
+\noindent drzewka: \pdftooltip[width=\textwidth]{D1}{K07.WE01.TECH.LOCAL.DBG.TASK.01 | WE 01: Explicit Task i trampoline. Zaprojektowanie jawnej,\textCR stabilnej granicy między taskiem FreeRTOS C i obiektem C++. | EK LOCAL DBG.TASK.01: Śledzi\textCR obiekt, context, TCB/handle i stack przez trampoline. | KW LOCAL DBG.TASK.01: Pokazuje\textCR object equalities, handle=current=TCB, local w bounds i brak vtable.}\par
+\vspace{0.10em}%
+\noindent K1: Sklasyfikuj trzy domeny adresów i jednostkę stack words.\quad D1\par
+\ESCTinyStepSeparator
+\noindent K2: Potwierdź completion, null handle, wynik 500500 i PASS.\quad D1\par
+\par\vspace{0.18em}%
+\endgroup
+
+Odróżnij aplikacyjny object address od dynamicznego TCB. Potwierdź handle=current=TCB oraz local w granicach task stack.
+\ESCSectionBlockEnd
+
+\end{document}
@@ -0,0 +1,244 @@
+\documentclass[10pt]{article}
+\usepackage[T1]{fontenc}\usepackage[utf8]{inputenc}\usepackage[polish]{babel}
+\usepackage[a4paper,margin=1.55cm]{geometry}
+\usepackage{array,tabularx,booktabs,amsmath,amssymb,xcolor,listings}
+\usepackage{hyperref,fancyhdr,lastpage,enumitem}
+\definecolor{accent}{HTML}{16324A}\definecolor{accentlight}{HTML}{EEF3F7}\definecolor{rulegray}{HTML}{D7DEE5}
+\hypersetup{colorlinks=true,linkcolor=accent,urlcolor=blue}
+\IfFileExists{build-meta.tex}{\input{build-meta.tex}}{\newcommand{\BuildCommit}{local}}
+\newcommand{\PublisherDomain}{mpabi}
+\newcommand{\CardArea}{inf}
+\newcommand{\CardSeries}{freertos-cpp}
+\newcommand{\CardNumber}{07}
+\newcommand{\CardCount}{16}
+\newcommand{\CardSlug}{task-wrapper}
+\newcommand{\CardVersion}{v00.01}
+\newcommand{\DocumentUUID}{9bffead0-4341-4350-806d-e975b1a3a08f}
+\newcommand{\blank}[1]{\rule{#1}{.2pt}}
+\lstset{language=C++,basicstyle=\ttfamily\scriptsize,columns=fullflexible,keepspaces=true,frame=single,breaklines=true,showstringspaces=false,numbers=none,backgroundcolor=\color{accentlight},rulecolor=\color{rulegray}}
+\pagestyle{fancy}\fancyhf{}
+\lhead{\textbf{K07 · FreeRTOS C++ · Task}}\rhead{\small L06 · start i trampoline}
+\lfoot{\scriptsize commit \BuildCommit}\cfoot{\scriptsize \thepage/\pageref{LastPage}}\rfoot{\scriptsize V11.3.0 / \CardVersion}
+\setlength{\headheight}{14pt}\setlength{\footskip}{19pt}
+\setlist[itemize]{nosep,leftmargin=1.45em}\setlist[enumerate]{nosep,leftmargin=1.65em}
+\begin{document}\sloppy
+
+\begin{center}
+{\LARGE\bfseries \texttt{TaskHandle\_t}, jawny \texttt{start()} i trampoline}\par
+\vspace{.25em}{\large jeden stabilny obiekt przez granicę C $\rightarrow$ C++}\par
+\end{center}
+\noindent\begin{tabularx}{\textwidth}{@{}p{1.65cm}Xp{1.55cm}X@{}}
+\toprule
+Karta & K07 / \CardCount & Czas & 30 minut \\
+Platforma & Hazard3 / RV32I & Język & freestanding C++17 \\
+Storage & dynamiczny TCB + stack & Dispatch & static CRTP trampoline \\
+Wersja & \CardVersion & UUID karty & \texttt{9bffead0-...} \\
+\bottomrule
+\end{tabularx}
+
+\section*{Trzy adresy, trzy role}
+\begin{center}
+\texttt{C++ object} $\ne$ \texttt{TaskHandle\_t/TCB} $\ne$
+\texttt{task stack storage}
+\end{center}
+
+Konstruktor zapisuje tylko konfigurację. Dopiero \texttt{start()} woła
+\texttt{xTaskCreate}, a kernel zapamiętuje adres kompletnego obiektu jako
+\texttt{void*}. Statyczny trampoline odzyskuje typ i uruchamia prywatne
+\texttt{run()} bez vtable.
+
+\noindent\fcolorbox{accent}{accentlight}{\begin{minipage}{.94\textwidth}
+\textbf{Inwariant K07.} Adres obiektu od startu do końca taska jest stały.
+Wrapper nie jest kopiowalny ani przenoszalny. Handle identyfikuje TCB, a nie
+obiekt aplikacyjny. Destruktor nie wykonuje wymuszonego delete taska.
+\end{minipage}}
+
+\section*{Plan 30 minut}
+\noindent\begin{tabularx}{\textwidth}{@{}p{1.35cm}p{3cm}X@{}}
+\toprule
+Czas & Tryb & Dowód \\
+\midrule
+0--5 & adresy & object, TCB/handle i stack to różne rzeczy \\
+5--10 & explicit start & konstruktor heap delta 0; start tworzy kernel storage \\
+10--16 & C API & sześć argumentów xTaskCreate \\
+16--21 & trampoline & raw context = object = this in run \\
+21--26 & lifecycle & ready, running, completed, null handle, self-delete \\
+26--30 & GDB/exit & local na task stack; bez move/vtable/destructor-delete \\
+\bottomrule
+\end{tabularx}
+
+\section*{Predykcja}
+Który adres znajdzie się w \texttt{TaskHandle\_t}: obiekt czy TCB?
+\blank{4cm}\quad Czy konstruktor może uruchomić task? \blank{4cm}
+
+\newpage
+\section{Dlaczego start nie należy do konstruktora}
+
+W czasie konstruktora bazowego część derived nie jest jeszcze kompletna.
+Scheduler mógłby wywołać \texttt{run()} natychmiast po create. Dlatego:
+
+\begin{lstlisting}
+CounterTask worker;       // tylko konfiguracja, heap bez zmian
+bool ok = worker.start(); // dopiero teraz xTaskCreate
+\end{lstlisting}
+
+\noindent\begin{tabularx}{\textwidth}{@{}p{4.4cm}X@{}}
+\toprule
+Stan wrappera & Znaczenie \\
+\midrule
+\texttt{constructed} & kompletny obiekt, brak taska kernela \\
+\texttt{starting} & wejście do jawnej operacji start \\
+\texttt{ready} & context i konfiguracja przekazywane do kernela \\
+\texttt{running} & trampoline odzyskał typed object \\
+\texttt{completed} & member body wrócił, handle wyzerowany \\
+\texttt{start\_failed} & create nie utworzył taska; handle null \\
+\bottomrule
+\end{tabularx}
+
+Drugie \texttt{start()} musi zwrócić \blank{2cm}, wykonać
+\blank{2cm} nowych \texttt{xTaskCreate} i pozostawić handle
+\blank{5cm}.
+
+\section{Rozpisz sześć argumentów \texttt{xTaskCreate}}
+
+\begin{lstlisting}
+xTaskCreate(&Task::trampoline,
+            name_, stack_words_,
+            static_cast<Derived*>(this),
+            priority_, &handle_);
+\end{lstlisting}
+
+\noindent\begin{tabularx}{\textwidth}{@{}p{5.5cm}X@{}}
+\toprule
+Argument & Co niesie / jednostka \\
+\midrule
+\texttt{\&Task::trampoline} & \blank{10cm} \\
+\texttt{name\_} & \blank{10cm} \\
+\texttt{stack\_words\_} & \blank{10cm} \\
+typed context: \texttt{Derived*} z \texttt{this} & \blank{9cm} \\
+\texttt{priority\_} & \blank{10cm} \\
+\texttt{\&handle\_} & \blank{10cm} \\
+\bottomrule
+\end{tabularx}
+
+\textbf{Pułapka jednostki:} stack depth jest liczbą \texttt{StackType\_t}, nie
+domyślnie bajtów. Dla RV32I 256 słów to \blank{2cm} B.
+
+\newpage
+\section{Trampoline odzyskuje typ, nie tworzy obiektu}
+
+\begin{lstlisting}
+static void trampoline(void* context) {
+    Derived* derived = static_cast<Derived*>(context);
+    Task& base = *static_cast<Task*>(derived);
+    base.state_ = TaskState::running;
+    derived->run();
+    base.state_ = TaskState::completed;
+    base.handle_ = nullptr;
+    vTaskDelete(nullptr);
+}
+\end{lstlisting}
+
+Nie ma \texttt{new}, lookupu ani vtable. Context jest adresem istniejącego,
+kompletnego obiektu. Prywatny \texttt{run()} jest dostępny dzięki jawnej relacji
+\texttt{friend} z konkretną instancją CRTP.
+
+\section*{Trzy domeny adresów}
+\noindent\begin{tabularx}{\textwidth}{@{}XXX@{}}
+\toprule
+Tożsamość obiektu C++ & Tożsamość TCB & Task stack \\
+\midrule
+before start: \blank{3.1cm} & handle after start: \blank{3cm} & low: \blank{3cm} \\
+after start: \blank{3.1cm} & current handle: \blank{3cm} & high: \blank{3cm} \\
+trampoline context: \blank{3.1cm} & status TCB: \blank{3cm} & local: \blank{3cm} \\
+\texttt{this} in run: \blank{3.1cm} & & watermark: \blank{3cm} \\
+completed object: \blank{3.1cm} & & \\
+\bottomrule
+\end{tabularx}
+
+\begin{center}
+\texttt{object identities equal}\qquad
+\texttt{handle == current == TCB}\qquad
+\texttt{low <= local <= high}
+\end{center}
+
+\section*{Maszyna stanów wrappera}
+\begin{center}
+\texttt{constructed -> starting -> ready -> running -> completed}\\[.5em]
+\texttt{constructed -> starting -> ready -> start\_failed} (gdy create fail)
+\end{center}
+
+Dlaczego stan \texttt{ready} jest ustawiany przed wejściem do
+\texttt{xTaskCreate}? Przy aktywnym schedulerze nowy task może wykonać się, a
+nawet zakończyć, zanim wywołanie create zwróci do startera. Kod po powrocie nie
+może nadpisać \texttt{completed} ponownie stanem \texttt{ready}.
+
+\section*{Predykcja duplikatu}
+Drugie \texttt{start()} na tym samym obiekcie powinno:
+\begin{itemize}
+  \item zwrócić \blank{2cm};
+  \item wywołać \texttt{xTaskCreate} jeszcze raz? \blank{2cm};
+  \item zmienić handle? \blank{2cm};
+  \item pozostawić stan: \blank{3cm}.
+\end{itemize}
+
+\section*{Granica destruktora}
+Destruktor obiektu na innym stosie nie może bezpiecznie „sprzątnąć” dowolnego
+żywego taska: wymuszone \texttt{vTaskDelete(handle)} nie odwija jego ramek C++.
+K07 kończy body normalnie i dopiero trampoline usuwa bieżący task.
+
+\newpage
+\section{Hazard3/GDB i kontrakt zaliczenia}
+\begin{lstlisting}[language=bash]
+make check
+riscv64-unknown-elf-gdb build/task01_task_wrapper/prog.elf
+b explicit_task_debug_checkpoint
+\end{lstlisting}
+\begin{lstlisting}
+p g_checkpoint_trace
+p/x g_object_before_start
+p/x g_trampoline_context
+p/x g_run_this
+p/x g_handle_after_start
+p/x g_tcb_address
+p/x g_stack_low
+p/x g_stack_high
+p/x g_stack_local
+p g_counter_result
+p g_task_wrapper_pass
+\end{lstlisting}
+
+\noindent\begin{tabularx}{\textwidth}{@{}p{1cm}p{3.8cm}X@{}}
+\toprule
+STOP & Stan & Obowiązkowy dowód \\
+\midrule
+1 & constructed & heap konstrukcji bez zmian, handle null \\
+2--3 & start & starting/ready, context wskazuje pełny obiekt \\
+4 & create returned & handle wskazuje TCB w ucHeap \\
+5 & before scheduler & object address nadal ten sam \\
+6--7 & trampoline & context odzyskany, state running \\
+8 & private run & handle/current/TCB równe; local w stack; wynik 500500 \\
+10 & completion & state completed; handle null; self-delete \\
+11--12 & verifier & wszystkie relacje i pass=1 \\
+\bottomrule
+\end{tabularx}
+
+\section*{Zaliczenie}
+\begin{itemize}
+  \item $\square$ odróżniam object, handle/TCB i task stack;
+  \item $\square$ pokazuję zerowy heap delta konstruktora i jawny create;
+  \item $\square$ opisuję sześć argumentów \texttt{xTaskCreate};
+  \item $\square$ śledzę ten sam context przez trampoline do \texttt{run()};
+  \item $\square$ pokazuję local w stack bounds oraz wynik 500500;
+  \item $\square$ uzasadniam brak copy/move, vtable i delete w destruktorze.
+\end{itemize}
+
+\section*{Wyjście}
+Dlaczego handle nie może być użyty jako adres obiektu aplikacyjnego?\\[.4em]
+\blank{12cm}\\[1em]
+Co chroni jawny \texttt{start()}?\\[.4em]\blank{11cm}
+
+\vfill
+\noindent\textbf{Następna karta K08:} dynamiczny i statyczny TCB/stack,
+słowa kontra bajty, jawne zakończenie i czas odzyskania pamięci.
+\end{document}