Platform Architecture & Support Directory¶
cais is engineered to provide a single, unified C89 and Lua systems programming substrate across more than ten distinct operating system families, spanning over three decades of computing history (1985β2026).
Rather than restricting itself to a lowest-common-denominator subset of POSIX, cais features a Pluggable Platform Abstraction Layer (PAL). The library communicates natively with host operating system kernels, BIOS interrupts, hardware chipsets, and synthetic filesystem trees, offering zero-bloat portability across 16-bit, 32-bit, and 64-bit architectures.
flowchart TD
App["<b>C89 Application / Lua >=5.4 Script</b>"]
--> Subsystems["<b>cais Subsystem Layer</b><br>(platform, filesystem, socket, serial, parallel, sandbox)"]
Subsystems --> Modern["<b>Mainstream Workstations & Cloud</b><br>β’ <b>POSIX & Darwin:</b> Linux, macOS, BSDs (poll, termios, Landlock, Seatbelt)<br>β’ <b>Windows Family:</b> Windows NT 3.1..11 & CE (WSAPoll, Comm API, Mitigations)"]
Subsystems --> Heritage["<b>Retro & Research Environments</b><br>β’ <b>Vintage Microcomputers:</b> DOS, AmigaOS, Atari ST (Direct Hardware I/O, WATT-32)<br>β’ <b>Exotic & Research Kernels:</b> KolibriOS, OS/2, Plan 9 (Syscalls & 9P synthetic trees)"]
ποΈ How cais Subsystems Adapt Across Operating Systems¶
Every subsystem in cais is designed around a clean conceptual boundary, delegating to specialized native drivers depending on the host architecture:
1. Host Identification & Metadata (cais.platform)¶
- Role: Compile-time and runtime introspection of CPU architecture, bitness, endianness, and operating system family.
- Mechanism: Evaluates compiler built-in macros (
__x86_64__,__m68k__,_WIN32,__amigaos__) without triggering expensive system calls or runtime memory allocations. - Endianness Predicates: Provides unambiguous Big-Endian (Motorola 68k, SPARC, PowerPC) and Little-Endian (x86, ARM, RISC-V) validation.
2. Filesystem & Path Operations (cais.filesystem)¶
- Role: Directory traversal, path canonicalization, file streaming, and metadata interrogation.
- Modern POSIX & BSD: Standard POSIX.1-2001 directory streams (
opendir,readdir,stat). - Windows NT & CE: Win32 file handles (
CreateFileAon NT; automatic UTF-8 to UTF-16 wide-character bridging on Windows CE). - MS-DOS & FreeDOS: Direct DOS API file handle manipulation (
_dos_open,_dos_read,_dos_findfirst). - AmigaOS: Native AmigaDOS file lock operations (
Lock(),Examine(),ExNext()). - Atari ST: GEMDOS file search routines (
Fsfirst(),Fsnext()). - Plan 9: Synthetic namespace navigation using native file descriptors and
dirread.
3. Network Sockets & Multiplexing (cais.socket)¶
- Role: Stream TCP, datagram UDP, non-blocking I/O, and asynchronous descriptor multiplexing.
- Modern POSIX, macOS & BSDs: Standard BSD Sockets with linear array multiplexing via
poll(2), bypassing legacyFD_SETSIZElimits. - Windows NT & CE: Adaptive Winsock 2 driver: invokes native
WSAPolldynamically on Windows Vista/11, or automatically falls back to Winsockselect()(configured with#define FD_SETSIZE 1024) on Windows NT 3.51..XP. - MS-DOS Protected Mode: Waterloo TCP/IP (WATT-32) stack integration over hardware packet drivers.
- AmigaOS & AROS: Dynamic binding to
bsdsocket.library(compatible with Roadshow, MiamiDX, and AmiTCP). - Atari ST FreeMiNT: MiNTNet BSD socket device streams.
- KolibriOS: Direct kernel-gate networking via Syscall 75.
- Plan 9: Synthetic network hierarchies under
/net/tcpand/net/udp(clone,ctl,data).
4. Serial Port RS-232 Driver (cais.serial)¶
- Role: Physical asynchronous serial communication (baud rate, parity, stop bits, flow control, modem lines).
- POSIX & Darwin: Standard POSIX
termiosconfiguration over/dev/tty*and/dev/cu.*device nodes. - Windows NT & CE: Win32 Communications API (
SetCommState,GetCommModemStatus) forCOM1..COM9and\\.\COM10+. - MS-DOS: Direct hardware I/O port manipulation of the National Semiconductor 8250 / 16550 UART chips (
0x3F8,0x2F8) and BIOSINT 14h. - AmigaOS: Native Amiga
serial.deviceExec I/O request packets and Paula UART chipset control. - Atari ST: Direct memory-mapped register configuration of the Motorola MFP 68901 UART (
0xFFFFFA01). - IBM OS/2: Kernel asynchronous communications via
DosDevIOCtl(Category 1). - Plan 9: Human-readable text control streams via
/dev/eia0ctl(e.g."b115200","l8","pn").
5. Centronics Parallel Port IEEE 1284 (cais.parallel)¶
- Role: Hardware line printer data transmission and hardware status pin interrogation (Busy, Ack, Paper Out, Error).
- Linux: Linux line printer character devices (
/dev/lp0../dev/lp2). - Windows NT & CE: Win32 parallel port drivers (
LPT1..LPT3). - MS-DOS: Direct parallel port strobe toggling (
0x378,0x278) and BIOSINT 17hprint service. - AmigaOS: Native Amiga
parallel.deviceExec I/O requests handled by CIA 8520 chips. - Atari ST: Centronics handshaking through Port A of the Yamaha YM2149 sound chip and MFP strobe GPIO.
- macOS: Safely reports
CAIS_PARALLEL_UNSUPPORTED(-4) with zero runtime overhead (hardware absent on Apple Macintosh).
6. Kernel Sandboxing & Confinement (cais.sandbox)¶
- Role: Irrevocable application sandboxing based on unified declarative policies.
- Linux: Linux Landlock LSM (ABIs 1 to 5) with
prctl(PR_SET_NO_NEW_PRIVS). - macOS Darwin: Apple Seatbelt MAC framework via dynamic TinyScheme SBPL synthesis and
sandbox_init(). - Windows NT: Dynamic resolution of
SetProcessMitigationPolicy(prohibiting child processes, enforcing W^X dynamic code memory hardening, and strict handle checking). - OpenBSD: Automatic path confinement via
unveil(2)and syscall promise filtering viapledge(2). - FreeBSD: Strict capability mode via
cap_enter(2)(Capsicum). - Vintage & Retro Platforms: Graceful fallback reporting
CAIS_SANDBOX_UNSUPPORTED(-4).
π§ Dedicated Platform Directory¶
Explore the dedicated documentation, hardware driver specifications, and implementation details for each target platform:
| Platform Family | Key Architecture & Subsystem Highlights |
|---|---|
| Linux (Modern & Embedded) | Modern LTS & embedded (glibc, musl, uClibc, bionic), Landlock LSM ABI 1β5, poll(2). |
| macOS (Darwin & Apple Silicon) | Apple Silicon (arm64), Intel, and PowerPC (G4/G5); Seatbelt SBPL sandboxing via sandbox_init(). |
| Windows NT & CE | 30 years of Windows (NT 3.1..11, CE 3.0+), dynamic WSAPoll, 1024-handle select, Process Mitigations. |
| OpenBSD | Security-first OS; automatic unveil(2) path confinement and synthesized pledge(2) promises. |
| FreeBSD | Capsicum capability mode (cap_enter), high-concurrency BSD sockets, /dev/lpt*. |
| NetBSD & DragonFly BSD | Unmatched architecture portability (alpha, vax, m68k, sparc, x86_64); HAMMER & SMP on DragonFly. |
| MS-DOS & FreeDOS | 16-bit Real Mode & 32-bit Protected Mode (DJGPP, DOS/4GW), WATT-32 TCP/IP, direct 8250 UART. |
| Commodore AmigaOS & AROS | Motorola 68000..68060 & AROS; AmigaDOS lock packets, parallel.device, serial.device, bsdsocket.library. |
| Atari ST (TOS & FreeMiNT) | TOS & FreeMiNT; direct MFP 68901 UART registers, Yamaha YM2149 Centronics strobe, MiNTNet BSD sockets. |
| KolibriOS | Pure x86 assembly OS; Syscall 46 direct port strobe/UART and Syscall 75 IPv4 network stack. |
| IBM OS/2 & ArcaOS | 32-bit flat memory model; DosOpen LPT devices, DosDevIOCtl asynchronous serial, IBM TCP/IP Sockets. |
| Plan 9 from Bell Labs & 9front | 9P synthetic directory trees; /net/tcp socket hierarchy, /dev/eia*ctl text commands, /dev/lp. |
| Kernel Internals & Gotchas | Deep technical breakdown of syscalls, buffer management, and platform quirks. |
ποΈ Comprehensive Driver & Subsystem Matrix¶
Universal Baseline Subsystem:
cais.platform(host OS identification, CPU architecture, bitness, and endianness) is supported across 100% of all target platforms.
| Platform Family | Filesystem (fs) |
Parallel (parallel) |
Serial (serial) |
Sockets (socket) |
Sandboxing (sandbox) |
|---|---|---|---|---|---|
| Linux (Modern & Embedded) | β POSIX | β
/dev/lp* |
β termios | β
BSD / poll(2) |
β Landlock LSM |
| OpenBSD | β POSIX | β
/dev/lpt* |
β termios | β
BSD / poll(2) |
β Pledge & Unveil |
| FreeBSD | β POSIX | β
/dev/lpt* |
β termios | β
BSD / poll(2) |
β Capsicum mode |
| NetBSD & DragonFly BSD | β POSIX | β
/dev/lpt* |
β termios | β
BSD / poll(2) |
β οΈ Safe Stub (-4) |
| macOS (Darwin) | β POSIX | β οΈ Safe Stub | β termios | β
BSD / poll(2) |
β Seatbelt SBPL |
| Windows NT (10 / 11 / Server) | β Win32 | β Win32 LPT | β Comm API | β
WSAPoll dynamic |
β Mitigations (1607+) |
| Windows NT (3.51..XP / 7) | β Win32 | β Win32 LPT | β Comm API | β
Winsock select (1024) |
β οΈ Safe Stub (-4) |
| Windows CE 3.0..6.0 (ARM/MIPS) | β WinCE W | β WinCE LPT | β Comm API | β Winsock CE | β οΈ Safe Stub (-4) |
| MS-DOS (16/32-bit WATT-32) | β DOS io | β
INT 17h / I/O |
β
INT 14h / 8250 |
β WATT-32 TCP/IP | β οΈ Safe Stub (-4) |
| AmigaOS (m68k / AROS) | β Lock DOS | β
parallel.device |
β
serial.device |
β
bsdsocket.library |
β οΈ Safe Stub (-4) |
| Atari ST (TOS / MiNT) | β Fsfirst | β Hardware I/O | β MFP 68901 UART | β MiNTNet Sockets | β οΈ Safe Stub (-4) |
| KolibriOS (x86) | β οΈ Safe Stub | β Syscall 46 / I/O | β Syscall 46 / UART | β Syscall 75 | β οΈ Safe Stub (-4) |
| OS/2 / ArcaOS | β access | β DosOpen LPT | β DosDevIOCtl | β TCP/IP BSD | β οΈ Safe Stub (-4) |
| Plan 9 from Bell Labs | β access | β
/dev/lp |
β
/dev/eia* |
β
/net/tcp |
β οΈ Safe Stub (-4) |
β±οΈ Minimum Operating System Versions¶
The table below outlines the minimum operating system version required for core library execution, as well as specific milestone releases where advanced subsystem features become active:
| Operating System Family | Minimum OS for Core (cais) |
Advanced Subsystem Milestones & Requirements |
|---|---|---|
| Linux | Linux 2.0+ (libc5 / glibc 2.0) | β’ poll(2) multiplexing: Linux 2.1.23+β’ Landlock v1 (Filesystem): Linux 5.13+ β’ Landlock v2 (Refer): Linux 5.19+ β’ Landlock v3 (Truncate): Linux 6.2+ β’ Landlock v4 (TCP Network): Linux 6.7+ β’ Landlock v5 (IOCTL dev): Linux 6.12+ |
| macOS (Darwin) | Mac OS X 10.0 (Cheetah, 2001) | β’ PowerPC Support: Mac OS X 10.0 atΓ© 10.5 Leopard (ΓΊltima versΓ£o compatΓvel com PowerPC; 10.6 Snow Leopard tornou-se exclusivamente Intel) β’ Seatbelt Sandboxing ( sandbox_init): Mac OS X 10.5+ (Leopard)β’ Dynamic event polling: macOS 10.3+ ( poll(2)) |
| Windows NT | Windows NT 3.1 (1993) | β’ Filesystem, Serial, LPT: Windows NT 3.51+ (1995) β’ Adaptive WSAPoll: Windows Vista / Server 2008+β’ Process Mitigations (W^X / Handles): Windows 8.1+ β’ Child Process Restrictions: Windows 10 Version 1607+ |
| Windows CE | Windows CE 3.0 (Pocket PC 2000) | β’ Filesystem (*W Unicode): CE 3.0+β’ Networking: Winsock for CE 3.0+ |
| OpenBSD | OpenBSD 2.0 (1996) | β’ pledge(2) syscall restrictions: OpenBSD 5.9+ (2016)β’ unveil(2) filesystem confinement: OpenBSD 6.4+ (2018) |
| FreeBSD | FreeBSD 3.0 (1998) | β’ Capsicum capability mode (cap_enter): FreeBSD 10.0+ (2014) |
| MS-DOS | MS-DOS 3.30 (1987) | β’ Networking (WATT-32 32-bit TCP/IP stack): 386+ protected mode (DJGPP / Open Watcom DOS/4GW) |
| AmigaOS | AmigaOS 1.2 / 1.3 (1986) | β’ Parallel & Serial drivers: AmigaOS 1.2+ (parallel.device, serial.device)β’ Networking: AmigaOS 2.04+ with AmiTCP / Miami ( bsdsocket.library) |
| Atari ST | TOS 1.00 (1985) | β’ Filesystem & Hardware I/O: GEMDOS / TOS 1.0+ β’ Networking: FreeMiNT 1.12+ with MiNTNet socket stack |
| OS/2 / ArcaOS | OS/2 2.0 (1992) | β’ Networking: OS/2 Warp 3.0+ with TCP/IP stack |
| KolibriOS | KolibriOS 0.7.7.0+ | β’ Raw I/O & UART: Syscall 46 β’ Networking: Syscall 75 (Stack IP v4) |
| Plan 9 from Bell Labs | Plan 9 3rd / 4th Edition | β’ Networking: Native /net/tcp and /net/udp synthetic file trees |
π‘οΈ Runtime Feature Degradation Model¶
cais guarantees that an application compiled with support for advanced features will never crash with missing dynamic symbols or loader failures when deployed on an older release within the same OS family:
- Windows:
WSAPollandSetProcessMitigationPolicyare probed at runtime viaGetProcAddress. When missing on Windows XP or Windows 7,caissafely falls back toselect()(with expanded 1024-handle arrays) or returnsCAIS_SANDBOX_UNSUPPORTED(-4). - Linux: Landlock syscall availability is probed via
syscall(__NR_landlock_create_ruleset, NULL, 0, LANDLOCK_CREATE_RULESET_VERSION). If Landlock is uncompiled or the kernel predates 5.13,caiscleanly reports unsupported. - OpenBSD / FreeBSD: Syscall support is checked via probe invocations (
pledge(NULL, NULL)andsysctlbyname("kern.features.capsicum")).