universalisos/docs/T8-3.4_GUEST_SERVICES.md

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

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

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

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

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

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