domctl.h

Go to the documentation of this file.

/* SPDX-License-Identifier: MIT */
/******************************************************************************
 * domctl.h
 *
 * Domain management operations. For use by node control stack.
 *
 * Copyright (c) 2002-2003, B Dragovic
 * Copyright (c) 2002-2006, K Fraser
 */
 
#ifndef __XEN_PUBLIC_DOMCTL_H__
#define __XEN_PUBLIC_DOMCTL_H__
 
#ifndef CONFIG_XEN_DOM0
#error "domctl operations are intended for use by node control tools only"
#endif
 
#include "xen.h"
#include "event_channel.h"
#include "grant_table.h"
#include "memory.h"
 
#define XEN_DOMCTL_INTERFACE_VERSION 0x00000015
 
/*
 * NB. xen_domctl.domain is an IN/OUT parameter for this operation.
 * If it is specified as an invalid value (0 or >= DOMID_FIRST_RESERVED),
 * an id is auto-allocated and returned.
 */
/* XEN_DOMCTL_createdomain */
struct xen_domctl_createdomain {
 /* IN parameters */
 uint32_t ssidref;
 xen_domain_handle_t handle;
/* Is this an HVM guest (as opposed to a PV guest)? */
#define _XEN_DOMCTL_CDF_hvm 0
#define XEN_DOMCTL_CDF_hvm (1U << _XEN_DOMCTL_CDF_hvm)
/* Use hardware-assisted paging if available? */
#define _XEN_DOMCTL_CDF_hap 1
#define XEN_DOMCTL_CDF_hap (1U << _XEN_DOMCTL_CDF_hap)
/* Should domain memory integrity be verifed by tboot during Sx? */
#define _XEN_DOMCTL_CDF_s3_integrity 2
#define XEN_DOMCTL_CDF_s3_integrity (1U << _XEN_DOMCTL_CDF_s3_integrity)
/* Disable out-of-sync shadow page tables? */
#define _XEN_DOMCTL_CDF_oos_off 3
#define XEN_DOMCTL_CDF_oos_off (1U << _XEN_DOMCTL_CDF_oos_off)
/* Is this a xenstore domain? */
#define _XEN_DOMCTL_CDF_xs_domain 4
#define XEN_DOMCTL_CDF_xs_domain (1U << _XEN_DOMCTL_CDF_xs_domain)
/* Should this domain be permitted to use the IOMMU? */
#define _XEN_DOMCTL_CDF_iommu 5
#define XEN_DOMCTL_CDF_iommu (1U << _XEN_DOMCTL_CDF_iommu)
#define _XEN_DOMCTL_CDF_nested_virt 6
#define XEN_DOMCTL_CDF_nested_virt (1U << _XEN_DOMCTL_CDF_nested_virt)
/* Should we expose the vPMU to the guest? */
#define XEN_DOMCTL_CDF_vpmu (1U << 7)
 
/* Max XEN_DOMCTL_CDF_* constant. Used for ABI checking. */
#define XEN_DOMCTL_CDF_MAX XEN_DOMCTL_CDF_vpmu
 
 uint32_t flags;
 
#define _XEN_DOMCTL_IOMMU_no_sharept 0
#define XEN_DOMCTL_IOMMU_no_sharep (1U << _XEN_DOMCTL_IOMMU_no_sharept)
 
/* Max XEN_DOMCTL_IOMMU_* constant. Used for ABI checking. */
#define XEN_DOMCTL_IOMMU_MAX XEN_DOMCTL_IOMMU_no_sharept
 
 uint32_t iommu_opts;
 
 /*
 * Various domain limits, which impact the quantity of resources
 * (global mapping space, xenheap, etc) a guest may consume. For
 * max_grant_frames and max_maptrack_frames, < 0 means "use the
 * default maximum value in the hypervisor".
 */
 uint32_t max_vcpus;
 uint32_t max_evtchn_port;
 int32_t max_grant_frames;
 int32_t max_maptrack_frames;
 
/* Grant version, use low 4 bits. */
#define XEN_DOMCTL_GRANT_version_mask 0xf
#define XEN_DOMCTL_GRANT_version(v) ((v) & XEN_DOMCTL_GRANT_version_mask)
 
