Document the Tasks, Threads, Ports, messages and memory-object model alongside C17 atomics, zero-copy mappings, firmware isolation, HDA/UAC, iGPU UMA, Bluetooth and LED translator contracts. Mark the reference layer as a tested contract rather than universal physical hardware support.
Signed-off-by: Breno Rodrigues Alves <[email protected]> --- doc/mach.texi | 3 +- doc/modern-platform.texi | 114 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 doc/modern-platform.texi diff --git a/doc/mach.texi b/doc/mach.texi index 70b31383..f99ee526 100644 --- a/doc/mach.texi +++ b/doc/mach.texi @@ -7406,7 +7406,7 @@ next address of the start of the last line examined. Unlike dot or next, this is only changed by @code{examine} or @code{write} command. -@item � +@item � last address explicitly specified. @item $@var{variable} @@ -7421,6 +7421,7 @@ indirection. It may be followed by a @code{:} and modifiers as described above. @end table +@include modern-platform.texi @include gpl.texi @node Documentation License diff --git a/doc/modern-platform.texi b/doc/modern-platform.texi new file mode 100644 index 00000000..e09daf37 --- /dev/null +++ b/doc/modern-platform.texi @@ -0,0 +1,114 @@ +@c -*- Texinfo -*- +@c Modern platform contracts for GNU Mach. +@c Updated to reflect C17 standards and modern hardware subsystems integration. +@c +@c This file is part of GNU Mach. +@c +@c GNU Mach is free software; you can redistribute it and/or modify it +@c under the terms of the GNU General Public License as published by +@c the Free Software Foundation; either version 3, or (at your option) +@c any later version. + +@node Modern Platform Contracts +@chapter Modern Platform Contracts + +@cindex C17 +@cindex microkernel +This chapter documents the optional C17 platform layer in @file{modern/}. +It does not replace the historical Mach interfaces. A @dfn{task} remains +a resource container and address-space owner; a @dfn{thread} remains an +execution context belonging to a task. Ports, port sets, messages and +memory objects remain the capability and communication primitives. + +The modern layer is a contract and testable reference implementation. It +must not be read as a claim that every listed controller is supported by the +upstream GNU Mach boot path. + +@section C17 data and concurrency model + +Kernel-facing headers use @code{uint32_t}, @code{uint64_t}, @code{size_t} +and @code{uintptr_t} where an exact-width or object-size contract is +required. Shared state uses @file{<stdatomic.h>}. A producer publishes a +ring index with @code{memory_order_release}; the consumer loads it with +@code{memory_order_acquire}. Reference counts use relaxed increments and +an acquire-release final decrement. These orders describe visibility; they +do not make a non-atomic object safe to access concurrently. + +Assembly remains appropriate for operations that have no C semantic +substitute, including early boot, control-register loads, interrupt-entry +frames and raw context switching. The C17 layer replaces only portable +locks, bit scans, byte swaps, memory loops and ring bookkeeping. The +compiler built-ins are kept in small, architecture-neutral wrappers. + +@example +uint32_t ready = atomic_load_explicit (&ring->producer, + memory_order_acquire); +@end example + +@section IPC and zero-copy regions + +An inline message copies at most the small fixed payload. A large payload +is represented by a memory object descriptor: the sender, queue and +receiver hold references, while the receiver maps the pages into its task. +The descriptor is copied; the payload is not. A server must validate the +range, protection and lifetime before issuing a device operation. This +preserves the Mach message API while allowing a future translator to use +shared DMA buffers. + +@section PCIe, framebuffer and integrated graphics + +The driver capability layer limits Ring 0 to MMIO mappings, DMA ownership +and interrupt acknowledgement. PCIe BARs are represented by 64-bit +physical addresses, so a BAR above 4 GiB is not truncated. x2APIC, GIC +and MSI-X setup remain platform-specific operations and require a real +interrupt-controller backend. + +The iGPU contract additionally records a claimed UMA or stolen-memory +range and a bounded command ring. KMS policy, command validation and +rendering remain in a user-space server. The reference implementation does +not claim Intel, AMD or ARM GPU command execution; it provides ownership +and lifetime checks for that future server. + +@section Firmware isolation + +Firmware bytes are not compiled into the kernel. A user-space Hurd server +owns an image, validates its CRC32 and uploads bounded chunks through the +@file{modern/interfaces/firmware.defs} contract. The privileged side only +performs a capability-scoped MMIO write and a final ordering fence. A +checksum is an integrity check, not a signature or a proof of vendor +provenance; deployments that require authenticity must add a signed-image +policy in the server. + +@section HDA and USB Audio Class + +The HDA/UAC contract supports 16-, 24- and 32-bit samples, two or more +channels, and rates from 44100 through 192000 Hz. A circular buffer keeps +producer and consumer indexes atomic. HDA stream configuration and MSI-X +acknowledgement are narrow callbacks; codec verbs, mixer policy, UAC1/UAC2 +class parsing and user-visible streams belong to the audio server. + +@section Bluetooth and LED translators + +The Bluetooth interface exposes a USB or PCIe HCI transport and validates +ACL memory-object ranges before advancing a sequence counter. Pairing, +encryption, firmware and packet policy remain in the Bluetooth server. + +LED records contain a safe name, kind, GPIO number and writable flag. A +Hurd translator may expose them as @file{/dev/leds/@var{name}}, but the +platform backend must still implement the actual GPIO or ACPI/EC access. +Names containing @samp{/} are rejected so the translator cannot escape its +namespace. + +@section Support boundary and validation + +The reference layer is built with: + +@example +-std=c17 -Wall -Wextra -Wpedantic -nostdinc -ffreestanding +@end example + +The hosted tests exercise fake MMIO and DMA backends. Passing those tests +proves the contracts and state transitions, not physical support for a +specific codec, GPU, Bluetooth chip, firmware image or motherboard. The +upstream boot configuration and the historical driver collection remain +separate compatibility layers. -- 2.56.0
