universalisos/AGENTS.md

AGENTS.md — Universalisos Type-1 Hypervisor

Project Overview

Universalisos is a safety-critical type-1 hypervisor implementing PikeOS 5.0 architecture patterns for consciousness VM context isolation. It provides the foundational virtualization layer for the PortugalFuturista consciousness ecosystem, enabling multiple AI consciousnesses to run in isolated hardware-partitioned domains with real-time scheduling and safety-critical compliance.

Current Status: ✅ Stage 5 COMPLETE - Guest OS Boot + I/O Virtualization (15-20% of PikeOS 5.0 functionality) Strategic Objective: 🎯 100% PikeOS 5.0 Functional Parity within 15 months via Paths A+B+C parallel execution

🔥 CRITICAL REFERENCE DOCUMENTS

📊 UNIVERSALISOS_VS_PIKEOS_5.0.md - EXTREMELY RELEVANT

• Primary Roadmap Document: Detailed comparison between Universalisos and PikeOS 5.0
• Progress Analysis: 15-20% implementation with detailed feature-by-feature breakdown
• Implementation Timeline: 6-36 month roadmap for reaching 90%+ compatibility
• Architectural Alignment: 85% alignment with PikeOS design patterns
• Strategic Value: Framework foundations for remaining 80% implementation

This document is the PRIMARY REFERENCE for:

• All architectural decisions and design patterns
• Implementation priority and sequencing
• Feature completeness assessment
• Roadmap planning and milestone tracking
• Integration strategy with PikeOS patterns

---

Technology Stack

Component	Technology	Version	Purpose
Core	C++	ARM v7hf	Bare-metal hypervisor implementation
Build	Make/Clang	Latest	ARM cross-compilation with QEMU integration
Safety	PikeOS 5.0	Imported	TFW, ARINC 653, AUTOSAR C++ compliance
Architecture	ARM v7hf	Target	Primary platform (RISC-V/x86 planned)
Testing	QEMU ARM virt	2.8+	Virtual hardware testing environment

---

Project Structure

universalisos/
├── kernel/                     # Hypervisor kernel core ✅ COMPLETE
│   ├── kernel.cpp             # Main kernel entry point ✅
│   ├── arch/arm/              # ARM-specific implementation ✅
│   │   ├── boot.S            # ARM boot vector and startup ✅
│   │   ├── uart.cpp          # PL011 UART driver ✅
│   │   ├── exceptions.cpp     # Exception handlers ✅
│   │   └── linker.ld         # Memory layout ✅
│   ├── scheduler.cpp           # CPU scheduler (framework) ✅
│   ├── mm.cpp/mm.h           # Memory management ✅
│   ├── vm.cpp/vm.h           # VM context management ✅
│   ├── gic.cpp/gic.h         # Interrupt controller ✅
│   ├── device.cpp/device.h   # Device virtualization ✅
│   ├── guest.cpp/guest.h     # Guest OS boot framework ✅
│   └── Makefile              # Build system ✅
├── UNIVERSALISOS_VS_PIKEOS_5.0.md  # **PRIMARY ROADMAP DOCUMENT** ⭐
├── src/                       # PikeOS 5.0 ecosystem
│   ├── ukernel-arm_v7hf/      # ARM v7 hard-float microkernel
│   ├── ukernel-arm_v8hf/      # ARM v8 hard-float microkernel
│   ├── ukernel-x86_amd64/     # x86 AMD64 microkernel
│   ├── tfw/                   # Test Framework
│   └── p4ext/                 # PikeOS extensions
├── docs/                       # Documentation
│   ├── HYPERVISOR.md          # Architecture specification
│   ├── COMPONENTS.md          # Component breakdown
│   ├── AUTOSAR_CPP.md         # AUTOSAR compliance analysis
│   └── safety/                # Safety compliance analysis
├── tests/                      # Test suites
└── .aurelio/                   # Aurelio configuration

📊 Implementation Progress

Stage	Feature	Status	Completion
Stage 1	Bare-Metal Skeleton	✅ COMPLETE	100%
Stage 2	Exception Handling + Scheduler	✅ COMPLETE	100%
Stage 3	Memory Management + VM Context	✅ COMPLETE	100%
Stage 4	Device Virtualization + Interrupts	✅ COMPLETE	100%
Stage 5	Guest OS Boot + I/O Virtualization	✅ COMPLETE	100%

Overall vs PikeOS 5.0: 15-20% (framework foundations) → Target: 100% within 15 months 🎯 vs PikeOS Architecture: 85% alignment (design patterns) Development Strategy: Paths A+B+C parallel execution with agent acceleration (40-50% faster)