 uint32_t grant_opts;
 
 /* Per-vCPU buffer size in bytes. 0 to disable. */
 uint32_t vmtrace_size;
 
 /* CPU pool to use; specify 0 or a specific existing pool */
 uint32_t cpupool_id;
 
 struct xen_arch_domainconfig arch;
};
 
/* XEN_DOMCTL_getdomaininfo */
struct xen_domctl_getdomaininfo {
 /* OUT variables. */
 domid_t domain; /* Also echoed in domctl.domain */
 uint16_t pad1;
/* Domain is scheduled to die. */
#define _XEN_DOMINF_dying 0
#define XEN_DOMINF_dying (1U << _XEN_DOMINF_dying)
/* Domain is an HVM guest (as opposed to a PV guest). */
#define _XEN_DOMINF_hvm_guest 1
#define XEN_DOMINF_hvm_guest (1U << _XEN_DOMINF_hvm_guest)
/* The guest OS has shut down. */
#define _XEN_DOMINF_shutdown 2
#define XEN_DOMINF_shutdown (1U << _XEN_DOMINF_shutdown)
/* Currently paused by control software. */
#define _XEN_DOMINF_paused 3
#define XEN_DOMINF_paused (1U << _XEN_DOMINF_paused)
/* Currently blocked pending an event. */
#define _XEN_DOMINF_blocked 4
#define XEN_DOMINF_blocked (1U << _XEN_DOMINF_blocked)
/* Domain is currently running. */
#define _XEN_DOMINF_running 5
#define XEN_DOMINF_running (1U << _XEN_DOMINF_running)
/* Being debugged. */
#define _XEN_DOMINF_debugged 6
#define XEN_DOMINF_debugged (1U << _XEN_DOMINF_debugged)
/* domain is a xenstore domain */
#define _XEN_DOMINF_xs_domain 7
#define XEN_DOMINF_xs_domain (1U << _XEN_DOMINF_xs_domain)
/* domain has hardware assisted paging */
#define _XEN_DOMINF_hap 8
#define XEN_DOMINF_hap (1U << _XEN_DOMINF_hap)
/* XEN_DOMINF_shutdown guest-supplied code. */
#define XEN_DOMINF_shutdownmask 255
#define XEN_DOMINF_shutdownshift 16
 uint32_t flags; /* XEN_DOMINF_* */
 uint64_aligned_t tot_pages;
 uint64_aligned_t max_pages;
 uint64_aligned_t outstanding_pages;
 uint64_aligned_t shr_pages;
 uint64_aligned_t paged_pages;
 uint64_aligned_t shared_info_frame; /* GMFN of shared_info struct */
 uint64_aligned_t cpu_time;
 uint32_t nr_online_vcpus; /* Number of VCPUs currently online. */
#define XEN_INVALID_MAX_VCPU_ID (~0U) /* Domain has no vcpus? */
 uint32_t max_vcpu_id; /* Maximum VCPUID in use by this domain. */
 uint32_t ssidref;
 xen_domain_handle_t handle;
 uint32_t cpupool;
 uint8_t gpaddr_bits; /* Guest physical address space size. */
 uint8_t pad2[7];
 struct xen_arch_domainconfig arch_config;
};
typedef struct xen_domctl_getdomaininfo xen_domctl_getdomaininfo_t;
DEFINE_XEN_GUEST_HANDLE(xen_domctl_getdomaininfo_t);
 
/*
 * Control shadow pagetables operation
 */
/* XEN_DOMCTL_shadow_op */
 
/* Memory allocation accessors. */
#define XEN_DOMCTL_SHADOW_OP_GET_ALLOCATION 30
#define XEN_DOMCTL_SHADOW_OP_SET_ALLOCATION 31
 
