System Calls (Syscalls)

Chapp-E's kernel interface for user-space programs

Overview

System calls are the interface between user-space programs and the kernel (Brain Controller). They allow programs to request kernel services like I/O, memory management, and process control.

✅ KEY INSIGHT: We can absolutely make OpenBSD's system calls work with our kernel! We just need to implement the syscall handlers in our Brain Controller. The syscall numbers and signatures are just an interface - we can implement them however we want internally. This gives us full compatibility while maintaining our unique neural-inspired architecture.

The Strategy: OpenBSD Interface, Chapp-E Implementation

Here's how we make OpenBSD syscalls work with Chapp-E:

  1. Use OpenBSD's syscall numbers and signatures - This is the interface that programs expect
  2. Implement handlers in our Brain Controller - This is our implementation, using our message-based architecture
  3. Programs work unchanged - They call the same syscalls, but they're handled by Chapp-E's kernel

Example: When a program calls sys_write(1, "Hello", 5):

  • Program uses OpenBSD syscall number 4 (SYS_WRITE)
  • Chapp-E's kernel receives the syscall
  • Brain Controller routes it through our message system
  • I/O system handles it using our VGA/text output
  • Program gets the expected result - text appears on screen!

Why We Need System Calls

  • Security: Isolate user programs from kernel internals
  • Abstraction: Provide a stable API for kernel services
  • Portability: Allow programs to work without knowing kernel internals
  • C Library Support: Enable building a C library (like glibc, but for Chapp-E)

Chapp-E vs. Other Operating Systems

OpenBSD System Calls (Reference)

OpenBSD has a clean, well-documented system call interface that we can use as a reference:

  • Well-designed API: Clean function signatures and naming
  • POSIX-compliant: Standard Unix system calls (read, write, open, close, etc.)
  • Documented: Clear syscall numbers and parameters
  • Stable: Mature, battle-tested interface
✅ STRATEGY: We can align Chapp-E's system call numbers with OpenBSD for common syscalls (read, write, open, close, etc.) to maintain compatibility and familiarity. This makes it easier to port programs and understand the API.

Linux/glibc Approach

glibc is designed for Linux systems and expects Linux system calls:

  • Linux syscalls (read, write, open, close, etc.)
  • POSIX API (pthreads, signals, etc.)
  • Linux-specific features (epoll, inotify, etc.)

Chapp-E Approach

