System Conventions & Infrastructure

Overview

This document defines the system-level infrastructure that Chapp-E's kernel and libc depend on. While we replicate glibc functions for the C library layer, this page documents the underlying OS infrastructure that makes everything work.

✅ TWO-LAYER APPROACH:

libc Layer: Replicating glibc functions (printf, malloc, etc.) - see C Library
System Layer: Building the infrastructure that libc depends on (syscalls, data structures, conventions) - this page

Naming Conventions

Function Naming

Pattern	Example	Description
`system_init`	`braincontroller_init`	System initialization function
`system_main`	`braincontroller_main_loop`	Main loop/entry point
`syscall_name`	`syscall_write`	System call handler
`function_name_64`	`braincontroller_64.asm`	64-bit implementation

Constant Naming

Pattern	Example	Description
`SYS_NAME`	`SYS_WRITE`	System call number
`SYS_ID_NAME`	`SYS_ID_IO`	System ID for Brain Controller routing
`MSG_TYPE_NAME`	`MSG_TYPE_INPUT`	Message type constant
`STATE_NAME`	`BC_STATE_READY`	State constant
`ADDR_NAME`	`BC_STATE_ADDR`	Memory address constant

Data Structure Naming

Pattern	Example	Description
`struct_name`	`message_queue`	Structure name (assembly: labels)
`struct_name.field`	`message_queue.head`	Structure field

Calling Conventions

x86-64 System V ABI

Chapp-E follows the standard x86-64 System V ABI for all function calls:

Arguments: RDI, RSI, RDX, RCX, R8, R9 (then stack)
Return Value: RAX
Callee-Saved: RBX, RBP, R12-R15
Caller-Saved: RAX, RCX, RDX, RSI, RDI, R8-R11

System Call Convention

System calls use the same register convention:

RAX: System call number
RDI: First argument
RSI: Second argument
RDX: Third argument
R10: Fourth argument (RCX is clobbered by syscall)
R8: Fifth argument
R9: Sixth argument
Return: RAX (negative = error, positive = success)

Data Structure Conventions

Structure Layout

In assembly, structures are defined as consecutive memory regions with labeled offsets:

; Example: Message Queue Structure
message_queue:
    .head:      db 0      ; Queue head index
    .tail:      db 0      ; Queue tail index
    .size:      db 0      ; Current queue size
    .buffer:    times 256 db 0  ; Message buffer

Alignment

8-byte alignment: All 64-bit values (pointers, qwords)
4-byte alignment: 32-bit values (dwords)
Natural alignment: Structures align to largest member

Memory Regions

0x100000 - 0x1FFFFF: Kernel code region (read-only after init)
0x200000+: System data structures (writable)
Stack: Grows downward from kernel stack pointer
Heap: TBD - will be allocated dynamically

System Call Infrastructure

Syscall Numbers

Chapp-E uses OpenBSD-compatible syscall numbers for standard operations:

1-99: Standard POSIX syscalls (exit, read, write, open, close, etc.)
0x100+: Chapp-E-specific syscalls (send_msg, get_state, etc.)

See System Calls for complete reference.

Syscall Table

The syscall table maps syscall numbers to handler functions:

syscall_table:
    dq 0                      ; 0 = unimplemented
    dq syscall_exit           ; 1 = exit
    dq syscall_read           ; 3 = read
    dq syscall_write          ; 4 = write
    ; ... etc

Error Handling

Success: Return value ≥ 0 in RAX
Error: Return negative value (OpenBSD error code)
errno: Set by syscall handler (libc reads this)

Brain Controller Integration

System IDs

All subsystems have unique IDs for Brain Controller routing:

ID	System	Description
`0x01`	`SYS_ID_IO`	I/O System (Brainstem)
`0x02`	`SYS_ID_FSM`	Finite State Machine (Basal Ganglia)
`0x03`	`SYS_ID_GCS`	Garbage Collection System (Thalamus)
`0x04`	`SYS_ID_CONS`	Consciousness System
`0x05`	`SYS_ID_NN`	Neural Network
`0x06`	`SYS_ID_MEMORY`	Memory System (Hippocampus)
`0x07`	`SYS_ID_EXEC`	Executive Control (Prefrontal Cortex)
`0x0C`	`SYS_ID_NEUROMOD`	Neuromodulator System
`0x0D`	`SYS_ID_DAGFS`	DAG-FS Filesystem

Message Types

Type	Constant	Description
`0x10`	`MSG_TYPE_INPUT`	Input message
`0x20`	`MSG_TYPE_OUTPUT`	Output message
`0x30`	`MSG_TYPE_STATE`	State change
`0x40`	`MSG_TYPE_COMMAND`	Command to execute
`0x50`	`MSG_TYPE_RESPONSE`	Response to command
`0x80`	`MSG_TYPE_ERROR`	Error detection

Error Codes

Chapp-E uses OpenBSD-compatible error codes for consistency:

Code	Name	Description
`0`	`E_OK`	Success (no error)
`1`	`EPERM`	Operation not permitted
`2`	`ENOENT`	No such file or directory
`3`	`ESRCH`	No such process
`4`	`EINTR`	Interrupted system call
`5`	`EIO`	Input/output error
`9`	`EBADF`	Bad file descriptor
`11`	`EAGAIN`	Resource temporarily unavailable
`12`	`ENOMEM`	Cannot allocate memory
`13`	`EACCES`	Permission denied
`14`	`EFAULT`	Bad address
`22`	`EINVAL`	Invalid argument

See libc/include/errno.h for complete list.

File Descriptors

Standard File Descriptors

FD	Name	Description
`0`	`STDIN_FILENO`	Standard input (keyboard)
`1`	`STDOUT_FILENO`	Standard output (VGA text)
`2`	`STDERR_FILENO`	Standard error (VGA text, red)

File Descriptor Allocation

0-2: Reserved for stdin/stdout/stderr
3+: Dynamically allocated (TBD - requires process management)

Process Management (Future)

Process Structure

When process management is implemented, each process will have:

Process ID (PID): Unique identifier
Parent PID: Parent process ID
State: Running, sleeping, zombie, etc.
File Descriptors: Open file descriptor table
Memory Map: Virtual memory layout
Stack: Process stack pointer

Process States

State	Constant	Description
Running	`PROC_STATE_RUNNING`	Currently executing
Sleeping	`PROC_STATE_SLEEPING`	Waiting for event
Zombie	`PROC_STATE_ZOMBIE`	Terminated, waiting for parent
Stopped	`PROC_STATE_STOPPED`	Suspended (SIGSTOP)

Memory Management (Future)

Heap Allocator

When heap allocation is implemented, it will provide:

malloc(size): Allocate memory block
free(ptr): Free memory block
realloc(ptr, size): Resize memory block
calloc(nmemb, size): Allocate and zero-initialize

Heap Structure

Heap Start: TBD (will be allocated at 0x300000+)
Heap Size: Dynamically grows as needed
Allocation Algorithm: TBD (first-fit, best-fit, etc.)

Documentation Standards

When Adding New Infrastructure

Update this page with new conventions/structures
Update memory-layout.html if memory addresses change
Update system-calls.html if new syscalls are added
Add code comments explaining the design
Cross-reference related documentation

Code Documentation

All system-level code should include:

Header comment: Purpose and usage
Function comments: Parameters, return values, side effects
Constant definitions: Clear names and values
Memory layout: Document any data structures