struct xen_domctl_shadow_op_stats {
 uint32_t fault_count;
 uint32_t dirty_count;
};
 
struct xen_domctl_shadow_op {
 /* IN variables. */
 uint32_t op; /* XEN_DOMCTL_SHADOW_OP_* */
 
 /* OP_ENABLE: XEN_DOMCTL_SHADOW_ENABLE_* */
 /* OP_PEAK / OP_CLEAN: XEN_DOMCTL_SHADOW_LOGDIRTY_* */
 uint32_t mode;
 
 /* OP_GET_ALLOCATION / OP_SET_ALLOCATION */
 uint32_t mb; /* Shadow memory allocation in MB */
 
 /* OP_PEEK / OP_CLEAN */
 XEN_GUEST_HANDLE_64(uint8_t) dirty_bitmap;
 uint64_aligned_t pages; /* Size of buffer. Updated with actual size. */
 struct xen_domctl_shadow_op_stats stats;
};
 
/* XEN_DOMCTL_max_mem */
struct xen_domctl_max_mem {
 /* IN variables. */
 uint64_aligned_t max_memkb;
};
 
/* XEN_DOMCTL_setvcpucontext */
/* XEN_DOMCTL_getvcpucontext */
struct xen_domctl_vcpucontext {
 uint32_t vcpu; /* IN */
 
 XEN_GUEST_HANDLE_64(vcpu_guest_context_t) ctxt; /* IN/OUT */
};
 
/*
 * XEN_DOMCTL_max_vcpus:
 *
 * The parameter passed to XEN_DOMCTL_max_vcpus must match the value passed to
 * XEN_DOMCTL_createdomain. This hypercall is in the process of being removed
 * (once the failure paths in domain_create() have been improved), but is
 * still required in the short term to allocate the vcpus themselves.
 */
struct xen_domctl_max_vcpus {
 uint32_t max; /* maximum number of vcpus */
};
 
/* XEN_DOMCTL_scheduler_op */
/* Scheduler types. */
/* #define XEN_SCHEDULER_SEDF 4 (Removed) */
#define XEN_SCHEDULER_CREDIT 5
#define XEN_SCHEDULER_CREDIT2 6
#define XEN_SCHEDULER_ARINC653 7
#define XEN_SCHEDULER_RTDS 8
#define XEN_SCHEDULER_NULL 9
 
struct xen_domctl_sched_credit {
 uint16_t weight;
 uint16_t cap;
};
 
struct xen_domctl_sched_credit2 {
 uint16_t weight;
 uint16_t cap;
};
 
struct xen_domctl_sched_rtds {
 uint32_t period;
 uint32_t budget;
/* Can this vCPU execute beyond its reserved amount of time? */
#define _XEN_DOMCTL_SCHEDRT_extra 0
#define XEN_DOMCTL_SCHEDRT_extra (1U<<_XEN_DOMCTL_SCHEDRT_extra)
 uint32_t flags;
};
 
typedef struct xen_domctl_schedparam_vcpu {
 union {
 struct xen_domctl_sched_credit credit;
 struct xen_domctl_sched_credit2 credit2;
 struct xen_domctl_sched_rtds rtds;
 } u;
 uint32_t vcpuid;
} xen_domctl_schedparam_vcpu_t;
DEFINE_XEN_GUEST_HANDLE(xen_domctl_schedparam_vcpu_t);
 
/*
 * Set or get info?
 * For schedulers supporting per-vcpu settings (e.g., RTDS):
 * XEN_DOMCTL_SCHEDOP_putinfo sets params for all vcpus;
 * XEN_DOMCTL_SCHEDOP_getinfo gets default params;
 * XEN_DOMCTL_SCHEDOP_put(get)vcpuinfo sets (gets) params of vcpus;
 *
 * For schedulers not supporting per-vcpu settings:
 * XEN_DOMCTL_SCHEDOP_putinfo sets params for all vcpus;
 * XEN_DOMCTL_SCHEDOP_getinfo gets domain-wise params;
 * XEN_DOMCTL_SCHEDOP_put(get)vcpuinfo returns error;
 */
