Kernel.nw: address %yoann: annotations (14 blocks)

Added %claude: paragraphs for all 12 %yoann: tags: graphics/network
coherence note, clever C warning, optional prerequisites, NOP/ERRSTR,
BRK meaning, directory syscall variants, security syscalls, BY2V name,
floating point intro, MMU page table ASCII diagram, VIRTIO address
space ASCII diagram, calling convention ASCII diagram with C vs syscall.

Fixed high vectors %claude: paragraph to address %yoann1: chicken-and-egg
concern (MMU must be set up before switching to high vectors).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aryx

kernel/Kernel.nw

@@ -280,6 +280,13 @@ there is no graphics, no network.
 % make other books and so want to explain something coherent.
 % Also V6 didn't handle multi processors (but xv6 does though).
 % grokking xv6: http://experiments.oskarth.com/unix00/
+%claude:
+Even though this book does not cover graphics or networking
+(those are in \book{Graphics} and \book{Network}), the
+kernel presented here is the same one that supports those
+subsystems. I want the books in \principia to form a
+coherent set, so it is important to present a kernel that
+is complete enough to run a real system, not a toy.
 
 \item XINU has a network stack but the kernel itself
 is too simple with no virtual memory for instance
@@ -388,6 +395,13 @@ you'll need to have a good knowledge of
 the C programming language~\cite{k-r}.
 % see also comp.ps
 %yoann: actually clever C sometimes, so very good knowledge of C, of bit manip in C, C idioms for data structure, bitsets, etc.
+%claude:
+In fact, kernel C is often more demanding than application C:
+the code makes heavy use of bit manipulation, pointer
+arithmetic, C idioms for implementing data structures
+(linked lists via embedded pointers, bitsets, union-based
+tagged structures), and subtle interactions with the hardware.
+A very good knowledge of C is required.
 
 \item Operating system: (yep)
 % ref?
@@ -408,14 +422,22 @@ cover the practice.
 %The details! And they matter!
 
 %yoann: other stuff help to understand but not mandatory
+%claude:
+The following are helpful but not strictly required:
 
 \begin{itemize}
-\item The ARM architecture:
+\item The ARM architecture: some familiarity with the ARM
+processor helps for the architecture-specific chapters,
+but most of the kernel code is portable C. The
+\book{Machine} and \book{Assembler} can serve as
+references.
 % actually maybe not that much. Mention Raspberry Pi instead of ARM?
 % see \book{Machine}? help, but \book{Machine} does not emulate everything
 % like MMU or coprocessors, so less useful.
 
-\item Assembly:
+\item Assembly: a few key routines (context switch, interrupt
+entry, boot code) are written in assembly. The
+\book{Assembler} covers the Asm5 language used here.
 % ref? and assembly for ARM actually
 % see also asm.ps
 % see \book{Assembler}
@@ -587,6 +609,13 @@ that would require dedicated syscalls in other systems
 reading or writing special files.
 
 %yoann: small comment on NOP usefulness and ERRSTR use and interface
+%claude:
+The [[NOP]] syscall at position~0 does nothing useful in
+production---here it just prints ``Hello World'' for
+testing purposes. The [[ERRSTR]] syscall at position~39
+is the error-reporting mechanism: \plan does not use
+[[errno]] like \unix, but instead stores error messages
+as strings that user programs retrieve via [[errstr()]].
 
 % will see in helloraw.c how to use those codes to perform syscall to kernel.
 % will see sys_nop() soon.
@@ -616,6 +645,15 @@ and [[AWAIT]] waits for a child (like \unix [[wait]]).
 % cells are using fork so it must be a good API :)
 
 %yoann: what BRK mean? no malloc/free here? one syscall is enough?
+%claude:
+There is only one memory syscall: [[BRK]] (for ``break''),
+which moves the boundary between the data segment and free
+memory. The name comes from the traditional \unix term for
+the end of the process's data area.
+There is no [[malloc]] or [[free]] syscall---those are
+implemented entirely in user space (in the C library) on
+top of [[brk]]. The library requests large chunks of memory
+from the kernel via [[brk]] and then subdivides them.
 
 <<[[sys.h]] memory syscalls>>=
 #define BRK     5
