universalisos/COMPONENTS.md

# PikeOS Component Categorization and Architecture

## Overview

This document provides comprehensive categorization of PikeOS 5.0 components by functionality and safety-critical level, establishing the foundation for Aurelio cyber-physical system architecture and component orchestration.

## Component Architecture Overview

### Multi-Layer Architecture

```
┌─────────────────────────────────────────────┐
│  APPLICATION LAYER                           │
│  (User Applications, Services)              │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  PIKEOS API LAYER                            │
│  (System Calls, Component Interfaces)        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  KERNEL CORE LAYER                           │
│  (Scheduler, Memory, IPC, Virtualization)    │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  HARDWARE ABSTRACTION LAYER (HAL)            │
│  (Drivers, Device Management)               │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  HARDWARE LAYER                              │
│  (Physical Processors, Memory, I/O)          │
└─────────────────────────────────────────────┘
```

## Component Categorization by Functionality

### 1. SCHEDULER SUBSYSTEM

#### Core Components
- **`sched.h`**: Main scheduler interface and thread management
- **`sched_deadline.h`**: Deadline-based scheduling support
- **`sched_readyq.h`**: Ready queue management
- **`sched_timeout.h`**: Timeout and time management
- **`sched_types.h`**: Scheduler data types and structures

#### Safety-Critical Level: **ASIL-D (Highest)**

**Key Features**:
```c
// Time partitioning and preemptive priority scheduling
extern void schedule(void);
extern void thread_wait(timeout_t timeout);
extern void thread_wakeup(thread_t *thread);
extern void thread_yield(void);
```

**Safety Mechanisms**:
- **Deterministic Scheduling**: Time partitioning for real-time guarantees
- **Preemption Protocols**: Well-defined preemption points
- **Priority Management**: Priority inheritance to prevent priority inversion
- **Deadline Enforcement**: Deadline-based scheduling for time-critical tasks
- **Critical Section Protection**: Fine-grained locking protocols

**Aurelio Integration**:
```python
class AurelioScheduler:
    def schedule_thread(self, thread: AurelioThread, deadline: Deadline):
        """Schedule Aurelio agent thread with safety guarantees"""
        self.validate_deadline(deadline)
        self.assign_time_partition(thread)
        self.enable_preemption_monitoring(thread)
```

### 2. MEMORY MANAGEMENT SUBSYSTEM

#### Core Components
- **`mm_kmem.h`**: Kernel memory management
- **`hm.h`**: Heap manager (main memory allocation)
- **`hm_lookup.h`**: Heap management lookup tables
- **`hm_dump.h`**: Heap debugging and diagnostics
- **`gc.h`**: Garbage collection for memory reclamation
- **`glock_types.h`**: Global locking for memory operations

#### Safety-Critical Level: **ASIL-D**

**Key Features**:
```c
// Memory allocation with safety checks
extern void *kmalloc(size_t size);
extern void kfree(void *ptr);
extern void heap_validate(void);
extern void garbage_collect(void);
```

**Safety Mechanisms**:
- **Bounds Checking**: Pointer validation before allocation
- **Heap Protection**: Guard pages and canaries for corruption detection
- **Memory Partitioning**: Separate memory domains for different safety levels
- **Garbage Collection**: Automatic memory reclamation with safety checks
- **Global Locking**: Atomic operations for memory protection

**Memory Safety Patterns**:
```c
// PikeOS memory safety
P4X_STAND_CHECK_PTR(ptr, size);  // Pointer validation
if (ALIGNED2(size_t, ptr)) {      // Alignment checking
    // Safe memory operations
}
```

### 3. INTER-PROCESS COMMUNICATION (IPC)

#### Core Components
- **`ipc.h`**: Main IPC interface
- **`ipc_types.h`**: IPC data structures
- **`sys_ipc.h`**: System call interface for IPC
- **`comm.h`**: Communication primitives
- **`event.h`**: Event and notification system
- **`event_types.h`**: Event data types

#### Safety-Critical Level: **ASIL-D**

**Key Features**:
```c
// Thread-safe IPC operations
extern int ipc_send(thread_t *dest, void *msg, size_t len);
extern int ipc_receive(thread_t *src, void *msg, size_t len);
extern void ipc_mask_update(thread_t *thread, ipc_mask_t mask);
```

**Safety Mechanisms**:
- **Thread Locking**: Fine-grained locking with thread-specific locks
- **Queue Management**: Safe receive queue with ADT list operations
- **Mask Management**: IPC mask for selective communication
- **Deadlock Prevention**: Lock ordering protocols
- **Event Notification**: Safe event delivery mechanism