#define XEN_DOMCTL_SCHEDOP_putinfo 0
#define XEN_DOMCTL_SCHEDOP_getinfo 1
#define XEN_DOMCTL_SCHEDOP_putvcpuinfo 2
#define XEN_DOMCTL_SCHEDOP_getvcpuinfo 3
struct xen_domctl_scheduler_op {
 uint32_t sched_id; /* XEN_SCHEDULER_* */
 uint32_t cmd; /* XEN_DOMCTL_SCHEDOP_* */
 /* IN/OUT */
 union {
 struct xen_domctl_sched_credit credit;
 struct xen_domctl_sched_credit2 credit2;
 struct xen_domctl_sched_rtds rtds;
 struct {
 XEN_GUEST_HANDLE_64(xen_domctl_schedparam_vcpu_t) vcpus;
 /*
 * IN: Number of elements in vcpus array.
 * OUT: Number of processed elements of vcpus array.
 */
 uint32_t nr_vcpus;
 uint32_t padding;
 } v;
 } u;
};
 
/* XEN_DOMCTL_iomem_permission */
struct xen_domctl_iomem_permission {
 uint64_aligned_t first_mfn;/* first page (physical page number) in range */
 uint64_aligned_t nr_mfns; /* number of pages in range (>0) */
 uint8_t allow_access; /* allow (!0) or deny (0) access to range? */
};
 
/* XEN_DOMCTL_set_address_size */
/* XEN_DOMCTL_get_address_size */
struct xen_domctl_address_size {
 uint32_t size;
};
 
/* Assign a device to a guest. Sets up IOMMU structures. */
/* XEN_DOMCTL_assign_device */
/*
 * XEN_DOMCTL_test_assign_device: Pass DOMID_INVALID to find out whether the
 * given device is assigned to any DomU at all. Pass a specific domain ID to
 * find out whether the given device can be assigned to that domain.
 */
/*
 * XEN_DOMCTL_deassign_device: The behavior of this DOMCTL differs
 * between the different type of device:
 * - PCI device (XEN_DOMCTL_DEV_PCI) will be reassigned to DOM0
 * - DT device (XEN_DOMCTL_DEV_DT) will left unassigned. DOM0
 * will have to call XEN_DOMCTL_assign_device in order to use the
 * device.
 */
#define XEN_DOMCTL_DEV_PCI 0
#define XEN_DOMCTL_DEV_DT 1
struct xen_domctl_assign_device {
 /* IN */
 uint32_t dev; /* XEN_DOMCTL_DEV_* */
 uint32_t flags;
#define XEN_DOMCTL_DEV_RDM_RELAXED 1 /* assign only */
 union {
 struct {
 uint32_t machine_sbdf; /* machine PCI ID of assigned device */
 } pci;
 struct {
 uint32_t size; /* Length of the path */
 
 XEN_GUEST_HANDLE_64(char) path; /* path to the device tree node */
 } dt;
 } u;
};
 
/* Pass-through interrupts: bind real irq -> hvm devfn. */
/* XEN_DOMCTL_bind_pt_irq */
/* XEN_DOMCTL_unbind_pt_irq */
enum pt_irq_type {
 PT_IRQ_TYPE_PCI,
 PT_IRQ_TYPE_ISA,
 PT_IRQ_TYPE_MSI,
 PT_IRQ_TYPE_MSI_TRANSLATE,
 PT_IRQ_TYPE_SPI, /* ARM: valid range 32-1019 */
};
struct xen_domctl_bind_pt_irq {
 uint32_t machine_irq;
 uint32_t irq_type; /* enum pt_irq_type */
 