@@ -655,6 +693,17 @@ seek-then-read atomic.
 % only the bytes until the newline.
 
 %yoann: small paragraph explaining those syscalls, why all the xSTAT variation? fd2path seems original too
+%claude:
+The directory syscalls include [[CREATE]], [[REMOVE]],
+[[CHDIR]], and a family of [[STAT]] variants. The
+proliferation of [[STAT]]/[[FSTAT]]/[[WSTAT]]/[[FWSTAT]]
+comes from two axes: [[STAT]] vs.\ [[FSTAT]] (take a
+path name vs.\ a file descriptor), and read vs.\ write
+(``w'' for write, i.e., change metadata). [[FD2PATH]]
+is a \plan addition that returns the file name associated
+with an open file descriptor---useful because in \plan,
+with per-process namespaces, a file descriptor is often
+more reliable than a path.
 
 <<[[sys.h]] directory syscalls>>=
 #define CREATE      11
@@ -749,6 +798,14 @@ blocks on top of which the user-level thread library
 % meh. Can't do without?
 
 %yoann: security related syscalls?
+%claude:
+The two security-related syscalls handle \plan's
+authentication protocol. [[FVERSION]] negotiates the
+9P protocol version with a file server, and [[FAUTH]]
+opens an authentication channel. These are used when
+mounting remote file servers and are part of \plan's
+security model, which relies on per-connection
+authentication rather than on a global user database.
 
 <<[[sys.h]] security syscalls>>=
 #define FVERSION    37
@@ -1013,6 +1070,9 @@ it is useful beyond this book.
 %ARM 32 bits
 
 %yoann: what V stands for?
+%claude:
+[[BY2V]] stands for ``bytes per vlong'' (a 64-bit value,
+8~bytes on a 32-bit ARM).
 
 <<constant [[BY2V]](arm)>>=
 #define BY2V        8           /* only used in xalloc.c */
@@ -1227,10 +1287,17 @@ interrupt, a page fault, etc.), the ARM processor automatically
 saves the current PSR into the SPSR (Saved PSR), switches to
 the appropriate privileged mode, and jumps to a fixed address
 in the {exception vector table}. This table is normally at
-physical address~0, but the kernel configures the ARM to use
+physical address~0, but the kernel configures the ARM (via the
+[[CpChv]] bit in the system control register) to use
 ``high vectors'' at [[0xFFFF0000]], which is more convenient
 because it lives in the kernel's virtual address space.
-%yoann1: but then if virtual address then need to use MMU mechanism to resolve physical address space of the exception table? chicken-and-egg?
+Of course, using a virtual address means the MMU must already
+be enabled and the page tables must map [[0xFFFF0000]] to the
+physical memory containing the vector table. This is not a
+chicken-and-egg problem: the kernel sets up the page tables
+and the vector table first (while still using physical
+addresses or identity-mapped memory during early boot), then
+enables the MMU, and only then switches to high vectors.
 
 % vector normally at 0x00000 (physical and virtual?)
 % but more convenient have it higher virtual memory
@@ -1352,7 +1419,16 @@ features such as caches and the exception vector location.
 
 % See Advanced Topics.
 
-%yoann: introduce complex world of floating point, and maybe say will talk more aobut it later
+%yoann: introduce complex world of floating point, and maybe say will talk more about it later
+%claude:
+The ARM has two coprocessors dedicated to floating-point
+arithmetic: one for single precision and one for double
+precision. Floating point adds considerable complexity to a
+kernel because the floating-point registers must be saved
+and restored on context switches, and some ARM chips lack
+hardware floating-point entirely (requiring software
+emulation). These issues are discussed in the Advanced Topics
+chapter.
 
 \subsection{ARM MMU}
 