**IPC Safety Protocols**:
```c
// PikeOS IPC protocol
LOCK "thr"                      // Acquire thread lock
perform_ipc_operation()        // IPC operation
UNLOCK "thr"                    // Release thread lock
validate_receive_queue()         // Queue validation
```

### 4. VIRTUAL MACHINE MANAGEMENT

#### Core Components
- **`vm.h`**: Core virtual machine interface
- **`vm_file.h`**: VM file system integration
- **`vm_fp.h`**: Floating point virtualization
- **`vm_console.h`**: Console management for VMs
- **`vm_core_types.h`**: VM core data structures
- **`vm_init.h`**: VM initialization

#### Safety-Critical Level: **ASIL-B**

**Key Features**:
```c
// Virtual machine management
extern int vm_create(vm_config_t *config);
extern int vm_destroy(vm_t *vm);
extern int vm_switch(vm_t *vm);
extern void vm_protect_memory(vm_t *vm, void *addr, size_t size);
```

**Safety Mechanisms**:
- **Memory Partitioning**: Separate address spaces for different VMs
- **Context Switching**: Safe context saving and restoration
- **Resource Isolation**: CPU time and memory allocation per VM
- **Device Virtualization**: Safe device access through virtualization
- **Privilege Separation**: Different privilege levels for VMs

### 5. DEVICE MANAGEMENT (HAL)

#### Core Components
- **`dev.h`**: Core device management interface
- **`kdev_alert.h`**: Device alert and notification system
- **`kglobal_per_cpu.h`**: Per-CPU kernel data
- **`p4arch_proto.h`**: PikeOS architecture protocols

#### Safety-Critical Level: **ASIL-D**

**Key Features**:
```c
// Device management with safety checks
extern int device_register(dev_t *dev);
extern int device_unregister(dev_t *dev);
extern ssize_t device_read(dev_t *dev, void *buf, size_t count);
extern ssize_t device_write(dev_t *dev, const void *buf, size_t count);
```

**Safety Mechanisms**:
- **Device Registration**: Centralized device management
- **Permission Checking**: Access control for device operations
- **Bounds Validation**: Buffer size validation for I/O operations
- **Atomic Operations**: Safe device register access

### 6. SYNCHRONIZATION PRIMITIVES

#### Core Components
- **`ulock.h`**: User-level locking primitives
- **`ulock_types.h`**: Lock data types
- **`sys_ulock.h`**: System call interface for user locks
- **`glock_types.h`**: Global locking types
- **`unblock.h`**: Thread unblocking mechanisms

#### Safety-Critical Level: **ASIL-D**

**Key Features**:
```c
// Safe locking primitives
extern int ulock_init(ulock_t *lock);
extern int ulock_acquire(ulock_t *lock, timeout_t timeout);
extern int ulock_release(ulock_t *lock);
extern int ulock_try_acquire(ulock_t *lock);
```

**Safety Mechanisms**:
- **Deadlock Prevention**: Lock ordering protocols
- **Priority Inheritance**: Priority inheritance for priority inversion prevention
- **Timeout Protection**: Timeout-based lock acquisition
- **Atomic Operations**: Hardware atomic operations for lock implementation

### 7. SYSTEM SERVICES

#### Core Components
- **`console.h`**: Console and logging services
- **`debugmon.h`**: Debug monitoring interface
- **`except.h`**: Exception handling framework
- **`exit.h`**: System exit and cleanup
- **`exregs.h`**: Extended register management

#### Safety-Critical Level: **ASIL-B**

**Key Features**:
```c
// System services
extern void console_print(const char *msg);
extern void debug_monitor(const char *event);
extern void exception_handler(int exception_num);
extern void system_exit(int status);
```

## Component Safety Matrix

| Subsystem | ASIL Level | Safety Mechanisms | Failure Impact |
|-----------|-----------|-------------------|----------------|
| **Scheduler** | ASIL-D | Deterministic scheduling, priority inheritance | System-wide timing failure |
| **Memory Management** | ASIL-D | Bounds checking, heap protection, garbage collection | Memory corruption, system crash |
| **IPC** | ASIL-D | Thread locking, queue validation, deadlock prevention | Communication failure, deadlock |
| **Virtual Machine** | ASIL-B | Memory partitioning, context isolation | VM isolation failure |
| **Device Management** | ASIL-D | Permission checks, bounds validation | Device access violations |
| **Synchronization** | ASIL-D | Priority inheritance, timeout protection | Priority inversion, deadlock |
| **System Services** | ASIL-B | Exception handling, safe exit | System instability |

## Multi-Architecture Component Support

### Architecture-Specific Components

