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:

// 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:

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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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

# 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

// 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

// 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

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

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

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

// 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

// 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

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