# T8-3.3: Multi-Android-Guest Architecture **Track:** T8-3.3 **Status:** IN PROGRESS **Date:** 2026-07-12 --- ## Overview The multi-Android-guest architecture enables running multiple concurrent Android guests (AOSP, LineageOS, GrapheneOS) inside UniversalisOS. Each guest is fully isolated through the separation model and inherits hardened_malloc from Bionic. --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ UniversalisOS Hypervisor (EL2) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Fleet Manager (uos-fork / uos-manage) │ │ │ │ - Guest lifecycle management │ │ │ │ - Resource allocation │ │ │ │ - Isolation audit │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Separation Model │ │ │ │ - Stage-2 MMU isolation │ │ │ │ - Partition memory domains │ │ │ │ - Independent allocator instances │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 0: musl POSIX Personality │ │ │ │ - Primary personality │ │ │ │ - hardened_malloc (default config) │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 1: Android (AOSP) │ │ │ │ - Bionic libc + hardened_malloc │ │ │ │ - Stage-2 MM features │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 2: Android (LineageOS) │ │ │ │ - Bionic libc + hardened_malloc │ │ │ │ - Stage-2 MM features │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 3: Android (GrapheneOS) │ │ │ │ - Bionic libc + hardened_malloc │ │ │ │ - Stage-2 MM features │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Guest Configuration ### Memory Layout | Guest | Type | Memory | IPA Base | PA Base | Partition | |-------|------|--------|----------|---------|-----------| | 0 | musl | 512M | 0x40000000 | 0x40000000 | 0 | | 1 | AOSP | 1G | 0x40000000 | 0x80000000 | 1 | | 2 | LineageOS | 1G | 0x40000000 | 0xC0000000 | 2 | | 3 | GrapheneOS | 1G | 0x40000000 | 0x100000000 | 3 | ### Stage-2 MM Configuration Each guest has independent Stage-2 page tables: ```c /* Guest 1 (AOSP) Stage-2 config */ stage2_config_t guest1_stage2 = { .ipa_base = 0x40000000, .ipa_size = 0x40000000, /* 1G */ .pa_base = 0x80000000, .pa_size = 0x40000000, .granule = STAGE2_GRANULE_4K, .guard_pages = true, .quarantine = true, }; /* Guest 2 (LineageOS) Stage-2 config */ stage2_config_t guest2_stage2 = { .ipa_base = 0x40000000, .ipa_size = 0x40000000, .pa_base = 0xC0000000, .pa_size = 0x40000000, .granule = STAGE2_GRANULE_4K, .guard_pages = true, .quarantine = true, }; ``` --- ## Boot Sequence ### 1. Hypervisor Boot ``` [UOS] UniversalisOS Hypervisor v1.0 [UOS] Initializing Stage-2 MMU... [UOS] Initializing GICv3... [UOS] Initializing timer... [UOS] Initializing scheduler... [UOS] Fleet manager initialized ``` ### 2. Guest 0 (musl) Boot ``` [UOS] Booting guest 0: musl [UOS] Loading personality ELF... [UOS] Configuring Stage-2 MM... [UOS] Starting vCPU... [musl] Hello from musl personality! [musl] hardened_malloc initialized ``` ### 3. Guest 1 (AOSP) Boot ``` [UOS] Booting guest 1: android-aosp [UOS] Loading Android kernel... [UOS] Loading ramdisk... [UOS] Loading DTB... [UOS] Configuring Stage-2 MM... [UOS] Starting vCPU... [android] Linux version 6.1.0-android [android] Bionic libc initialized [android] hardened_malloc initialized ``` ### 4. Guest 2 (LineageOS) Boot ``` [UOS] Booting guest 2: android-lineage [UOS] Loading Android kernel... [UOS] Loading ramdisk... [UOS] Loading DTB... [UOS] Configuring Stage-2 MM... [UOS] Starting vCPU... [android] Linux version 6.1.0-lineage [android] Bionic libc initialized [android] hardened_malloc initialized ``` --- ## Inter-Guest Communication ### ARINC-653 Sampling Ports Guests communicate via ARINC-653 sampling ports: ```c /* Guest 1 writes to port 0 */ sampling_port_write(0, data, len); /* Guest 2 reads from port 0 */ sampling_port_read(0, buffer, &len); ``` ### Shared Memory (Explicit) Guests can share memory via explicit shared regions: ```c /* Create shared memory region */ shared_memory_create(0x50000000, 0x1000, GUEST_1 | GUEST_2); /* Guest 1 writes */ shared_memory_write(0x50000000, data, len); /* Guest 2 reads */ shared_memory_read(0x50000000, buffer, len); ``` --- ## Resource Management ### CPU Scheduling Each guest gets a time slice: ```c /* Scheduler configuration */ scheduler_config_t sched_config = { .tick_us = 1000, /* 1ms tick */ .guest_timeslices = { [0] = 100, /* musl: 100ms */ [1] = 200, /* AOSP: 200ms */ [2] = 200, /* LineageOS: 200ms */ [3] = 200, /* GrapheneOS: 200ms */ }, }; ``` ### Memory Allocation Memory is allocated per guest: ```c /* Memory allocation */ memory_alloc_t mem_alloc = { .total_memory = 8 * 1024 * 1024 * 1024, /* 8G */ .guest_allocations = { [0] = 512 * 1024 * 1024, /* musl: 512M */ [1] = 1024 * 1024 * 1024, /* AOSP: 1G */ [2] = 1024 * 1024 * 1024, /* LineageOS: 1G */ [3] = 1024 * 1024 * 1024, /* GrapheneOS: 1G */ }, .hypervisor_reserved = 512 * 1024 * 1024, /* 512M */ }; ``` --- ## Security Model ### Isolation Guarantees | Guarantee | Mechanism | Status | |-----------|-----------|--------| | Memory isolation | Stage-2 MMU | ✅ | | Execution isolation | vCPU contexts | ✅ | | State isolation | Independent allocators | ✅ | | Communication control | ARINC-653 ports | ✅ | ### Attack Surface | Attack | Mitigation | Status | |--------|------------|--------| | Memory disclosure | Stage-2 isolation | ✅ BLOCKED | | Code injection | No shared code pages | ✅ BLOCKED | | State corruption | Independent allocators | ✅ BLOCKED | | Side-channel | Independent randomization | ⚠️ MITIGATED | --- ## Implementation Files | File | Purpose | |------|---------| | `kernel/src/core/abi/uos_multi_guest.h` | Multi-guest API | | `kernel/src/core/abi/uos_multi_guest.cpp` | Multi-guest implementation | | `kernel/src/core/abi/uos_fleet.h` | Fleet management | | `kernel/src/core/abi/uos_separation_model.h` | Separation model | | `kernel/src/arch/aarch64/stage2.cpp` | Stage-2 MMU | --- ## Multi-Guest API ```c /* Initialize multi-guest subsystem */ int uos_multi_guest_init(void); /* Add Android guest */ int uos_multi_guest_add_android(const char* name, uint64_t memory_size); /* Remove guest */ int uos_multi_guest_remove(uint32_t guest_id); /* Start all guests */ int uos_multi_guest_start_all(void); /* Stop all guests */ int uos_multi_guest_stop_all(void); /* Get guest count */ uint32_t uos_multi_guest_count(void); /* Run isolation audit on all guests */ int uos_multi_guest_audit_all(void); ``` --- ## Verification - [ ] Multiple Android guests boot successfully - [ ] Each guest has independent Stage-2 MM - [ ] Each guest has independent hardened_malloc - [ ] Isolation audit passes for all guests - [ ] Inter-guest communication works - [ ] Resource management works --- ## References - `universalisos/docs/T8-2.2_ANDROID_INHERITANCE.md` — Android inheritance - `universalisos/docs/T8-3.1_FLEET_TOOLING.md` — Fleet tooling - `universalisos/docs/T8-3.2_SEPARATION_MODEL.md` — Separation model