```bash
# PowerPC e500/e500mc/e5500 variants
ukernel-ppc_e500/
ukernel-ppc_e500mc/
ukernel-ppc_e500mc-4g/
ukernel-ppc_e5500/

# ARM variants
ukernel-arm_v7hf/
ukernel-arm_v8hf/

# x86 variants
ukernel-x86_amd64/
```

**Architecture-Safety Mechanisms**:
- **Cache Coherency**: Architecture-specific cache management
- **Atomic Operations**: Hardware-supported atomic operations
- **Memory Barriers**: Architecture-specific memory ordering
- **Interrupt Handling**: Architecture-specific interrupt management

## Component Interface Standardization

### Standard Component Interface Pattern

```c
// Standard PikeOS component interface
typedef struct {
    const char *name;           // Component name
    const char *description;    // Component description
    safety_level_t asil_level;   // Safety-critical level
    
    // Standard lifecycle operations
    int (*init)(component_config_t *config);
    int (*start)(void);
    int (*stop)(void);
    int (*cleanup)(void);
    
    // Safety operations
    int (*validate)(void);
    int (*safety_check)(void);
    int (*error_handler)(int error_code);
    
    // Communication interfaces
    int (*send_message)(component_id_t dest, void *msg, size_t len);
    int (*receive_message)(component_id_t src, void *msg, size_t len);
    
    // Resource management
    resource_table_t resources;
    dependency_table_t dependencies;
    
} pikeos_component_t;
```

## Type-1 Hypervisor Architecture

### Virtual Machine Context Structure

```c
// PikeOS type-1 hypervisor context
typedef struct {
    // CPU context
    cpu_registers_t registers;
    fpu_registers_t fpu_state;
    
    // Memory management
    page_table_t *page_tables;
    memory_domain_t *memory_domain;
    
    // Virtual device state
    virtual_devices_t virtual_devices;
    
    // Safety state
    vm_safety_state_t safety_state;
    
    // Resource allocation
    time_partition_t time_partition;
    cpu_quota_t cpu_quota;
    
} vm_context_t;
```

### Hypervisor Safety Features

1. **Memory Isolation**: Complete memory separation between VMs
2. **CPU Time Partitioning**: Guaranteed CPU time allocation
3. **I/O Virtualization**: Safe device access through hypervisor
4. **Privilege Levels**: Different privilege levels for kernel and applications
5. **Interrupt Virtualization**: Safe interrupt delivery to VMs

## Aurelio Component Integration

### Mapping PikeOS Components to Aurelio Architecture

#### 1. **Scheduler → Aurelio Thread Orchestrator**
```python
class AurelioThreadOrchestrator:
    """Maps PikeOS scheduler patterns to Aurelio"""
    def __init__(self):
        self.time_partitioning = TimePartitioning()
        self.priority_manager = PriorityManager()
        self.preemption_monitor = PreemptionMonitor()
    
    def schedule_agent(self, agent: AurelioAgent):
        """Schedule agent with PikeOS-style safety"""
        self.assign_time_partition(agent)
        self.manage_priority(agent)
        self.monitor_preemption(agent)
```

#### 2. **Memory Management → Aurelio Memory Safety**
```python
class AurelioMemoryManager:
    """PikeOS memory safety patterns for Aurelio"""
    def __init__(self):
        self.bounds_checker = BoundsChecker()
        self.heap_protector = HeapProtector()
        self.garbage_collector = GarbageCollector()
    
    def allocate_safe(self, size: int) -> Optional[bytes]:
        """Safe allocation with PikeOS-style checks"""
        if not self.bounds_checker.validate(size):
            return None
        return self.heap_protector.allocate(size)
```

#### 3. **IPC → Aurelio Agent Communication**
```python
class AurelioAgentCommunication:
    """PikeOS IPC patterns for agent communication"""
    def __init__(self):
        self.thread_locker = ThreadSafeLocking()
        self.queue_manager = SafeQueueManager()
        self.mask_manager = IPCMaskManager()
    
    def send_message_safe(self, dest: Agent, message: Message):
        """Thread-safe agent communication"""
        with self.thread_locker.lock():
            self.validate_message(message)
            self.queue_manager.enqueue(dest, message)
```

## Component Dependencies and Relationships

### Dependency Graph

```
┌─────────────────┐
│  Applications   │
└────────┬────────┘
         │
┌────────▼────────┐
│   System Calls   │
└────────┬────────┘
         │
┌────────▼────────┐     ┌──────────────────┐
│    Scheduler    │◄────│   Memory Manager  │
└────────┬────────┘     └──────────────────┘
         │                     │
┌────────▼────────┐     ┌───▼──────────────┐
│      IPC         │─────▶│  Synchronization│
└────────┬────────┘     └──────────────────┘
         │
┌────────▼────────┐     ┌──────────────────┐
│ Virtual Machines │◄────│   Device Mgmt    │
└────────┬────────┘     └──────────────────┘
         │
┌────────▼────────┐
│  HAL / Drivers  │
└────────┬────────┘
         │
┌────────▼────────┐
│    Hardware     │
└─────────────────┘
```