Chapp-E will adopt OpenBSD's system call numbers and names where appropriate, but implement them for Chapp-E's architecture:

  • OpenBSD-compatible syscall numbers for common operations
  • Message-based communication (Brain Controller pattern)
  • Neural-inspired API (systems communicate through messages)
  • Custom C library (Chapp-E libc, inspired by OpenBSD's design)
💡 BEST OF BOTH WORLDS: Use OpenBSD's well-designed system call interface as our foundation, but implement them with Chapp-E's Brain Controller architecture. This gives us compatibility and familiarity while maintaining our unique neural-inspired design.

System Call Mechanism

How System Calls Work

In x86-64, system calls are invoked using the syscall instruction:

; System call invocation
mov rax, SYS_CALL_NUMBER    ; System call number
mov rdi, arg1               ; First argument
mov rsi, arg2               ; Second argument
mov rdx, arg3               ; Third argument
syscall                      ; Invoke kernel
; Return value in RAX

Chapp-E System Call Convention

Chapp-E follows the x86-64 System V ABI for system calls:

  • RAX: System call number
  • RDI: First argument
  • RSI: Second argument
  • RDX: Third argument
  • R10: Fourth argument
  • R8: Fifth argument
  • R9: Sixth argument
  • Return: RAX contains return value
  • Error: Negative return value indicates error

System Call Numbers

Chapp-E aligns with OpenBSD's system call numbers for common operations to maintain compatibility and familiarity. This makes it easier to port programs and understand the API.

Core System Calls (OpenBSD-Compatible)

These system calls match OpenBSD's numbers and signatures:

Number Name Description Arguments OpenBSD
1 SYS_EXIT Terminate process RDI = exit code ✅ Aligned
2 SYS_FORK Create new process None ✅ Aligned
3 SYS_READ Read from file descriptor RDI = fd, RSI = buf, RDX = count ✅ Aligned
4 SYS_WRITE Write to file descriptor RDI = fd, RSI = buf, RDX = count ✅ Aligned
5 SYS_OPEN Open file RDI = path, RSI = flags, RDX = mode ✅ Aligned
6 SYS_CLOSE Close file descriptor RDI = fd ✅ Aligned
20 SYS_GETPID Get process ID None ✅ Aligned
41 SYS_DUP Duplicate file descriptor RDI = fd ✅ Aligned
90 SYS_DUP2 Duplicate file descriptor to specific number RDI = from, RSI = to ✅ Aligned

Chapp-E-Specific System Calls

These system calls are unique to Chapp-E's Brain Controller architecture:

Number Name Description Arguments Notes
0x100 SYS_SEND_MSG Send message to system (Brain Controller) RDI = sys_id, RSI = msg_type, RDX = data, R10 = len Chapp-E specific
0x101 SYS_RECV_MSG Receive message from system RDI = sys_id, RSI = buf, RDX = max_len Chapp-E specific
0x102 SYS_GET_STATE Get system state (consciousness, etc.) RDI = state_type Chapp-E specific
0x103 SYS_SET_STATE Set system state RDI = state_type, RSI = state_value Chapp-E specific
✅ COMPATIBILITY: By aligning with OpenBSD's system call numbers for common operations, Chapp-E maintains compatibility with standard Unix programs while adding unique neural-inspired features through Chapp-E-specific syscalls (0x100+).

Note: More system calls will be added as Chapp-E evolves. We'll prioritize OpenBSD compatibility for standard operations and add Chapp-E-specific syscalls for Brain Controller features.

Implementation Status

Current State

Chapp-E now has system call infrastructure implemented:

  • ✅ System Call Handler: syscall_handler processes syscall requests
  • ✅ Syscall Table: Array mapping OpenBSD syscall numbers to handlers
  • ✅ MSR Setup: syscall_init configures syscall/sysret instructions
  • ✅ Basic Syscalls: exit, write, getpid, send_msg, get_state implemented
  • ⚠️ User/Kernel Separation: Currently all in kernel mode (Ring 0)
  • ✅ C Library (libchappe): 70+ functions implemented, 100% independent from glibc
  • ✅ Toolchain: Compiler (chappe-cc) and Linker (chappe-ld) Phase 1 complete

Next Steps

  1. More Syscalls: Implement read, open, close, and other common syscalls
  2. Build Chapp-E libc: Create our own C library using glibc as reference
  3. User Space (Future): Implement proper Ring 3 (user) vs Ring 0 (kernel) separation
  4. Test Programs: Create test programs that use syscalls

Using OpenBSD and glibc as References

What We Can Learn from OpenBSD

OpenBSD provides an excellent reference for system call design:

  • System Call Numbers: Well-organized, stable syscall numbers
  • Function Signatures: Clean, POSIX-compliant signatures
  • Documentation: Clear syscall.master format
  • Design Philosophy: Security-focused, clean API

What We Can Learn from glibc

glibc provides reference for C library design. Location: reference/glibc-2.42/

  • API Design: What functions should a C library provide?
  • Function Signatures: Standard C library function signatures
  • Error Handling: How to handle errors (errno, etc.)
  • Implementation Patterns: How to implement common functions
📚 REFERENCE LOCATION: glibc is located at reference/glibc-2.42/ for study purposes. We don't compile or link it - we use it as a reference to understand what a C library should provide and how functions should behave.

What We Must Build Ourselves

  • System Call Interface: OpenBSD-compatible syscalls + Chapp-E-specific ones
  • Syscall Handlers: Kernel functions that implement syscalls (Brain Controller integration)
  • C Library Wrappers: Functions that call Chapp-E syscalls (our own libc, not glibc)
  • Error Codes: OpenBSD-compatible error codes + Chapp-E-specific ones

Building Chapp-E's C Library

We will create our own C library (e.g., libchappe or chappe-libc) that:

  • Provides the same API as glibc (for compatibility)
  • Calls Chapp-E's system calls (not Linux syscalls)
  • Integrates with Brain Controller's message system
  • Maintains OpenBSD-compatible syscall interface
✅ BEST APPROACH: Use OpenBSD's system call numbers and design as our foundation, study glibc's C library API (in reference/glibc-2.42/), but implement everything with Chapp-E's Brain Controller architecture. This gives us compatibility, familiarity, and our unique neural-inspired design.

Integration with Brain Controller

Message-Based System Calls

Chapp-E's system calls can integrate with the Brain Controller's message system:

; User program wants to send a message
mov rax, SYS_SEND_MSG       ; System call number
mov rdi, SYS_ID_CONS        ; Target: Consciousness system
mov rsi, MSG_TYPE_STATE     ; Message type
mov rdx, message_data       ; Data pointer
mov r10, message_len        ; Data length
syscall                      ; Invoke kernel

; Kernel handler routes message through Brain Controller
syscall_handler:
    cmp rax, SYS_SEND_MSG
    je .handle_send_msg
    ; ... other syscalls
    
.handle_send_msg:
    ; Call braincontroller_send internally
    call braincontroller_send
    ret

Benefits

  • Consistent Architecture: System calls use the same message system
  • Centralized Routing: All communication goes through Brain Controller
  • Neural-Inspired: Systems communicate through messages, like neurons

Next Steps: Building OpenBSD-Compatible Syscalls

Phase 1: Basic System Call Infrastructure

  1. Implement syscall handler in Brain Controller - Receives syscall number in RAX
  2. Create syscall table - Maps OpenBSD syscall numbers to our handler functions
  3. Implement basic OpenBSD syscalls - write (4), read (3), exit (1), open (5), close (6)
  4. Integrate with Brain Controller - Route syscalls through message system
  5. Test with assembly programs - Call OpenBSD syscalls directly

Phase 2: More OpenBSD Syscalls

  1. Implement file operations - stat, fstat, lseek, etc.
  2. Implement process operations - fork, getpid, wait4, etc.
  3. Implement memory operations - mmap, munmap, mprotect, etc.
  4. Add error handling - Return proper error codes (OpenBSD-compatible)

Phase 3: C Library Integration

  1. Use or port OpenBSD's libc - It already calls the syscalls we're implementing!
  2. Or build Chapp-E libc - Wrapper functions that call our OpenBSD-compatible syscalls
  3. Add standard functions - printf, malloc, etc. (using our syscalls internally)
  4. Test with C programs - Port Unix programs to Chapp-E

Phase 4: Chapp-E-Specific Extensions

  1. Add Chapp-E syscalls - SYS_SEND_MSG, SYS_RECV_MSG (0x100+)
  2. Neural-inspired features - System state queries, neuromodulator access, etc.
  3. Brain Controller integration - Direct access to message system
💡 THE BEAUTY OF THIS APPROACH: By implementing OpenBSD's syscall interface, we get compatibility with existing Unix programs while maintaining our unique Brain Controller architecture. Programs don't need to know about our message system - they just call standard syscalls, and we handle them our way!

Related Documentation