lab-rv32i-freertos-semaphore-notify/doc/main.tex

\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,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}{12}
\newcommand{\CardCount}{16}
\newcommand{\CardSlug}{semaphore-notify}
\newcommand{\CardVersion}{v00.01}
\newcommand{\DocumentUUID}{fcb6107c-268f-4e86-a8cc-092e5875f6f0}
\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{K12 · FreeRTOS C++ · sync}}\rhead{\small L11 · semaphore vs TCB notify}
\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 Semafory i task notifications}\par
\vspace{.25em}{\large sygnał 0/1, licznik slotów i kanał jednego TCB}\par
\end{center}
\noindent\begin{tabularx}{\textwidth}{@{}p{1.65cm}Xp{1.75cm}X@{}}
\toprule
Karta & K12 / \CardCount & Czas & 30 minut \\
Platforma & Hazard3 / RV32I & Taski & waiter 3 / signaler 2 \\
Storage & static controls + TCB & Heap delta & 0 B \\
Wersja & \CardVersion & UUID karty & \texttt{fcb6107c-...} \\
\bottomrule
\end{tabularx}

\section*{Trzy podobne wakeupy, trzy różne kontrakty}
\noindent\begin{tabularx}{\textwidth}{@{}p{3.6cm}p{3.2cm}p{3.6cm}X@{}}
\toprule Typ & Stan & Odbiorcy & Payload \\
\midrule
Binary semaphore & 0 lub 1 & waiter obiektu & brak \\
Counting semaphore & 0..Max & waiterzy obiektu & count zasobu \\
Task notification & value/state w TCB & jeden task/slot & value lub bits \\
\bottomrule
\end{tabularx}

\noindent\fcolorbox{accent}{accentlight}{\begin{minipage}{.94\textwidth}
\textbf{Kontrakt K12.} Semaphore nie jest magazynem danych. Notification jest
adresowana do konkretnego taska, a action oraz clear/decrement policy są częścią
typu operacji, nie szczegółem do domyślenia.
\end{minipage}}

\section*{Plan 30 minut}
\noindent\begin{tabularx}{\textwidth}{@{}p{1.35cm}p{3.1cm}X@{}}
\toprule Czas & Tryb & Dowód \\
\midrule
0--5 & binary & 0--1--0; drugi give przy full=false \\
5--10 & counting & initial/max 2; take 2--1--0 \\
10--15 & block & trzeci take: waiter eBlocked \\
15--20 & release & jeden give budzi; token od razu zużyty \\
20--25 & notify count & TCB give/take zwraca 1 \\
25--30 & notify value & overwrite/wait daje 0xA5A55A5A \\
\bottomrule
\end{tabularx}

\section*{Wybór}
Jeden producent budzi jeden znany task bez payloadu: \blank{4cm}. Trzech
workerów konkuruje o dwa sloty: \blank{4cm}.

\newpage
\section{Binary i counting: granice count}

\noindent\begin{tabularx}{\textwidth}{@{}p{4.6cm}p{3.4cm}X@{}}
\toprule Binary krok & Predykcja & Odczyt \\
\midrule
po create & 0 & \blank{2.5cm} \\
po pierwszym give & 1 & \blank{2.5cm} \\
drugi give przy full & false / nadal 1 & \blank{2.5cm} \\
po take(0) & 0 & \blank{2.5cm} \\
\bottomrule
\end{tabularx}

\vspace{1em}
\noindent\begin{tabularx}{\textwidth}{@{}p{4.6cm}p{3.4cm}X@{}}
\toprule Counting krok & Predykcja & Odczyt \\
\midrule
max / initial & 2 / 2 & \blank{2.5cm} \\
give przy max & false / 2 & \blank{2.5cm} \\
po take 1 & 1 & \blank{2.5cm} \\
po take 2 & 0 & \blank{2.5cm} \\
take 3, portMAX delay & waiter Blocked & \blank{2.5cm} \\
signaler give / handoff & waiter wakes, count 0 & \blank{2.5cm} \\
\bottomrule
\end{tabularx}

\section{Dlaczego count po handoff nadal wynosi zero?}
Give przekazuje dostępność oczekującemu waiterowi. Ponieważ waiter ma wyższy
priorytet, natychmiast kończy zablokowany take i konsumuje token, zanim signaler
ponownie odczyta count.

