377 lines
12 KiB
Markdown
377 lines
12 KiB
Markdown
# 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.
|