 union {
 struct {
 uint8_t isa_irq;
 } isa;
 struct {
 uint8_t bus;
 uint8_t device;
 uint8_t intx;
 } pci;
 struct {
 uint8_t gvec;
 uint32_t gflags;
#define XEN_DOMCTL_VMSI_X86_DEST_ID_MASK 0x0000ff
#define XEN_DOMCTL_VMSI_X86_RH_MASK 0x000100
#define XEN_DOMCTL_VMSI_X86_DM_MASK 0x000200
#define XEN_DOMCTL_VMSI_X86_DELIV_MASK 0x007000
#define XEN_DOMCTL_VMSI_X86_TRIG_MASK 0x008000
#define XEN_DOMCTL_VMSI_X86_UNMASKED 0x010000
 
 uint64_aligned_t gtable;
 } msi;
 struct {
 uint16_t spi;
 } spi;
 } u;
};
 
 
/* Bind machine I/O address range -> HVM address range. */
/* XEN_DOMCTL_memory_mapping */
/* Returns
 * - zero success, everything done
 * - -E2BIG passed in nr_mfns value too large for the implementation
 * - positive partial success for the first <result> page frames (with
 * <result> less than nr_mfns), requiring re-invocation by the
 * caller after updating inputs
 * - negative error; other than -E2BIG
 */
#define DPCI_ADD_MAPPING 1
#define DPCI_REMOVE_MAPPING 0
struct xen_domctl_memory_mapping {
 uint64_aligned_t first_gfn; /* first page (hvm guest phys page) in range */
 uint64_aligned_t first_mfn; /* first page (machine page) in range */
 uint64_aligned_t nr_mfns; /* number of pages in range (>0) */
 uint32_t add_mapping; /* add or remove mapping */
 uint32_t padding; /* padding for 64-bit aligned structure */
};
 
/*
 * ARM: Clean and invalidate caches associated with given region of
 * guest memory.
 */
struct xen_domctl_cacheflush {
 /* IN: page range to flush. */
 xen_pfn_t start_pfn, nr_pfns;
};
 
/*
 * XEN_DOMCTL_get_paging_mempool_size / XEN_DOMCTL_set_paging_mempool_size.
 *
 * Get or set the paging memory pool size. The size is in bytes.
 *
 * This is a dedicated pool of memory for Xen to use while managing the guest,
 * typically containing pagetables. As such, there is an implementation
 * specific minimum granularity.
 *
 * The set operation can fail mid-way through the request (e.g. Xen running
 * out of memory, no free memory to reclaim from the pool, etc.).
 */
struct xen_domctl_paging_mempool {
 uint64_aligned_t size; /* Size in bytes. */
};
 
