# UniversalisOS API Reference

## Kernel Hypercall Interface

Guests communicate with the hypervisor through architecture-specific trap instructions. All hypercalls return a status code in the first return register.

### AArch64 HVC Interface

Guests issue `hvc #0x5500` (immediate = `'UOS'`). Call number in `x0`, arguments in `x1`-`x4`, return in `x0`.

**Source**: `kernel/src/arch/aarch64/inc/uos_hv_abi.h`

| Call # | Name | Args | Description |
|--------|------|------|-------------|
| 0x00 | `UOS_HV_PUTC` | char | Character output |
| 0x01 | `UOS_HV_PUTS` | IPA of NUL string | String output |
| 0x02 | `UOS_HV_GETTIME` | — | Get time (ticks) |
| 0x03 | `UOS_HV_YIELD` | — | Yield CPU |
| 0x04 | `UOS_HV_SHUTDOWN` | — | Shutdown (no return) |
| 0x05 | `UOS_HV_ACK_VTIMER` | — | Acknowledge virtual timer |
| 0x06 | `UOS_HV_GETC` | — | Character input (poll) |
| 0x07 | `UOS_HV_IRQ_ACK` | — | Acknowledge virtual IRQ |
| 0x08 | `UOS_HV_IRQ_ENABLE` | irq_num | Enable virtual IRQ |
| 0x09 | `UOS_HV_IRQ_DISABLE` | irq_num | Disable virtual IRQ |
| 0x0A | `UOS_HV_INFO` | — | Get HV identity/capabilities |
| 0x0B | `UOS_HV_GET_VCPU_ID` | — | Get vCPU ID |
| 0x0C | `UOS_HV_GET_PART_ID` | — | Get partition ID |
| 0x0D | `UOS_HV_GET_TICK_HZ` | — | Get ticks per second |
| 0x0E | `UOS_HV_PART_GET_STATUS` | part_id | ARINC-653 partition status |
| 0x0F | `UOS_HV_PART_SET_MODE` | part_id, mode | ARINC-653 set mode |
| 0x10 | `UOS_HV_ERROR_RAISE` | error_code | ARINC-653 raise error |
| 0x11 | `UOS_HV_ERROR_GET_STATUS` | — | ARINC-653 get error status |
| 0x12 | `UOS_HV_SAMPLING_CREATE` | port_id, max_msg_size | ARINC-653 sampling port create |
| 0x13 | `UOS_HV_SAMPLING_WRITE` | port_id, msg_ptr, msg_size | ARINC-653 sampling port write |
| 0x14 | `UOS_HV_SAMPLING_READ` | port_id, msg_ptr, buf_size | ARINC-653 sampling port read |
| 0x15 | `UOS_HV_VIRTIO_DISCOVER` | — | VirtIO device discovery |
| 0x17 | `UOS_HV_VIRTIO_GET_CONFIG` | dev_id, cfg_ptr | VirtIO get device config |
| 0x18 | `UOS_HV_CHECKPOINT` | slot_id | Checkpoint partition |
| 0x19 | `UOS_HV_VIRTIO_KICK` / `UOS_HV_RESTORE` | dev_id / slot_id | VirtIO kick or restore |

#### Return Codes (AArch64)

| Code | Name | Description |
|------|------|-------------|
| 0 | `UOS_HV_OK` | Success |
| -1 | `UOS_HV_EINVAL` | Bad argument |
| -2 | `UOS_HV_ENOSYS` | Unknown call number |
| -3 | `UOS_HV_EPERM` | Not permitted |
| -4 | `UOS_HV_EBUSY` | Resource busy |
| -5 | `UOS_HV_EAGAIN` | Would block / nothing pending |
| -6 | `UOS_HV_ENOMEM` | No resource |
| -7 | `UOS_HV_EFAULT` | Bad guest pointer |
| -8 | `UOS_HV_ENXIO` | No such device/irq |
| -9 | `UOS_HV_ETIMEDOUT` | Timed out |

#### Capability Bits

| Bit | Name | Description |
|-----|------|-------------|
| 0 | `UOS_HV_CAP_CONSOLE` | PUTC/PUTS/GETC |
| 1 | `UOS_HV_CAP_VTIMER` | Virtual timer |
| 2 | `UOS_HV_CAP_VIRQ` | Virtual IRQ control |
| 3 | `UOS_HV_CAP_VIRTIO_BLK` | VirtIO block device |
| 4 | `UOS_HV_CAP_STAGE2` | Stage-2 MMU active |
| 5 | `UOS_HV_CAP_APEX` | ARINC-653 calls |
| 6 | `UOS_HV_CAP_SAMPLING` | ARINC-653 sampling ports |
| 7 | `UOS_HV_CAP_VIRTIO_NET` | VirtIO net device |