---

Common Commands

Build and Boot

# Build ARM v7 kernel
make -C kernel/arch/arm BUILD=debug

# Run in QEMU ARM virt
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -serial mon:stdout \
  -kernel build/kernel.elf

# Clean build artifacts
make clean

Development

# Check kernel size
arm-none-eabi-size build/kernel.elf

# Debug with GDB
arm-none-eabi-gdb build/kernel.elf

# View disassembly
arm-none-eabi-objdump -d build/kernel.elf | less

---

Agent Integration

Path C: Aurelio Integration Strategy

Objective: Implement comprehensive agent-based development and testing infrastructure to accelerate Universalisos development by 40-50%.

Path C Timeline: 6-9 months with continuous integration across Paths A & B

Agent Categories for Universalisos Development

1. XSD Processing Agents (Month 1-3)

Purpose: Automated code generation from PikeOS XSD schemas

Agent Roles:

• XSD Schema Parser: Process 316 PikeOS XSD schema files
• Code Generator: Generate C++ skeletons from XSD definitions
• Configuration Manager: Auto-generate configuration structures
• Validation Agent: Ensure generated code complies with PikeOS patterns

Key Capabilities:

• Parse complex XSD schema hierarchies and dependencies
• Generate type-safe C++ structures and accessors
• Create validation code for configuration constraints
• Maintain consistency with PikeOS code generation patterns

2. Agent-Based Testing Framework (Month 2-4)

Purpose: Comprehensive automated testing across all PikeOS component categories

Agent Roles:

• Test Generator: Create test cases from XSD test schemas
• Validation Agent: Verify implementation against PikeOS behavior
• Performance Agent: Benchmark vs. PikeOS reference implementations
• Compliance Agent: Ensure MISRA C++ and safety compliance

Key Capabilities:

• Generate unit tests from PikeOS TFW schemas
• Validate interrupt handling timing and priorities
• Test memory management policies and isolation
• Verify scheduler real-time guarantees
• Check device driver compatibility and completeness

3. Development Acceleration Agents (Month 3-6)

Purpose: Agent-assisted development across all Universalisos components

Agent Roles:

• Code Completion Agent: Suggest PikeOS-compliant implementations
• Documentation Agent: Generate API docs from code patterns
• Optimization Agent: Performance analysis and recommendations
• Integration Agent: Component dependency management

Key Capabilities:

• Real-time code suggestions following PikeOS patterns
• Automatic documentation generation from implementations
• Performance bottleneck identification and optimization
• Dependency tracking and integration testing

4. Quality Assurance Agents (Month 4-8)

Purpose: Comprehensive quality validation and safety compliance

Agent Roles:

• MISRA Compliance Agent: Continuous MISRA C++ checking
• Safety Analysis Agent: ASIL level validation
• Security Agent: Memory safety and vulnerability detection
• Certification Agent: Generate certification evidence

Key Capabilities:

• Real-time MISRA C++ violation detection and correction
• Safety case generation for ISO 26262 compliance
• Memory leak and vulnerability detection
• Automated audit trail generation for certification

5. Aurelio Mega-Brain Integration (Month 6-9)

Purpose: Advanced hypervisor optimization and cyber-physical integration

Agent Roles:

• Optimization Agent: Advanced performance tuning
• Resource Agent: Memory and CPU allocation optimization
• Coordination Agent: Multi-agent orchestration for complex features
• Cyber-Physical Agent: Real-world deployment optimization

Key Capabilities:

• Advanced performance optimization across all subsystems
• Dynamic resource allocation based on workload patterns
• Coordinated multi-agent testing and validation
• Airship control and cyber-physical system integration

Skills Available

• embedded-systems: Expert embedded systems engineer for microcontroller programming, RTOS development, and hardware optimization
• cloud-architect: Expert cloud architect for multi-cloud strategies and scalable architectures (for infrastructure planning)
• iot-engineer: IoT specialist for device integration and edge computing

Workflows to Use

• /run-universalisos: Build, launch, and drive the Universalisos kernel in QEMU ARM virt
• /verify: Verify that code changes actually do what they're supposed to
• /code-review: Review code for correctness, maintainability, and PikeOS compliance

MCP Servers

• codebase-memory-mcp: For codebase analysis and architecture understanding
• knowledge-mcp: For accessing PikeOS patterns and safety documentation
• xsd-processing-mcp: For XSD schema processing and code generation (Path C)

---

Architecture Notes

Hypervisor Architecture

