API Reference

types.h

Primitive type definitions shared across all Haven modules.

typedef uint64_t hv_u64;
typedef uint32_t hv_u32;
typedef uint16_t hv_u16;
typedef uint8_t  hv_u8;
typedef int32_t  hv_status_t;

Status Codes

stage2.h - Stage-2 MMU

struct hv_mem_region {
    hv_u64 ipa_base;
    hv_u64 pa_base;
    hv_u64 size;
    hv_u64 attrs;
};

struct hv_partition_mem {
    hv_u32                   partition_id;
    const struct hv_mem_region *regions;
    hv_u32                   region_count;
};

hv_status_t hv_stage2_init(void);
hv_status_t hv_stage2_map_partition(const struct hv_partition_mem *pmem);
hv_status_t hv_stage2_check_access(hv_u32 partition_id, hv_u64 ipa, hv_u64 size);

hv_stage2_init - Must be called once before any other stage-2 function. Zeroes all partition mapping state.

hv_stage2_map_partition - Maps all regions in pmem into the partition’s stage-2 page tables. Returns HV_EINVAL if any region overlaps with an existing mapping or if partition_id ≥ HV_MAX_PARTITIONS.

hv_stage2_check_access - Returns HV_OK if [ipa, ipa+size) is fully within the partition’s mapped range. Returns HV_EPERM otherwise.

irq_ownership.h - Interrupt Ownership

struct hv_irq_route {
    hv_u32 irq_id;
    hv_u32 owner_partition_id;
    hv_u32 target_cpu;
};

hv_status_t hv_irq_owner_init(void);
hv_status_t hv_irq_assign(const struct hv_irq_route *route);
hv_status_t hv_irq_revoke(hv_u32 irq_id, hv_u32 owner_partition_id);
hv_status_t hv_irq_check_owner(hv_u32 irq_id, hv_u32 partition_id);

hv_irq_owner_init - Marks all HV_MAX_IRQ_ID (1024) IRQs as unowned.

hv_irq_assign - Assigns route->irq_id to route->owner_partition_id. Returns HV_EINVAL if irq_id ≥ HV_MAX_IRQ_ID. Returns HV_EPERM if the IRQ is already assigned to a different partition.

hv_irq_revoke - Removes the assignment. Returns HV_EPERM if owner_partition_id does not currently own the IRQ.

budget_sched.h - Budget Scheduler

struct hv_budget {
    hv_u32 partition_id;
    hv_u64 period_ns;
    hv_u64 budget_ns;
};

hv_status_t hv_budget_sched_init(void);
hv_status_t hv_budget_set(const struct hv_budget *budget);
hv_status_t hv_budget_consume(hv_u32 partition_id, hv_u64 delta_ns);
hv_status_t hv_budget_check(hv_u32 partition_id);
hv_status_t hv_budget_replenish(hv_u32 partition_id);

hv_budget_set - Validates budget_ns ≤ period_ns and period_ns > 0. Returns HV_EINVAL on violation.

hv_budget_consume - Subtracts delta_ns from the partition’s remaining budget. Returns HV_EPERM when the budget is exhausted (remaining ≤ 0).

smmu.h - SMMU / DMA Isolation

hv_status_t hv_smmu_init(void);
hv_status_t hv_smmu_map_device(hv_u32 stream_id, hv_u32 partition_id);
hv_status_t hv_smmu_unmap_device(hv_u32 stream_id, hv_u32 partition_id);
hv_status_t hv_smmu_check_device(hv_u32 stream_id, hv_u32 partition_id);

hv_smmu_map_device - Associates stream_id with partition_id’s stage-2 context. Returns HV_ENOSPC if HV_MAX_SMMU_DEVICES is reached.

Error Handling Convention

All functions return hv_status_t:

• HV_OK (0) on success.
• A negative error code on failure.
• Callers must check the return value; ignoring it is a contract violation.