---

### RISC-V Ecall Interface

Guests issue `ecall` from U-mode. Call number in `a7`, arguments in `a0`-`a2`, return in `a0`.

**Source**: `kernel/src/arch/riscv/inc/hypercall.h`

| Call # | Name | Args | Description |
|--------|------|------|-------------|
| 0 | `UOS_HCALL_YIELD` | — | Yield CPU |
| 1 | `UOS_HCALL_SET_TIMER` | time_lo, time_hi | Set timer |
| 2 | `UOS_HCALL_CONSOLE_PUTS` | str_ptr, len | Console output |
| 3 | `UOS_HCALL_MAP_MEMORY` | vaddr, paddr, size, flags | Map memory |
| 4 | `UOS_HCALL_UNMAP_MEMORY` | vaddr, size | Unmap memory |
| 5 | `UOS_HCALL_IPI_SEND` | target_hart | Send IPI |
| 6 | `UOS_HCALL_PARTITION_RESET` | — | Reset partition |
| 7 | `UOS_HCALL_IRQ_CLAIM` | — | Claim IRQ |
| 8 | `UOS_HCALL_IRQ_COMPLETE` | irq_num | Complete IRQ |
| 9 | `UOS_HCALL_NEXT_TIMEPART` | — | Next time partition |
| 10 | `UOS_HCALL_PART_GET_STATUS` | part_id | ARINC-653 partition status |
| 11 | `UOS_HCALL_PART_SET_MODE` | part_id, mode | ARINC-653 set mode |
| 12 | `UOS_HCALL_ERROR_RAISE` | error_code | ARINC-653 raise error |
| 13 | `UOS_HCALL_ERROR_GET_STATUS` | — | ARINC-653 get error status |
| 14 | `UOS_HCALL_GETTIME` | — | Get time (ticks) |
| 15 | `UOS_HCALL_SAMPLING_CREATE` | port_id, max_size | Sampling port create |
| 16 | `UOS_HCALL_SAMPLING_WRITE` | port_id, msg_ptr, msg_size | Sampling port write |
| 17 | `UOS_HCALL_SAMPLING_READ` | port_id, msg_ptr, buf_size | Sampling port read |
| 18 | `UOS_HCALL_VIRTIO_DISCOVER` | — | VirtIO device discovery |
| 19 | `UOS_HCALL_VIRTIO_KICK` | dev_id | VirtIO kick (notify) |
| 20 | `UOS_HCALL_VIRTIO_GET_CONFIG` | dev_id, cfg_ptr | VirtIO get device config |
| 21 | `UOS_HCALL_CHECKPOINT` | slot_id | Checkpoint (migration) |
| 22 | `UOS_HCALL_RESTORE` | slot_id | Restore (migration) |

#### Return Codes (RISC-V)

| Code | Name | Description |
|------|------|-------------|
| 0 | `UOS_HCALL_OK` | Success |
| -1 | `UOS_HCALL_EINVAL` | Bad argument |
| -7 | `UOS_HCALL_EFAULT` | Bad guest pointer |

---

### ARMv7 Paravirtualized Interface

ARMv7 guests run at SVC (no EL2). Opcodes are dispatched through `svc` with the opcode in `r7`.

**Source**: `kernel/src/core/abi/uos_pv_abi.h`

| Opcode | Name | Description |
|--------|------|-------------|
| 0xA0 | `PV_SVC_CON_PUTC` | Console character out |
| 0xA1 | `PV_SVC_CON_GETC` | Console character in (poll) |
| 0xA2 | `PV_SVC_CON_WRITE` | Console buffer write |
| 0xA3 | `PV_SVC_IRQ_ACK` | Acknowledge IRQ |
| 0xA4 | `PV_SVC_IRQ_ENABLE` | Enable IRQ |
| 0xA5 | `PV_SVC_IRQ_DISABLE` | Disable IRQ |
| 0xA6 | `PV_SVC_TIME` | Get time (ticks) |
| 0xA7 | `PV_SVC_MMIO_READ` | Proxy MMIO read |
| 0xA8 | `PV_SVC_MMIO_WRITE` | Proxy MMIO write |
| 0xA9 | `PV_SVC_PART_GET_STATUS` | ARINC-653 partition status |
| 0xAA | `PV_SVC_PART_SET_MODE` | ARINC-653 set mode |
| 0xAB | `PV_SVC_ERROR_RAISE` | ARINC-653 raise error |
| 0xAC | `PV_SVC_ERROR_GET_STATUS` | ARINC-653 get error status |
| 0xAF | `PV_SVC_HALT` | Halt guest partition |

