Hypercall APIs¶

This section contains APIs for the hypercall services. Sources for the Device Model are found in the ACRN Hypervisor GitHub repo

group acrn_hypercall

Hypercall.

Defines

ACRN_INTR_TYPE_ISA¶: Interrupt type for acrn_irqline: inject interrupt to IOAPIC

ACRN_INTR_TYPE_IOAPIC¶: Interrupt type for acrn_irqline: inject interrupt to both PIC and IOAPIC

GUEST_CFG_OFFSET¶

The guest config pointer offset.

It’s designed to support passing DM config data pointer, based on it, hypervisor would parse then pass DM defined configuration to GUEST VCPU when booting guest VM. the address 0xd0000 here is designed by DM, as it arranged all memory layout below 1M, DM should make sure there is no overlap for the address 0xd0000 usage.

SPACE_SYSTEM_MEMORY¶: Info The power state data of a VCPU.

SPACE_SYSTEM_IO¶

SPACE_PCI_CONFIG¶

SPACE_Embedded_Control¶

SPACE_SMBUS¶

SPACE_PLATFORM_COMM¶

SPACE_FFixedHW¶

PMCMD_VMID_MASK¶

Info PM command from DM/VHM.

The command would specify request type(e.g. get px count or data) for specific VM and specific VCPU with specific state number. For Px, PMCMD_STATE_NUM means Px number from 0 to (MAX_PSTATE - 1), For Cx, PMCMD_STATE_NUM means Cx entry index from 1 to MAX_CX_ENTRY.

PMCMD_VCPUID_MASK¶

PMCMD_STATE_NUM_MASK¶

PMCMD_TYPE_MASK¶

PMCMD_VMID_SHIFT¶

PMCMD_VCPUID_SHIFT¶

PMCMD_STATE_NUM_SHIFT¶

Enums

enum pm_cmd_type¶

Values:

PMCMD_GET_PX_CNT¶

PMCMD_GET_PX_DATA¶

PMCMD_GET_CX_CNT¶

PMCMD_GET_CX_DATA¶

Functions

int64_t hcall_get_api_version(struct vm *vm, uint64_t param)¶

Get hypervisor api version.

The function only return api version information when VM is VM0.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
param: guest physical memory address. The api version returned will be copied to this gpa

int64_t hcall_create_vm(struct vm *vm, uint64_t param)¶

create virtual machine

Create a virtual machine based on parameter, currently there is no limitation for calling times of this function, will add MAX_VM_NUM support later.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
param: guest physical memory address. This gpa points to struct acrn_create_vm

int64_t hcall_destroy_vm(uint64_t vmid)¶

destroy virtual machine

Destroy a virtual machine, it will pause target VM then shutdown it. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vmid: ID of the VM

int64_t hcall_resume_vm(uint64_t vmid)¶

resume virtual machine

Resume a virtual machine, it will schedule target VM’s vcpu to run. The function will return -1 if the target VM does not exist or the IOReq buffer page for the VM is not ready.

Return

0 on success, non-zero on error.

Parameters

vmid: ID of the VM

int64_t hcall_pause_vm(uint64_t vmid)¶

pause virtual machine

Pause a virtual machine, if the VM is already paused, the function will return 0 directly for success. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vmid: ID of the VM

int64_t hcall_create_vcpu(struct vm *vm, uint64_t vmid, uint64_t param)¶

create vcpu

Create a vcpu based on parameter for a VM, it will allocate vcpu from freed physical cpus, if there is no available pcpu, the function will return -1.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_create_vcpu

int64_t hcall_assert_irqline(struct vm *vm, uint64_t vmid, uint64_t param)¶

assert IRQ line

Assert a virtual IRQ line for a VM, which could be from ISA or IOAPIC, normally it will active a level IRQ. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_irqline

int64_t hcall_deassert_irqline(struct vm *vm, uint64_t vmid, uint64_t param)¶

deassert IRQ line

Deassert a virtual IRQ line for a VM, which could be from ISA or IOAPIC, normally it will deactive a level IRQ. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_irqline

int64_t hcall_pulse_irqline(struct vm *vm, uint64_t vmid, uint64_t param)¶

trigger a pulse on IRQ line

