Platform Abstraction Layer (PAL)¶
The Platform Abstraction Layer (PAL) decouples high-level public APIs and Lua bindings from OS-specific system calls, hardware I/O ports, and kernel architectures.
PAL Directory Organization¶
Each subsystem contains a dedicated *_pal.h file that detects the host environment and provides unified internal signatures:
src/socket/socket_pal.hsrc/serial/serial_pal.hsrc/filesystem/filesystem_pal.hsrc/parallel/parallel_pal.hsrc/sandbox/sandbox_pal.h
PAL Compilation Pipeline¶
flowchart TD
PublicAPI["Public C API (include/cais/*.h)"]
LuaBinding["Lua Binding (src/*/*_lua.c)"]
BackendDispatch["Subsystem Core Engine"]
PALDetect["PAL Macro Detection<br/>CAIS_IS_POSIX, CAIS_IS_WINDOWS, CAIS_IS_DOS, etc."]
DriverPOSIX["POSIX Driver (termios, poll, dirent)"]
DriverWin32["Win32 Driver (Comm API, WSAPoll/select, FindFirstFile)"]
DriverDOS["DOS Driver (INT 14h, INT 17h, WATT-32)"]
DriverAmiga["Amiga Driver (serial.device, bsdsocket.library)"]
DriverAtari["Atari Driver (MFP 68901, MiNTNet)"]
DriverExotic["Exotic Drivers (KolibriOS, OS/2, Plan 9)"]
PublicAPI --> BackendDispatch
LuaBinding --> BackendDispatch
BackendDispatch --> PALDetect
PALDetect --> DriverPOSIX & DriverWin32 & DriverDOS & DriverAmiga & DriverAtari & DriverExotic
PAL Rules for Contributors¶
- No direct standard includes in public headers: User code including
<cais/cais.h>should not leak<windows.h>,<sys/socket.h>, or<dos.h>. - Abstract socket types: Use
CAIS_PAL_SOCK_TandCAIS_SOCK_IS_VALID()because Windows usesSOCKET(unsigned integer) while POSIX usesint(signed integer). - Interrupt Handling: Loop on transient interrupt signals (
EINTRon POSIX,WSAEINTRon Windows) viaCAIS_PAL_IS_INTR(err).