Note: ARMv7 has no dedicated VirtIO hypercalls; VirtIO access goes through MMIO trap-and-emulate (`PV_SVC_MMIO_READ`/`PV_SVC_MMIO_WRITE`).

---

## VirtIO Hypercalls

VirtIO hypercalls provide paravirtualized device access. Implemented on AArch64 and RISC-V.

### VIRTIO_DISCOVER

Enumerates available VirtIO devices. Returns a bitmap of device IDs and their types.

- **AArch64**: `UOS_HV_VIRTIO_DISCOVER` (0x15)
- **RISC-V**: `UOS_HCALL_VIRTIO_DISCOVER` (18)

### VIRTIO_KICK

Notifies the hypervisor that the guest has updated a virtqueue descriptor.

- **AArch64**: `UOS_HV_VIRTIO_KICK` (0x19)
- **RISC-V**: `UOS_HCALL_VIRTIO_KICK` (19)

### VIRTIO_GET_CONFIG

Reads device-specific configuration space.

- **AArch64**: `UOS_HV_VIRTIO_GET_CONFIG` (0x17)
- **RISC-V**: `UOS_HCALL_VIRTIO_GET_CONFIG` (20)

### Supported Device Types

| Type | Name |
|------|------|
| 1 | `UOS_VIRTIO_NET` — Network |
| 2 | `UOS_VIRTIO_BLOCK` — Block storage |
| 3 | `UOS_VIRTIO_CONSOLE` — Console |
| 4 | `UOS_VIRTIO_GPU` — GPU |
| 5 | `UOS_VIRTIO_INPUT` — Input |
| 6 | `UOS_VIRTIO_BALLOON` — Memory balloon |
| 7 | `UOS_VIRTIO_CRYPTO` — Crypto |
| 8 | `UOS_VIRTIO_CUSTOM` — Custom |

---

## Migration Hypercalls

Checkpoint/restore hypercalls for live migration. Available on AArch64 and RISC-V only.

### CHECKPOINT

Captures a snapshot of the guest partition state (registers, memory, device state).

- **AArch64**: `UOS_HV_CHECKPOINT` (0x18)
- **RISC-V**: `UOS_HCALL_CHECKPOINT` (21)
- **Args**: `slot_id` (checkpoint slot index, 0 or 1)
- **Returns**: `UOS_HV_OK` on success

### RESTORE

Restores a previously checkpointed partition state.

- **AArch64**: `UOS_HV_RESTORE` (0x19)
- **RISC-V**: `UOS_HCALL_RESTORE` (22)
- **Args**: `slot_id`
- **Returns**: `UOS_HV_OK` on success

**Internal format**: Magic `0x554F4348` ("UOSH"), version 1, 2 checkpoint slots. See `kernel/src/core/migration/migrator.h`.

---

## Mycelium CLI

The `mycelium` binary replaces PikeOS's proprietary `configconv`. Located in the separate `mycelium` repository (`/home/fabiorafaelcoutada/portugalfuturista/mycelium/`).

### Usage

```
mycelium [OPTIONS] <xsd-file>
```

### Output Modes

| Flag | Description |
|------|-------------|
| `--enum --struct` | Emit C header enums and structs from XSD |
| `--enum-asm` | Emit assembler-safe enum header (defines only) |
| `--bin` | Emit binary configuration blob from XML instance |
| `--crc=NAME` | Emit CRC32 checksum for binary config |
| `--test` | Emit `.inc` test harness (C macro assertions) |
| `--tfw` | Emit TFW C test harness from test config XML |
| `--loader` | Emit struct-aware binary loader (C function) |

### Global Options

