# T8-2.2: hardened_malloc in Android Guests (Inheritance)

**Track:** T8-2.2  
**Status:** IN PROGRESS  
**Date:** 2026-07-12

---

## Overview

Android guests inherit hardened_malloc from Bionic (Android's libc). UniversalisOS does **not** rebuild hardened_malloc for Android; instead, it provides the Stage-2 MM features that hardened_malloc needs.

---

## Inheritance Model

```
┌─────────────────────────────────────────────────────────────┐
│  Android Guest (AOSP/LineageOS/GrapheneOS)                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Bionic libc                                        │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │  hardened_malloc (built-in)                 │   │   │
│  │  │  - CONFIG_SELF_INIT=false                   │   │   │
│  │  │  - N_ARENA=1                                │   │   │
│  │  │  - Uses Android.bp build system             │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                          │                                  │
│                          ▼                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  UniversalisOS Stage-2 MM Features                  │   │
│  │  - Guard pages (mm_mmap_guard)                      │   │
│  │  - High map count (mm_set_map_count)                │   │
│  │  - Quarantine (mm_quarantine)                       │   │
│  │  - Aligned mappings (mm_mmap_aligned)               │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## What UniversalisOS Provides

### 1. Stage-2 MM Features (T8-2.1)

| Feature | hardened_malloc Usage | UOS Implementation |
|---------|----------------------|-------------------|
| Guard pages | `pages.c:13-30` emulates with PROT_NONE VMAs | `mm_mmap_guard()` native |
| High map count | Creates many VMAs (guard + per-class regions) | `MM_MAX_MAP_COUNT = 1M` |
| Quarantine | `h_malloc.c` quarantine queues | `mm_quarantine()` native |
| Aligned mappings | Size-class alignment | `mm_mmap_aligned()` native |
| mremap expansion | `memory.c:92-110` uses mremap | `mm_mremap_ex()` native |

### 2. Page-Size Contract

- **AArch64:** 4 KiB translation granule ✅ compatible
- **riscv64 / armv7:** Must confirm 4 KiB granule
- hardened_malloc has compile-time `static_assert(PAGE_SIZE == 4096)`

### 3. Partition Isolation

Each Android guest gets:
- Independent Stage-2 address space
- Independent hardened_malloc instance (via Bionic)
- Independent random bases, quarantine queues, guard regions

---

## What UniversalisOS Does NOT Do

- ❌ Rebuild hardened_malloc for Android
- ❌ Replace Bionic's malloc
- ❌ Modify Android's build system
- ❌ Provide musl for Android guests

---

## Integration Points

### 1. Guest Boot

When an Android guest boots:
1. UOS loads the Android kernel + ramdisk
2. Android's init starts
3. Bionic initializes hardened_malloc (CONFIG_SELF_INIT=false)
4. hardened_malloc uses UOS Stage-2 MM features via hypercalls

### 2. Hypercall Interface

Android guests use the same POSIX_SVC_* hypercalls as the musl personality:
- `POSIX_SVC_MMAP_GUARD` → `mm_mmap_guard()`
- `POSIX_SVC_MMAP_ALIGNED` → `mm_mmap_aligned()`
- `POSIX_SVC_QUARANTINE` → `mm_quarantine()`

### 3. Memory Accounting

- Per-partition memory domains (`partition.h`)
- Accountable mappings tracked separately
- `mm_set_accountable_limit()` for RLIMIT_AS alternative

---

## Configuration

### Android Guest Config

```c
/* Bionic hardened_malloc config (from Android.bp) */
#define CONFIG_SELF_INIT false    /* Android initializes it */
#define CONFIG_N_ARENA 1          /* Single arena for Android */
#define CONFIG_ZERO_ON_FREE true
#define CONFIG_SLAB_CANARY true
#define CONFIG_REGION_QUARANTINE_RANDOM_LENGTH 256
#define CONFIG_REGION_QUARANTINE_QUEUE_LENGTH 1024
```

### UOS Stage-2 Config

```c
/* UOS personality-MM config for Android guests */
#define MM_MAX_MAP_COUNT 1048576u  /* 1M mappings */
#define MM_GUARD_DEFAULT_SIZE 1    /* 1 page guard */
#define MM_QUARANTINE_DEFAULT 256  /* 256 region quarantine */
```

---

## Verification

- [ ] Android guest boots with Bionic hardened_malloc
- [ ] hardened_malloc uses UOS Stage-2 MM features
- [ ] Guard pages work correctly
- [ ] Quarantine detects use-after-free
- [ ] Memory accounting per partition

---

## References

- `universalisos/docs/HARDENED_MALLOC.md` — Config matrix, page-size contract
- `universalisos/docs/T8-2.1_KERNEL_FEATURE_WISHLIST.md` — MM features
- `universalisos/third_party/hardened_malloc/` — Source code
- `platform_bionic/h_malloc_wrapper.cpp` — Android integration (external)