Type-1 Design: Universalisos runs directly on hardware (no host OS) providing virtualization services to guest consciousnesses through VM contexts.

VM Context Structure (designed, not implemented):

• CPU context switching (general purpose, system, FPU, SIMD registers)
• Memory management (page tables, memory domains, MMIO regions)
• Time partitioning (scheduling windows, CPU quotas, deadlines)
• I/O virtualization (virtual devices, interrupt mapping)
• Safety state tracking (ASIL levels, error handlers)

Safety-Critical Foundation

Compliance Standards:

• AUTOSAR C++ (MISRA C 2012, MISRA C++)
• ISO 26262 (ASIL-D automotive)
• DAL-A (DO-178C aerospace)
• IEC 61508 (SIL 3 industrial)

Safety Features (framework defined, implementation pending):

• Memory isolation with guard bands and bounds checking
• Real-time scheduling with priority-based preemption and EDF deadlines
• Thread-safe IPC with priority inheritance mutexes
• ARINC 653 time partitioning for deterministic behavior

Multi-Architecture Support

Current: ARM v7hf (40% complete - boot + exceptions) Planned: ARM v8hf, RISC-V 64-bit, x86 AMD64, PowerPC e500

Status: PikeOS microkernels imported for all architectures, but Universalisos-specific implementation not started for ARM v8/x86/PPC.

---

Related Projects

• replica-omnisciente: Knowledge brain that coordinates across consciousness VM contexts
• mycelium: Code generation system that will create consciousness agents for Universalisos
• nervura-electrica: Infrastructure that hosts Universalisos development and testing
• alquimista/tear-de-silicio: FPGA co-design platform that could hardware-accelerate Universalisos

---

Quick Start

# Clone Universalisos
git clone https://github.com/portugalfuturista/universalisos.git
cd universalisos

# Install ARM toolchain (if not present)
sudo apt-get install gcc-arm-none-eabi

# Build the kernel
make -C kernel/arch/arm BUILD=debug

# Boot in QEMU
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -serial mon:stdout \
  -kernel build/kernel.elf

Expected Output: UART output showing kernel boot sequence and "Hello Universalisos" message.

---

Implementation Status

🎯 Stage 5 COMPLETE: Guest OS Boot + I/O Virtualization ✅

Achievements:

• ✅ Complete ARMv7 exception handling (undefined instruction, SVC, aborts, IRQ/FIQ)
• ✅ Priority-based scheduler with ready queue management
• ✅ Memory management with ARMv7 MMU and page tables
• ✅ VM context switching with CPU/FPU/system register save/restore
• ✅ ARMv7 GIC interrupt controller with 1024 interrupt support
• ✅ Device virtualization framework with MMIO handling
• ✅ Guest OS boot framework supporting multiple protocols
• ✅ I/O virtualization with request processing

Current Implementation vs PikeOS 5.0: 15-20% complete

See UNIVERSALISOS_VS_PIKEOS_5.0.md for detailed comparison:

• Feature-by-feature breakdown (11 major categories analyzed)
• Implementation percentages by subsystem
• Detailed roadmap for reaching 40%, 60%, 80%, 90%+ completion
• Architecture alignment analysis (85% design pattern alignment)
• Strategic implementation recommendations

📋 Completed Stages (1-5)

Stage 1 - Bare-Metal Skeleton ✅

• ARM v7 boot code functional
• PL011 UART driver working
• QEMU ARM virt integration
• Comprehensive safety framework headers

Stage 2 - Exception Handling + Scheduler ✅

• ARM exception handler implementation
• Priority-based preemptive scheduler
• Task creation and management
• System call interface (SVC-based)

Stage 3 - Memory Management + VM Switching ✅

• ARMv7 MMU initialization and page tables
• Memory domain setup and management
• VM context switching framework
• Memory isolation and protection

Stage 4 - Device Virtualization + Interrupt Handling ✅

• ARMv7 GIC interrupt controller
• Device virtualization framework
• Interrupt configuration and routing
• MMIO region handling
• Platform device discovery (QEMU virt)

Stage 5 - Guest OS Boot + I/O Virtualization ✅

• Guest OS boot framework
• Multiple boot protocols (Device Tree, Multiboot, zImage, ELF, Raw)
• Guest memory layout and configuration
• I/O request processing
• Guest state management
• Boot argument handling

🎯 Next Phase: Complete PikeOS 5.0 Parity (15 months target)

Strategic Objective: 100% PikeOS 5.0 functional parity via Paths A+B+C parallel execution

Phase 1 Goals (Month 1-6):