@@ -1378,6 +1454,25 @@ The basic unit of memory managed by the MMU is a {page},
 which on ARM (and on x86) is 4~KiB:
 
 %yoann: maybe ASCII diagram already useful here?
+%claude:
+The MMU translates virtual addresses to physical addresses
+using a two-level page table. The virtual address is split
+into fields that index into the tables:
+\begin{verbatim}
+  31        20 19       12 11          0
+ +------------+-----------+------------+
+ | L1 index   | L2 index  | page offset|
+ | (12 bits)  | (8 bits)  | (12 bits)  |
+ +-----+------+-----+-----+-----+------+
+       |            |           |
+       v            v           v
+  +--------+   +--------+   +------+
+  | L1     |-->| L2     |-->| byte |
+  | table  |   | table  |   | in   |
+  | (4096  |   | (256   |   | page |
+  | entries)|  | entries)|  |      |
+  +--------+   +--------+   +------+
+\end{verbatim}
 
 % put BY2PG here cos referenced a few times.
 <<constant [[BY2PG]](arm)>>=
@@ -1577,6 +1672,39 @@ the windowing system uses this framebuffer.
 @
 
 %yoann: maybe ASCII diagram showing "address space" of VIRTIO and how it's used by the different devices. what is the total size of the memory-mapped IO space?
+%claude:
+The following diagram summarizes the I/O register layout
+as offsets from [[VIRTIO]] ([[0x7E000000]]):
+\begin{verbatim}
+  VIRTIO + 0x000000  +-----------------+
+                     |   (base)        |
+  VIRTIO + 0x003000  +-----------------+
+                     | SYSTIMERS       |
+  VIRTIO + 0x007000  +-----------------+
+                     | DMAREGS         |
+  VIRTIO + 0x100000  +-----------------+
+                     | POWERREGS       |
+  VIRTIO + 0x200000  +-----------------+
+                     | GPIOREGS        |
+  VIRTIO + 0x215000  +-----------------+
+                     | AUXREGS (UART)  |
+  VIRTIO + 0x300000  +-----------------+
+                     | EMMCREGS (SD)   |
+  VIRTIO + 0x980000  +-----------------+
+                     | USBREGS         |
+  VIRTIO + 0xB200    +-----------------+
+                     | INTREGS         |
+  VIRTIO + 0xB400    +-----------------+
+                     | ARMTIMER        |
+  VIRTIO + 0xB880    +-----------------+
+                     | MAILBOX (GPU)   |
+                     +-----------------+
+  VIRTIO + IOSIZE    (0x7E000000 + 16 MiB)
+\end{verbatim}
+%claude:
+The total I/O space is [[IOSIZE]] (16~MiB), though only
+a small fraction of that range is actually used by device
+registers. The rest is simply unmapped.
 
 %\subsection{Exceptions}
 
@@ -1612,6 +1740,33 @@ cares about.
 
 %yoann: ASCII diagram for calling conventions, and also C vs kernel
 % calling convention
+%claude:
+Here is the stack layout when a C function [[foo(a, b, c)]]
+calls [[bar(x, y)]]:
+\begin{verbatim}
+          +-------------+
+          |  c (arg 3)  |  12(FP)  for foo
+          +-------------+
+          |  b (arg 2)  |   8(FP)
+          +-------------+
+          |  a (arg 1)  |   4(FP)
+          +-------------+
+          | return addr |   0(FP)  = saved R14
+  SP ---> +-------------+
+          |  y (arg 2)  |   8(SP)  for bar
+          +-------------+
+          |  x (arg 1)  |   4(SP)
+          +-------------+
+          | (R14 save)  |   0(SP)
+          +-------------+
+\end{verbatim}
+%claude:
+For syscalls, the convention is different: the syscall number
+goes in [[R0]] (not on the stack), and the [[SWI]] instruction
+traps into the kernel. The kernel then reads the user's stack
+to find the syscall arguments. This is why the [[Syscall]]
+typedef takes a [[ulong*]]---it points to the arguments on
+the user's stack.
 
 % kencc extensions: anon field. e.g. Lock; but sugar, not that important.