struct xen_domctl {
 uint32_t cmd;
#define XEN_DOMCTL_createdomain 1
#define XEN_DOMCTL_destroydomain 2
#define XEN_DOMCTL_pausedomain 3
#define XEN_DOMCTL_unpausedomain 4
#define XEN_DOMCTL_getdomaininfo 5
#define XEN_DOMCTL_setvcpuaffinity 9
#define XEN_DOMCTL_shadow_op 10
#define XEN_DOMCTL_max_mem 11
#define XEN_DOMCTL_setvcpucontext 12
#define XEN_DOMCTL_getvcpucontext 13
#define XEN_DOMCTL_getvcpuinfo 14
#define XEN_DOMCTL_max_vcpus 15
#define XEN_DOMCTL_scheduler_op 16
#define XEN_DOMCTL_setdomainhandle 17
#define XEN_DOMCTL_setdebugging 18
#define XEN_DOMCTL_irq_permission 19
#define XEN_DOMCTL_iomem_permission 20
#define XEN_DOMCTL_ioport_permission 21
#define XEN_DOMCTL_hypercall_init 22
#define XEN_DOMCTL_settimeoffset 24
#define XEN_DOMCTL_getvcpuaffinity 25
#define XEN_DOMCTL_real_mode_area 26 /* Obsolete PPC only */
#define XEN_DOMCTL_resumedomain 27
#define XEN_DOMCTL_sendtrigger 28
#define XEN_DOMCTL_subscribe 29
#define XEN_DOMCTL_gethvmcontext 33
#define XEN_DOMCTL_sethvmcontext 34
#define XEN_DOMCTL_set_address_size 35
#define XEN_DOMCTL_get_address_size 36
#define XEN_DOMCTL_assign_device 37
#define XEN_DOMCTL_bind_pt_irq 38
#define XEN_DOMCTL_memory_mapping 39
#define XEN_DOMCTL_ioport_mapping 40
#define XEN_DOMCTL_set_ext_vcpucontext 42
#define XEN_DOMCTL_get_ext_vcpucontext 43
#define XEN_DOMCTL_set_opt_feature 44 /* Obsolete IA64 only */
#define XEN_DOMCTL_test_assign_device 45
#define XEN_DOMCTL_set_target 46
#define XEN_DOMCTL_deassign_device 47
#define XEN_DOMCTL_unbind_pt_irq 48
#define XEN_DOMCTL_get_device_group 50
#define XEN_DOMCTL_debug_op 54
#define XEN_DOMCTL_gethvmcontext_partial 55
#define XEN_DOMCTL_vm_event_op 56
#define XEN_DOMCTL_mem_sharing_op 57
#define XEN_DOMCTL_gettscinfo 59
#define XEN_DOMCTL_settscinfo 60
#define XEN_DOMCTL_getpageframeinfo3 61
#define XEN_DOMCTL_setvcpuextstate 62
#define XEN_DOMCTL_getvcpuextstate 63
#define XEN_DOMCTL_set_access_required 64
#define XEN_DOMCTL_audit_p2m 65
#define XEN_DOMCTL_set_virq_handler 66
#define XEN_DOMCTL_set_broken_page_p2m 67
#define XEN_DOMCTL_setnodeaffinity 68
#define XEN_DOMCTL_getnodeaffinity 69
#define XEN_DOMCTL_cacheflush 71
#define XEN_DOMCTL_get_vcpu_msrs 72
#define XEN_DOMCTL_set_vcpu_msrs 73
#define XEN_DOMCTL_setvnumainfo 74
#define XEN_DOMCTL_psr_cmt_op 75
#define XEN_DOMCTL_monitor_op 77
#define XEN_DOMCTL_psr_alloc 78
#define XEN_DOMCTL_soft_reset 79
#define XEN_DOMCTL_vuart_op 81
#define XEN_DOMCTL_get_cpu_policy 82
#define XEN_DOMCTL_set_cpu_policy 83
#define XEN_DOMCTL_vmtrace_op 84
#define XEN_DOMCTL_get_paging_mempool_size 85
#define XEN_DOMCTL_set_paging_mempool_size 86
#define XEN_DOMCTL_gdbsx_guestmemio 1000
#define XEN_DOMCTL_gdbsx_pausevcpu 1001
#define XEN_DOMCTL_gdbsx_unpausevcpu 1002
#define XEN_DOMCTL_gdbsx_domstatus 1003
 uint32_t interface_version; /* XEN_DOMCTL_INTERFACE_VERSION */
 domid_t domain;
 uint16_t _pad[3];
 union {
 struct xen_domctl_createdomain createdomain;
 struct xen_domctl_getdomaininfo getdomaininfo;
 struct xen_domctl_max_mem max_mem;
 struct xen_domctl_vcpucontext vcpucontext;
 struct xen_domctl_max_vcpus max_vcpus;
 struct xen_domctl_scheduler_op scheduler_op;
 struct xen_domctl_iomem_permission iomem_permission;
 struct xen_domctl_address_size address_size;
 struct xen_domctl_assign_device assign_device;
 struct xen_domctl_bind_pt_irq bind_pt_irq;
 struct xen_domctl_memory_mapping memory_mapping;
 struct xen_domctl_cacheflush cacheflush;
 struct xen_domctl_paging_mempool paging_mempool;
 uint8_t pad[128];
 } u;
};
typedef struct xen_domctl xen_domctl_t;
DEFINE_XEN_GUEST_HANDLE(xen_domctl_t);
 
#endif /* __XEN_PUBLIC_DOMCTL_H__ */