302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
# 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
|