Trigger a pulse on a virtual IRQ line for a VM, which could be from ISA or IOAPIC, normally it triggers an edge IRQ. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_irqline

int64_t hcall_inject_msi(struct vm *vm, uint64_t vmid, uint64_t param)¶

inject MSI interrupt

Inject a MSI interrupt for a VM. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_msi_entry

int64_t hcall_set_ioreq_buffer(struct vm *vm, uint64_t vmid, uint64_t param)¶

set ioreq shared buffer

Set the ioreq share buffer for a VM. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_set_ioreq_buffer

int64_t hcall_notify_req_finish(uint64_t vmid, uint64_t param)¶

notify request done

Notify the requestor VCPU for the completion of an ioreq. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vmid: ID of the VM
param: vcpu ID of the requestor

int64_t hcall_set_vm_memmap(struct vm *vm, uint64_t vmid, uint64_t param)¶

setup ept memory mapping

Set the ept memory mapping for a VM. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct vm_set_memmap

int64_t hcall_set_vm_memmaps(struct vm *vm, uint64_t param)¶

setup ept memory mapping for multi regions

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
param: guest physical address. This gpa points to struct set_memmaps

int64_t hcall_remap_pci_msix(struct vm *vm, uint64_t vmid, uint64_t param)¶

remap PCI MSI interrupt

Remap a PCI MSI interrupt from a VM’s virtual vector to native vector. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct acrn_vm_pci_msix_remap

int64_t hcall_gpa_to_hpa(struct vm *vm, uint64_t vmid, uint64_t param)¶

translate guest physical address to host physical address

Translate guest physical address to host physical address for a VM. The function will return -1 if the target VM does not exist.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to struct vm_gpa2hpa

int64_t hcall_assign_ptdev(struct vm *vm, uint64_t vmid, uint64_t param)¶

Assign one passthrough dev to VM.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to physical BDF of the assigning ptdev

int64_t hcall_deassign_ptdev(struct vm *vm, uint64_t vmid, uint64_t param)¶

Deassign one passthrough dev from VM.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to physical BDF of the deassigning ptdev

int64_t hcall_set_ptdev_intr_info(struct vm *vm, uint64_t vmid, uint64_t param)¶

Set interrupt mapping info of ptdev.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to data structure of hc_ptdev_irq including intr remapping info

int64_t hcall_reset_ptdev_intr_info(struct vm *vm, uint64_t vmid, uint64_t param)¶

Clear interrupt mapping info of ptdev.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
vmid: ID of the VM
param: guest physical address. This gpa points to data structure of hc_ptdev_irq including intr remapping info

int64_t hcall_setup_sbuf(struct vm *vm, uint64_t param)¶

Setup a share buffer for a VM.

Return

0 on success, non-zero on error.

Parameters

vm: Pointer to VM data structure
param: guest physical address. This gpa points to struct sbuf_setup_param

int64_t hcall_get_cpu_pm_state(struct vm *vm, uint64_t cmd, uint64_t param)¶

Get VCPU Power state.

Return

0 on success, non-zero on error.

Parameters

vm: pointer to VM data structure
cmd: cmd to show get which VCPU power state data
param: VCPU power state data

struct mmio_request¶

#include <acrn_common.h>

Public Members

uint32_t direction¶

uint32_t reserved¶

int64_t address¶

int64_t size¶

int64_t value¶

struct pio_request¶

#include <acrn_common.h>

Public Members

uint32_t direction¶

uint32_t reserved¶

int64_t address¶

int64_t size¶

int32_t value¶

struct pci_request¶

#include <acrn_common.h>

Public Members

uint32_t direction¶

uint32_t reserved[3]¶

int64_t size¶

int32_t value¶

int32_t bus¶

int32_t dev¶

int32_t func¶

int32_t reg¶

struct vhm_request¶

#include <acrn_common.h>

Public Members

uint32_t type¶

int32_t reserved0[15]¶

union vhm_request::@0 vhm_request::reqs

int32_t valid¶

int32_t client¶

int32_t processed¶

union vhm_request_buffer¶

#include <acrn_common.h>

Public Members

struct vhm_request req_queue[VHM_REQUEST_MAX]¶