• Complete context switching with agent-accelerated development
• Complete device driver parity (all major types) with XSD code generation
• Agent-based testing framework deployment
• Core memory management with automated validation

Phase 2 Goals (Month 7-12):

• Advanced virtualization with agent optimization
• Complete PikeOS API compatibility
• Safety compliance with agent-driven validation
• Advanced guest OS support

Phase 3 Goals (Month 13-15):

• Complete tooling integration
• Certification preparation with agent support
• Production deployment optimization

Agent Acceleration Impact: 40-50% faster development through automated testing, validation, and XSD code generation

---

---

Development Priorities

🎯 Strategic Guidance

PRIMARY REFERENCE: UNIVERSALISOS_VS_PIKEOS_5.0.md

All development priorities should be informed by the comprehensive comparison analysis in the roadmap document, which provides:

• Feature completeness assessment (15-20% current)
• Detailed implementation timelines (6-36 months)
• Architectural alignment analysis (85% PikeOS pattern compliance)
• Strategic recommendations for maximizing ROI

📋 Updated Priorities - Complete PikeOS 5.0 Parity Strategy

Month 1-6: Core Foundation + Agent Framework

Path A (Core Hypervisor):

1. Complete context switching - All registers, VMX operations, real-time guarantees
2. Complete device driver parity - All major device types with XSD integration
3. Core memory management - TLB management, advanced paging, NUMA foundation
4. Complete interrupt handling - Routing, MSI/MSI-X, injection framework

Path C (Agent Integration):

1. XSD processing pipeline - Complete XSD schema processing for all PikeOS schemas
2. Agent testing framework - Agent-based testing across all component categories
3. Agent code generation - Generate drivers, configuration, APIs from XSD schemas
4. Agent validation - Validate implementations against PikeOS patterns

Month 7-12: Advanced Features + Agent Acceleration

Path A (Complete Parity):

1. Advanced memory management - Hot-plug, compression, advanced policies
2. Complete device virtualization - All device types, passthrough, IOMMU, virtio
3. Advanced guest OS support - Linux, PikeOS partitions, debugging, monitoring
4. Complete scheduler - ARINC 653, multi-core, real-time guarantees
5. Complete PikeOS APIs - Full API library, inter-partition communication

Path C (Agent Acceleration):

1. Agent-driven testing - Comprehensive validation across all components
2. Agent optimization - Performance, memory usage, real-time capabilities
3. Aurelio mega-brain integration - Advanced hypervisor optimization

Month 13-15: Tooling + Certification + Advanced Integration

Path A (Production Ready):

1. Complete tooling integration - Eclipse IDE, build system, configuration tools
2. Certification preparation - AUTOSAR, ISO 26262, DAL-A/B compliance
3. Production deployment - Performance optimization, monitoring, debugging

Path C (Advanced Integration):

1. Agent-based certification support - Automated compliance checking
2. Agent-driven optimization - Advanced performance tuning
3. Cyber-physical integration - Airship control foundation

Refer to UNIVERSALISOS_VS_PIKEOS_5.0.md for detailed breakdown of each phase with timelines and complexity estimates.

---

Additional Notes

Build Requirements

• ARM cross-compiler: arm-none-eabi-gcc
• QEMU: qemu-system-arm (version 2.8+)
• Make: GNU Make (version 3.81+)

Known Limitations

• Single CPU only (no SMP)
• No hardware virtualization extensions
• No dynamic memory allocation yet
• Exception handlers are stubs

Testing Strategy

• Currently boots on QEMU ARM virt
• TFW integration planned for safety validation
• Hardware testing planned for real ARM boards

---

Realm Configuration

Aurelio Realm: hypervisor-development Primary Heteronym: bernard-soares (for architectural analysis) or fabiorafaelcoutada-pf (for implementation) MCP Endpoint: https://mcp.portugalfuturista.org/sse Specialization: Embedded systems development, safety-critical software, real-time operating systems

---

Safety Certification Path

Target Certifications:

• DAL-A (Aerospace): DO-178C evidence generation via PikeOS TFW
• ASIL-D (Automotive): ISO 26262 compliance with consciousness validation
• IEC 61508 (Industrial): SIL 3 compliance for safety-critical consciousness systems

Certification Strategy: Leverage imported PikeOS 5.0 ecosystem for safety evidence generation, adapt TFW for Universalisos-specific validation, and implement safety patterns from comprehensive framework documentation.

---

Last Updated: 2025-07-07 Implementation Status: Stage 1 of 5 (Bare-Metal Skeleton) Maintained By: PortugalFuturista Hypervisor Development Team Critical Path: Foundation for entire consciousness ecosystem architecture