Narysuj kolejność: waiter block, signaler give, waiter ready/run/take, signaler
resume.\\[.5em]\blank{16cm}\\[1em]\blank{16cm}

\section*{Storage}
Oba uchwyty muszą równać się caller \texttt{StaticSemaphore\_t} w .bss. Create
i destroy nie zmieniają heapu. Notification nie ma trzeciego control block:
value/state istnieją już w TCB waitera.

\newpage
\section{Notification jako count 1}
\begin{lstlisting}
freertos::TaskNotification target{waiter_handle};
target.give();
// in waiter:
uint32_t n = freertos::TaskNotification::take(true, timeout);
\end{lstlisting}

\noindent\begin{tabularx}{\textwidth}{@{}p{5cm}p{3.2cm}X@{}}
\toprule Pomiar & Predykcja & Odczyt \\
\midrule
waiter przed give & Blocked & \blank{2.5cm} \\
notification value po give & 1 pending & checkpoint / GDB \\
take clear-on-exit result & 1 & \blank{2.5cm} \\
value po take & 0 & \blank{2.5cm} \\
\bottomrule
\end{tabularx}

\section{Notification jako jawna wartość}
\begin{lstlisting}
target.notify(0xA5A55A5A,
              freertos::NotificationAction::overwrite);
uint32_t value;
TaskNotification::wait_value(value, timeout);
\end{lstlisting}

\noindent\begin{tabularx}{\textwidth}{@{}p{5cm}p{3.2cm}X@{}}
\toprule Pomiar & Predykcja & Odczyt \\
\midrule
waiter przed notify & Blocked & \blank{2.5cm} \\
action & overwrite & \blank{2.5cm} \\
received value & \texttt{0xA5A55A5A} & \blank{2.5cm} \\
clear on exit & wszystkie bits & \blank{2.5cm} \\
\bottomrule
\end{tabularx}

\section*{Clear kontra decrement}
\texttt{take(true)} zeruje cały count i zachowuje się jak binary. Z
\texttt{take(false)} odejmuje jeden i zachowuje się jak counting. Co zwrócą dwa
kolejne take(false), gdy przed nimi wykonano trzy give?\\[.5em]\blank{16cm}

\section*{Ćwiczenie wyboru}
Dobierz mechanizm: (a) dwa wolne bufory DMA, (b) UART budzi konkretny parser,
(c) przycisk publikuje strukturę z timestampem.\\[.5em]\blank{16cm}\\[1em]
\blank{16cm}

\newpage
\section{Hazard3/GDB i zaliczenie}
\begin{lstlisting}[language=bash]
make check
riscv64-unknown-elf-gdb build/task01_semaphore_notify/prog.elf
b synchronization_debug_checkpoint
\end{lstlisting}
\begin{lstlisting}
p g_binary_initial_count
p g_binary_after_give
p g_binary_second_give
p g_counting_initial_count
p g_count_after_take1
p g_count_after_take2
p g_waiter_state_for_counting
p g_waiter_state_for_notification
p g_notification_pending_checkpoint
p g_notification_take_value
p/x g_notification_message_value
p g_sync_pass
\end{lstlisting}

\section*{Zaliczenie}
\begin{itemize}
  \item $\square$ rozróżniam binary signal, counting slots i TCB notification;
  \item $\square$ pokazuję binary 0--1--0 i odrzucony drugi give;
  \item $\square$ pokazuję counting 2--1--0, Blocked i handoff;
  \item $\square$ notification give/take zwraca dokładnie 1;
  \item $\square$ overwrite/wait przenosi 0xA5A55A5A;
  \item $\square$ wyjaśniam storage, cardinality i clear policy.
\end{itemize}

\section*{Wyjście}
Dlaczego notification nie zastąpi kolejki wielu konsumentów?\\[.5em]
\blank{16cm}\\[1em]
Dlaczego semaphore count nie jest payloadem aplikacji?\\[.5em]\blank{16cm}

\vfill
\noindent\textbf{Następna karta K13:} typed \texttt{EventBits}, wait any/all,
clear-on-exit oraz koordynacja stanu wielu tasków.
\end{document}