int8_t reserved[4096]¶

union

Public Members

struct acrn_create_vm¶

#include <acrn_common.h>

Info to create a VM, the parameter for HC_CREATE_VM hypercall.

Public Members

int32_t vmid¶: created vmid return to VHM. Keep it first field

uint32_t vcpu_num¶: VCPU numbers this VM want to create

uint8_t GUID[16]¶: the GUID of this VM

uint64_t vm_flag¶

uint8_t reserved[24]¶: Reserved for future use

struct acrn_create_vcpu¶

#include <acrn_common.h>

Info to create a VCPU.

the parameter for HC_CREATE_VCPU hypercall

Public Members

uint16_t vcpu_id¶: the virtual CPU ID for the VCPU created

uint16_t pcpu_id¶: the physical CPU ID for the VCPU created

struct acrn_set_ioreq_buffer¶

#include <acrn_common.h>

Info to set ioreq buffer for a created VM.

the parameter for HC_SET_IOREQ_BUFFER hypercall

Public Members

uint64_t req_buf¶: guest physical address of VM request_buffer

struct acrn_irqline¶

#include <acrn_common.h>

Info to assert/deassert/pulse a virtual IRQ line for a VM.

the parameter for HC_ASSERT_IRQLINE/HC_DEASSERT_IRQLINE/HC_PULSE_IRQLINE hypercall

Public Members

uint32_t intr_type¶: interrupt type which could be IOAPIC or ISA

uint32_t reserved¶: reserved for alignment padding

uint64_t pic_irq¶: pic IRQ for ISA type

uint64_t ioapic_irq¶: ioapic IRQ for IOAPIC & ISA TYPE, if ~0UL then this IRQ will not be injected

struct acrn_msi_entry¶

#include <acrn_common.h>

Info to inject a MSI interrupt to VM.

the parameter for HC_INJECT_MSI hypercall

Public Members

uint64_t msi_addr¶: MSI addr[19:12] with dest VCPU ID

uint64_t msi_data¶: MSI data[7:0] with vector

struct acrn_nmi_entry¶

#include <acrn_common.h>

Info to inject a NMI interrupt for a VM.

Public Members

int64_t vcpu_id¶: virtual CPU ID to inject

struct acrn_vm_pci_msix_remap¶

#include <acrn_common.h>

Info to remap pass-through PCI MSI for a VM.

the parameter for HC_VM_PCI_MSIX_REMAP hypercall

Public Members

uint16_t virt_bdf¶: pass-through PCI device virtual BDF#

uint16_t phys_bdf¶: pass-through PCI device physical BDF#

uint16_t msi_ctl¶: pass-through PCI device MSI/MSI-X cap control data

uint16_t reserved¶: reserved for alignment padding

uint64_t msi_addr¶: pass-through PCI device MSI address to remap, which will return the caller after remapping

uint32_t msi_data¶: pass-through PCI device MSI data to remap, which will return the caller after remapping

int32_t msix¶: pass-through PCI device is MSI or MSI-X 0 - MSI, 1 - MSI-X

int32_t msix_entry_index¶: if the pass-through PCI device is MSI-X, this field contains the MSI-X entry table index

uint32_t vector_ctl¶: if the pass-through PCI device is MSI-X, this field contains Vector Control for MSI-X Entry, field defined in MSI-X spec

struct acpi_generic_address¶

#include <acrn_common.h>

Public Members

uint8_t space_id¶

uint8_t bit_width¶

uint8_t bit_offset¶

uint8_t access_size¶

uint64_t address¶

struct cpu_cx_data¶

#include <acrn_common.h>

Public Members

struct acpi_generic_address cx_reg¶

uint8_t type¶

uint32_t latency¶

uint64_t power¶

struct cpu_px_data¶

#include <acrn_common.h>

Public Members

uint64_t core_frequency¶

uint64_t power¶

uint64_t transition_latency¶

uint64_t bus_master_latency¶

uint64_t control¶

uint64_t status¶

struct acpi_sx_pkg¶

#include <acrn_common.h>

Public Members

uint8_t val_pm1a¶

uint8_t val_pm1b¶

uint16_t reserved¶

struct pm_s_state_data¶

#include <acrn_common.h>

