# T8-3.4: Guest-Services Partition **Track:** T8-3.4 **Status:** IN PROGRESS **Date:** 2026-07-12 --- ## Overview The guest-services partition is a dedicated partition that provides shared services to all guests. It acts as a trusted intermediary for device emulation, shared resources, and inter-guest communication. --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ UniversalisOS Hypervisor (EL2) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest-Services Partition (Partition 255) │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ Device Emulation │ │ │ │ │ │ - virtio-blk, virtio-net, virtio-console │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ Shared Services │ │ │ │ │ │ - Time service │ │ │ │ │ │ - Random number service │ │ │ │ │ │ - Logging service │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ Inter-Guest Communication │ │ │ │ │ │ - ARINC-653 sampling ports │ │ │ │ │ │ - Shared memory management │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 0: musl POSIX Personality │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 1: Android (AOSP) │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 2: Android (LineageOS) │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Guest 3: Android (GrapheneOS) │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Services Provided ### 1. Device Emulation The guest-services partition provides device emulation for all guests: | Device | Service | Guests | |--------|---------|--------| | virtio-blk | Block device emulation | All | | virtio-net | Network device emulation | All | | virtio-console | Console device emulation | All | | virtio-rng | Random number generation | All | ### 2. Shared Services | Service | Description | API | |---------|-------------|-----| | Time | Monotonic time source | `guest_service_get_time()` | | Random | Secure random numbers | `guest_service_get_random()` | | Logging | Centralized logging | `guest_service_log()` | | Health | Health monitoring | `guest_service_health()` | ### 3. Inter-Guest Communication | Mechanism | Description | API | |-----------|-------------|-----| | Sampling ports | ARINC-653 ports | `guest_service_port_write/read()` | | Shared memory | Explicit shared regions | `guest_service_shm_create/read/write()` | | Message queues | Priority-based messaging | `guest_service_mq_send/receive()` | --- ## Security Model ### Trust Boundary ``` ┌─────────────────────────────────────────────────────────────┐ │ TRUSTED: Guest-Services Partition │ │ - Runs at EL1 with hypervisor privileges │ │ - Can access all guest memory (for device emulation) │ │ - Mediates all inter-guest communication │ ├─────────────────────────────────────────────────────────────┤ │ UNTRUSTED: Guest Partitions │ │ - Run at EL1 with guest privileges │ │ - Cannot access other guest memory │ │ - Must use guest-services for shared resources │ └─────────────────────────────────────────────────────────────┘ ``` ### Isolation - Guest-services partition is **trusted** but **isolated** from guests - Guests cannot directly access guest-services memory - All communication via hypercalls or shared memory (explicit) - Guest-services cannot be compromised by guests --- ## Implementation ### Guest-Services Partition Config ```c /* Guest-services partition configuration */ guest_services_config_t services_config = { .partition_id = 255, /* Reserved partition ID */ .memory_size = 256 * 1024 * 1024, /* 256M */ .priority = 0, /* Highest priority */ .services = { .device_emulation = true, .shared_services = true, .inter_guest_comm = true, }, }; ``` ### Service Registration ```c /* Register a service */ int guest_service_register(const char* name, guest_service_handler_t handler); /* Unregister a service */ int guest_service_unregister(const char* name); /* Call a service */ int guest_service_call(const char* name, void* args, void* result); ``` --- ## API ### Device Emulation ```c /* virtio-blk */ int guest_service_vblk_read(uint32_t guest_id, uint64_t sector, void* buffer, uint32_t count); int guest_service_vblk_write(uint32_t guest_id, uint64_t sector, const void* buffer, uint32_t count); /* virtio-net */ int guest_service_vnet_send(uint32_t guest_id, const void* packet, uint32_t len); int guest_service_vnet_receive(uint32_t guest_id, void* buffer, uint32_t* len); /* virtio-console */ int guest_service_vconsole_write(uint32_t guest_id, const char* str); int guest_service_vconsole_read(uint32_t guest_id, char* buffer, uint32_t* len); ``` ### Shared Services ```c /* Time service */ uint64_t guest_service_get_time(void); /* Random service */ int guest_service_get_random(void* buffer, uint32_t len); /* Logging service */ int guest_service_log(uint32_t guest_id, const char* message); /* Health service */ int guest_service_health(uint32_t guest_id, uint32_t* status); ``` ### Inter-Guest Communication ```c /* Sampling ports */ int guest_service_port_write(uint32_t port_id, const void* data, uint32_t len); int guest_service_port_read(uint32_t port_id, void* buffer, uint32_t* len); /* Shared memory */ int guest_service_shm_create(uint64_t addr, uint32_t size, uint32_t guests); int guest_service_shm_read(uint64_t addr, void* buffer, uint32_t len); int guest_service_shm_write(uint64_t addr, const void* data, uint32_t len); /* Message queues */ int guest_service_mq_send(uint32_t queue_id, const void* message, uint32_t len, uint32_t priority); int guest_service_mq_receive(uint32_t queue_id, void* buffer, uint32_t* len, uint32_t* priority); ``` --- ## Implementation Files | File | Purpose | |------|---------| | `kernel/src/core/abi/uos_guest_services.h` | Guest-services API | | `kernel/src/core/abi/uos_guest_services.cpp` | Guest-services implementation | | `kernel/src/core/abi/uos_fleet.h` | Fleet management | | `kernel/src/core/abi/uos_separation_model.h` | Separation model | --- ## Verification - [ ] Guest-services partition boots successfully - [ ] Device emulation works for all guests - [ ] Shared services work correctly - [ ] Inter-guest communication works - [ ] Security model enforced - [ ] Isolation audit passes --- ## TODO - [ ] Implement actual device emulation (virtio-blk, virtio-net, virtio-console) - [ ] Implement shared services (time, random, logging, health) - [ ] Implement inter-guest communication (sampling ports, shared memory, message queues) - [ ] Add service registration/deregistration - [ ] Add service discovery - [ ] Add service access control - [ ] Add service monitoring - [ ] Add service health checks --- ## References - `universalisos/docs/T8-3.1_FLEET_TOOLING.md` — Fleet tooling - `universalisos/docs/T8-3.2_SEPARATION_MODEL.md` — Separation model - `universalisos/docs/T8-3.3_MULTI_ANDROID.md` — Multi-Android architecture