| Flag | Default | Description |
|------|---------|-------------|
| `--comment` | `""` | Banner comment in output |
| `--ifndef` | `MYCELIUM_GEN_H` | Include guard macro |
| `--include` | — | `#include` directive (e.g. `<kernel/p4stddef.h>`) |
| `--wordsize` | `32` | Pointer word size for `--bin` (32 or 64) |
| `--endian` | `little` | Endianness for `--bin` |
| `--align-tail` | `128` | Tail-padding alignment for `--bin` |
| `--xml` | — | Input XML instance (for `--bin`, `--test`, `--crc`) |
| `--out` | stdout | Output file path |

### Companion: `configmore`

| Flag | Description |
|------|-------------|
| `--mode test` | Emit test harness from XML + XSD |
| `--mode dump` | Print textual representation of binary config blob |
| `--schema` | XSD path (required for `--mode test`) |
| `--header-only` | For `--mode dump`: print header only |

---

## uos-cover Toolchain

Coverage analysis and certification evidence pipeline.

### uos-cins — C Source Instrumenter

```bash
python3 tools/uos-cover/uos_cins.py <source.c> \
  --profile COV_STATEMENTS -o <output.c> --uxsc <output.uxsc>
```

Profiles: `COV_STATEMENTS`, `COV_DECISIONS`, `COV_MCDC`, `COV_CALLS`, `COV_FUNCTIONS`

### uos-xst — Structural Linker

```bash
python3 tools/uos-cover/uos_xst.py <file1.uxsc> <file2.uxsc> ... \
  -o <project.umdb> --map <uos_map.h>
```

### uos-covparse — Coverage Dump Parser

```bash
python3 tools/uos-cover/uos_covparse.py <runtime.umap> \
  --map <project.umdb> --dataset <name> [--merge-results]
```

### uos-covexport — Report Generator

```bash
python3 tools/uos-cover/uos_covexport.py <project.umdb> \
  --fmt html -o <report.html>
```

Formats: `txt`, `csv`, `xml`, `html`

### uos-justify — Justification Store

```bash
# Add a justification
python3 tools/uos-cover/uos_justify.py add \
  --file src/sched.cpp --function schedule \
  --title "Dead code in error path" --class COV_DECISIONS

# List justifications
python3 tools/uos-cover/uos_justify.py list --file src/sched.cpp

# Export
python3 tools/uos-cover/uos_justify.py export --format xml -o ./justifications/
```

### uos-trace — Traceability Matrix

```bash
python3 tools/uos-cover/uos_trace.py generate \
  --requirements reqs.md --umdb <project.umdb> \
  --format html -o <traceability.html>
```

### uos-verify — DO-178C Verification Plan

```bash
python3 tools/uos-cover/uos_verify.py plan \
  --module scheduler --dal B --profile COV_STATEMENTS \
  -o verification_plan.md
```

DAL levels: A, B, C, D, E

### uos-package — Evidence Packager

```bash
python3 tools/uos-cover/uos_package.py \
  --umdb <project.umdb> \
  --justifications ./justifications/ \
  --traceability <traceability.html> \
  --verification-plan <verification_plan.md> \
  -o ./evidence/
```

### uos-cover — Project Driver (Orchestrator)

```bash
python3 tools/uos-cover/uos_cover.py run <project.ucovprj> --dataset <name>
python3 tools/uos-cover/uos_cover.py report <project.umdb> -o report.html
python3 tools/uos-cover/uos_cover.py instrument <project.ucovprj>
```

---

## uos-pkg Toolchain

RPM 4.2-compatible package management tooling.

### uos-pkg — Package Tool (Macro Engine)

```bash
# Evaluate a macro expression
python3 tools/uos-pkg/uos-pkg.py eval "%{name}-%{version}"

# Show resolved macro configuration
python3 tools/uos-pkg/uos-pkg.py showrc
```

### uos-build — RPM Build Engine

```bash
python3 tools/uos-pkg/uos_build.py <spec-file> [-bp|-bc|-bi|-ba|-bb|-bs]
```

| Flag | Stages |
|------|--------|
| `-bp` | Prep only |
| `-bc` | Prep + build |
| `-bi` | Prep + build + install |
| `-ba` | Full build (all stages + source + binary RPMs) |
| `-bb` | Binary RPM only |
| `-bs` | Source RPM only |

### uos-spec-parser — Spec File Parser

```bash
python3 tools/uos-pkg/uos_spec_parser.py <spec-file> --validate
```

Parses `.spec` files with preamble tags, `%define`/`%global` macros, section blocks (`%prep`, `%build`, `%install`, `%files`, `%changelog`), `%if`/`%else`/`%endif` conditionals, and macro expansion.