Public Members

struct acpi_generic_address pm1a_evt¶

struct acpi_generic_address pm1b_evt¶

struct acpi_generic_address pm1a_cnt¶

struct acpi_generic_address pm1b_cnt¶

struct acpi_sx_pkg s3_pkg¶

struct acpi_sx_pkg s5_pkg¶

uint32_t *wake_vector_32¶

uint64_t *wake_vector_64¶

struct acpi_info¶

#include <acrn_common.h>

Public Members

int16_t x86_family¶

int16_t x86_model¶

struct pm_s_state_data pm_s_state¶

struct vm_set_memmap¶

#include <acrn_hv_defs.h>

Info to set ept mapping.

the parameter for HC_VM_SET_MEMMAP hypercall

Public Members

uint32_t type¶: map type: MAP_MEM, MAP_MMIO or MAP_UNMAP

uint32_t prot¶: memory attributes: memory type + RWX access right

uint64_t remote_gpa¶: guest physical address to map

uint64_t vm0_gpa¶: VM0’s guest physcial address which remote gpa will be mapped to

uint64_t length¶: length of the map range

uint32_t prot_2¶: old memory attributes(will be removed in the future): memory type + RWX access right

struct memory_map¶

#include <acrn_hv_defs.h>

Public Members

uint32_t type¶: map type: MAP_MEM, MAP_MMIO or MAP_UNMAP

uint32_t prot¶: memory attributes: memory type + RWX access right

uint64_t remote_gpa¶: guest physical address to map

uint64_t vm0_gpa¶: VM0’s guest physcial address which remote gpa will be mapped to

uint64_t length¶: length of the map range

struct set_memmaps¶

#include <acrn_hv_defs.h>

multi memmap regions hypercall, used for HC_VM_SET_MEMMAPS

Public Members

uint64_t vmid¶: vmid for this hypercall

uint32_t memmaps_num¶: multi memmaps numbers

uint64_t memmaps_gpa¶: the gpa of memmaps buffer, point to the memmaps array: struct memory_map regions[memmaps_num] the max buffer size is one page.

struct sbuf_setup_param¶

#include <acrn_hv_defs.h>

Setup parameter for share buffer, used for HC_SETUP_SBUF hypercall

Public Members

uint16_t pcpu_id¶: sbuf physical cpu id

uint32_t sbuf_id¶: sbuf id

uint64_t gpa¶: sbuf’s guest physical address

struct vm_gpa2hpa¶

#include <acrn_hv_defs.h>

Gpa to hpa translation parameter, used for HC_VM_GPA2HPA hypercall

Public Members

uint64_t gpa¶: gpa to do translation

uint64_t hpa¶: hpa to return after translation

struct hc_ptdev_irq¶

#include <acrn_hv_defs.h>

Intr mapping info per ptdev, the parameter for HC_SET_PTDEV_INTR_INFO hypercall

Public Members

uint32_t type¶: irq mapping type: INTX or MSI

uint16_t virt_bdf¶: virtual BDF of the ptdev

uint16_t phys_bdf¶: physical BDF of the ptdev

union hc_ptdev_irq::@1 hc_ptdev_irq::is

union

Public Members

: INTX remapping info

: MSIx remapping info

struct

INTX remapping info

Public Members

: virtual IOAPIC/PIC pin

: physical IOAPIC pin

: is virtual pin from PIC

struct

MSIx remapping info

Public Members

: vector count of MSI/MSIX

struct hc_api_version¶

#include <acrn_hv_defs.h>

Hypervisor api version info, return it for HC_GET_API_VERSION hypercall

Public Members

uint32_t major_version¶: hypervisor api major version

uint32_t minor_version¶: hypervisor api minor version

struct trusty_boot_param¶

#include <acrn_hv_defs.h>

Trusty boot params, used for HC_INITIALIZE_TRUSTY

Public Members

uint32_t size_of_this_struct¶: sizeof this structure

uint32_t version¶: version of this structure

uint32_t base_addr¶: trusty runtime memory base address

uint32_t entry_point¶: trusty entry point

uint32_t mem_size¶: trusty runtime memory size

uint32_t padding¶: padding

uint8_t rpmb_key[64]¶: rpmb key