## Component Safety Validation

### Runtime Safety Checks

```c
// Production-safe component validation
#define COMPONENT_VALIDATE(comp) \
    do { \
        if (!(comp)->validate()) { \
            warn((comp)->safety_check()); \
            component_safe_shutdown(comp); \
        } \
    } while(0)

// Component lifecycle with safety
int component_start_lifecycle(pikeos_component_t *comp) {
    COMPONENT_VALIDATE(comp);
    
    if (comp->init(comp->config) != 0) {
        return -1;
    }
    
    if (comp->safety_check() != 0) {
        comp->cleanup();
        return -2;
    }
    
    return comp->start();
}
```

## Component Configuration Tables

### Standard Configuration Structure

```c
// PikeOS component configuration (from XSD analysis)
typedef struct {
    // Component identification
    const char *name;
    component_version_t version;
    
    // Safety parameters
    safety_level_t asil_level;
    timeout_t max_response_time;
    size_t max_memory_usage;
    
    // Resource allocation
    cpu_quota_t cpu_quota;
    memory_quota_t memory_quota;
    
    // Dependencies
    component_id_t dependencies[MAX_DEPS];
    size_t dependency_count;
    
    // Communication interfaces
    ipc_mask_t ipc_mask;
    event_mask_t event_mask;
    
    // Safety callbacks
    int (*error_handler)(int error_code);
    int (*safety_monitor)(void);
    
} component_config_t;
```

## Key Architectural Insights

### 1. Layered Safety Architecture

**PikeOS implements defense-in-depth**:
- Hardware-level memory protection (MMU)
- Hypervisor-level VM isolation
- Kernel-level component validation
- Application-level safety checks

### 2. Fine-Grained Locking Strategy

**PikeOS uses fine-grained locking** for:
- Thread-specific locks (thr)
- Component-specific locks
- Fine-grained critical sections
- Well-defined lock ordering protocols

### 3. Time Partitioning

**Deterministic real-time guarantees**:
- Fixed time slices for each thread
- Preemption points at well-defined locations
- Deadline-aware scheduling
- Priority inheritance for priority inversion prevention

### 4. Memory Safety Patterns

**Comprehensive memory protection**:
- Pointer bounds checking (P4X_STAND_CHECK_PTR)
- Alignment-safe operations (ALIGNED2 macro)
- Heap protection with guard pages
- Garbage collection with safety checks

## Component Migration to Aurelio

### Aurelio Component Architecture

```python
class AurelioPikeOSComponent:
    """PikeOS-inspired component for Aurelio"""
    
    def __init__(self, config: ComponentConfig):
        self.name = config.name
        self.asil_level = config.asil_level
        self.dependencies = config.dependencies
        
        # PikeOS-style safety mechanisms
        self.safety_validator = SafetyValidator()
        self.lock_manager = FineGrainedLocking()
        self.resource_manager = ResourcePartitioning()
    
    def lifecycle_start(self):
        """Start component with PikeOS-style safety"""
        self.safety_validator.validate_preconditions()
        self.resource_manager.allocate_resources()
        self.lock_manager.acquire_component_locks()
        
        try:
            self.start_component()
        except SafetyError as e:
            self.handle_safety_failure(e)
            self.enter_safe_state()
    
    def ipc_send_safe(self, dest: 'AurelioPikeOSComponent', message: Message):
        """Thread-safe IPC inspired by PikeOS"""
        with self.lock_manager.thread_lock():
            self.validate_message(message)
            self.check_ipc_mask(dest)
            dest.queue_manager.enqueue(message)
```

## Next Steps

### Phase 6: Aurelio Brain Test

1. **Validate Aurelio Understanding** of PikeOS component architecture
2. **Test Component Recognition** capabilities
3. **Verify Safety Pattern Mapping**
4. **Test Component Integration** with Aurelio orchestration

---

**Status**: ✅ **Phase 5 Complete**

This component categorization establishes PikeOS as a comprehensive safety-critical type-1 hypervisor with well-defined architectural patterns that can be directly mapped to Aurelio cyber-physical system development.

**Key Architectural Patterns for Aurelio**:
- Layered safety architecture with defense-in-depth
- Fine-grained locking for concurrent systems
- Time partitioning for real-time guarantees
- Comprehensive memory safety mechanisms
- Well-defined component interfaces and protocols