Brain Controller

Chapp-E's Kernel - The Central Nervous System

Overview

The Brain Controller is Chapp-E's kernel - the central nervous system that coordinates all subsystems, just like how the human brain's central nervous system coordinates all body systems.

✅ CORE ARCHITECTURE: The Brain Controller implements a central hub pattern where all subsystems communicate through it. No direct subsystem-to-subsystem communication exists - everything routes through the Brain Controller.

Architecture

Central Hub Pattern

All subsystems communicate through the Brain Controller:

  • No direct communication between subsystems
  • All messages go through the Brain Controller
  • Centralized routing and coordination
  • Message-based communication protocol

Message Flow

Input → Brain Controller → GCS (filter) → FSM (state) → Processing
                                                              ↓
Output ← Brain Controller ← I/O System ← Consciousness ← Neural Network

System IDs

Each subsystem has a unique ID for Brain Controller routing:

ID Constant System Brain Region
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 Networks
0x05 SYS_ID_NN Neural Network Networks
0x06 SYS_ID_MEMORY Memory System Hippocampus
0x07 SYS_ID_EXEC Executive Control Prefrontal Cortex
0x08 SYS_ID_CEREBELLUM Cerebellum Error Correction
0x09 SYS_ID_REWARD Reward System Substantia Nigra
0x0A SYS_ID_ATTENTION Attention Network Attention
0x0B SYS_ID_SALIENCE Salience Network Salience
0x0C SYS_ID_NEUROMOD Neuromodulator System Limbic System
0x0D SYS_ID_DAGFS DAG-FS Filesystem Hippocampus/Memory

Message Types

Type Constant Description
0x10 MSG_TYPE_INPUT Input message (from I/O system)
0x20 MSG_TYPE_OUTPUT Output message (to I/O system)
0x30 MSG_TYPE_STATE State change notification
0x40 MSG_TYPE_COMMAND Command to execute
0x50 MSG_TYPE_RESPONSE Response to command
0x60 MSG_TYPE_GOAL Goal definition message
0x70 MSG_TYPE_PLAN Execution plan message
0x80 MSG_TYPE_ERROR Error detection message
0x90 MSG_TYPE_REWARD Reward/reinforcement message

Memory Layout

The Brain Controller uses the following memory addresses:

Address Name Size Description
0x100000 BC_STATE_ADDR 1 byte Controller state (INIT, READY, PROCESS, SLEEP, ERROR)
0x100001 BC_QUEUE_HEAD 1 byte Message queue head index
0x100002 BC_QUEUE_TAIL 1 byte Message queue tail index
0x100003 BC_QUEUE_BUF 253 bytes Message buffer

Controller States

Value Constant Description
0 BC_STATE_INIT Initializing
1 BC_STATE_READY Ready for operations
2 BC_STATE_PROCESS Processing messages
3 BC_STATE_SLEEP Sleep mode
4 BC_STATE_ERROR Error state

API Reference

braincontroller_init

Initializes the Brain Controller kernel.

; Initialize Brain Controller
call braincontroller_init

; Sets up:
; - Message queue (head, tail, buffer)
; - Controller state (INIT → READY)
; - Subsystem initialization

braincontroller_send

Send a message to a subsystem through the Brain Controller.

; Send message
; Input: AL = target system ID
;        AH = message type
;        RSI = message data pointer
;        RCX = message data length
; Output: CF = 1 if sent, CF = 0 if queue full

mov al, SYS_ID_FSM        ; Target: FSM
mov ah, MSG_TYPE_INPUT    ; Type: Input message
mov rsi, message_data     ; Data pointer
mov rcx, message_length   ; Data length
call braincontroller_send

braincontroller_process

Process messages in the queue.

; Process messages
call braincontroller_process

; Routes messages to appropriate subsystems
; Handles message queue management

braincontroller_main_loop

Main kernel loop (runs forever).

; Start main loop
call braincontroller_main_loop

; Continuously:
; - Processes messages
; - Handles system events
; - Manages subsystem lifecycle

Integration

System Call Integration

The Brain Controller integrates with Chapp-E's system call infrastructure:

  • SYS_SEND_MSG (0x100): Routes through Brain Controller
  • SYS_RECV_MSG (0x101): Receives messages from Brain Controller
  • SYS_GET_STATE (0x102): Queries Brain Controller state
  • SYS_SET_STATE (0x103): Sets Brain Controller state

Boot Process

The Brain Controller is initialized during kernel startup:

  1. kernel_main calls braincontroller_init
  2. Brain Controller initializes all subsystems
  3. Boot checklist verifies initialization
  4. braincontroller_main_loop starts

File Locations

  • 64-bit Implementation: neural/braincontroller/braincontroller_64.asm
  • Kernel Entry Point: neural/braincontroller/kernel_main.asm
  • Documentation: neural/braincontroller/README.md
  • Integration Guide: neural/braincontroller/INTEGRATION.md

Related Documentation