Fábio Coutada 7983d7ffc3 fix(kernel): resolve armv7 linker errors, fix exceptions vector base address, and remove untracked conflicting files

2026-07-12 16:40:24 +01:00

12 KiB

Raw Permalink Blame History

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

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

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

uos-covparse — Coverage Dump Parser

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

uos-covexport — Report Generator

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

Formats: txt, csv, xml, html

uos-justify — Justification Store

# 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

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

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

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)

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)

# 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

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

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.

12 KiB Raw Permalink Blame History