Control domain lifecycle, resources, and vCPUs from the privileged domain. More...

Files
file	domctl.h
	Xen Dom0 domain control operations.

Functions
int	xen_domctl_scheduler_op (int domid, struct xen_domctl_scheduler_op *sched_op)
	Perform a scheduler operation on a specified domain.
int	xen_domctl_pausedomain (int domid)
	Pause a domain in the Xen hypervisor.
int	xen_domctl_unpausedomain (int domid)
	Unpause a domain in the Xen hypervisor.
int	xen_domctl_resumedomain (int domid)
	Resumes a domain.
int	xen_domctl_getvcpucontext (int domid, int vcpu, vcpu_guest_context_t *ctxt)
	Get the guest context of a domain vCPU.
int	xen_domctl_setvcpucontext (int domid, int vcpu, vcpu_guest_context_t *ctxt)
	Set the guest context of a domain vCPU.
int	xen_domctl_getdomaininfo (int domid, xen_domctl_getdomaininfo_t *dom_info)
	Get summary information for a domain.
int	xen_domctl_get_paging_mempool_size (int domid, uint64_t *size)
	Get the paging mempool size for a domain.
int	xen_domctl_set_paging_mempool_size (int domid, uint64_t size)
	Set the paging mempool size for a domain.
int	xen_domctl_max_mem (int domid, uint64_t max_memkb)
	Set the maximum memory assigned to a domain.
int	xen_domctl_set_address_size (int domid, int addr_size)
	Set the address size used by a domain.
int	xen_domctl_iomem_permission (int domid, uint64_t first_mfn, uint64_t nr_mfns, uint8_t allow_access)
	Allow or deny I/O-memory access for a domain.
int	xen_domctl_memory_mapping (int domid, uint64_t first_gfn, uint64_t first_mfn, uint64_t nr_mfns, uint32_t add_mapping)
	Map or unmap a machine-memory range into a guest frame range.
int	xen_domctl_assign_dt_device (int domid, char *dtdev_path)
	Assign a devicetree-described device to a guest domain.
int	xen_domctl_deassign_dt_device (int domid, char *dtdev_path)
	Remove a devicetree-described device assignment from a guest domain.
int	xen_domctl_bind_pt_irq (int domid, uint32_t machine_irq, uint8_t irq_type, uint8_t bus, uint8_t device, uint8_t intx, uint8_t isa_irq, uint16_t spi)
	Bind a physical interrupt to a guest domain.
int	xen_domctl_max_vcpus (int domid, int max_vcpus)
	Set the maximum number of vCPUs available to a domain.
int	xen_domctl_createdomain (int domid, struct xen_domctl_createdomain config)
	Create a new domain.
int	xen_domctl_cacheflush (int domid, struct xen_domctl_cacheflush *cacheflush)
	Clean and invalidate caches for a guest memory range.
int	xen_domctl_destroydomain (int domid)
	Destroy a domain.
int	xen_domctl_getvcpu (int domid, uint32_t vcpu, struct xen_domctl_getvcpuinfo *info)
	Query runtime information for one domain vCPU.

Detailed Description

Control domain lifecycle, resources, and vCPUs from the privileged domain.

Function Documentation

◆ xen_domctl_assign_dt_device()

int xen_domctl_assign_dt_device	(	int	domid,
		char *	dtdev_path )

#include <zephyr/xen/dom0/domctl.h>

Assign a devicetree-described device to a guest domain.

On arm64, this is primarily used for devices that can act as bus masters (DMA-capable devices). Xen configures the IOMMU as part of the assignment.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
dtdev_path	NULL-terminated devicetree path to the device.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_bind_pt_irq()

int xen_domctl_bind_pt_irq	(	int	domid,
		uint32_t	machine_irq,
		uint8_t	irq_type,
		uint8_t	bus,
		uint8_t	device,
		uint8_t	intx,
		uint8_t	isa_irq,
		uint16_t	spi )

#include <zephyr/xen/dom0/domctl.h>

Bind a physical interrupt to a guest domain.

Only PT_IRQ_TYPE_SPI is currently supported.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
machine_irq	Machine IRQ number to bind.
irq_type	Xen passthrough IRQ type.
bus	PCI bus number for PCI passthrough modes.
device	PCI device number for PCI passthrough modes.
intx	PCI INTx line for PCI passthrough modes.
isa_irq	ISA IRQ number for ISA passthrough modes.
spi	SPI number used with PT_IRQ_TYPE_SPI.

Returns: 0 on success, negative errno value on failure.

Return values

-ENOTSUP irq_type is not supported by the current implementation.

◆ xen_domctl_cacheflush()

int xen_domctl_cacheflush	(	int	domid,
		struct xen_domctl_cacheflush *	cacheflush )

#include <zephyr/xen/dom0/domctl.h>

Clean and invalidate caches for a guest memory range.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
cacheflush	Cache-flush request parameters.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_createdomain()

int xen_domctl_createdomain	(	int *	domid,
		struct xen_domctl_createdomain *	config )

#include <zephyr/xen/dom0/domctl.h>

Create a new domain.

domid is an IN/OUT parameter. If it is specified as an invalid value (0 or >= DOMID_FIRST_RESERVED), Xen auto-allocates an identifier and returns it through domid.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

[in,out]	domid	Domain identifier request and response buffer.
	config	Domain configuration passed to Xen.

Returns: 0 on success, negative errno value on failure.

Return values

-EINVAL domid or config is NULL.

◆ xen_domctl_deassign_dt_device()

int xen_domctl_deassign_dt_device	(	int	domid,
		char *	dtdev_path )

#include <zephyr/xen/dom0/domctl.h>

Remove a devicetree-described device assignment from a guest domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
dtdev_path	NULL-terminated devicetree path to the device.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_destroydomain()

int xen_domctl_destroydomain ( int domid )

#include <zephyr/xen/dom0/domctl.h>

Destroy a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid Target domain identifier.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_get_paging_mempool_size()

int xen_domctl_get_paging_mempool_size	(	int	domid,
		uint64_t *	size )

#include <zephyr/xen/dom0/domctl.h>

Get the paging mempool size for a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

	domid	Target domain identifier.
[out]	size	Buffer that receives the paging mempool size in bytes.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_getdomaininfo()

int xen_domctl_getdomaininfo	(	int	domid,
		xen_domctl_getdomaininfo_t *	dom_info )

#include <zephyr/xen/dom0/domctl.h>

Get summary information for a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

	domid	The ID of the Xen domain to retrieve information for.
[out]	dom_info	Pointer to the structure where the retrieved domain information will be stored.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_getvcpu()

int xen_domctl_getvcpu	(	int	domid,
		uint32_t	vcpu,
		struct xen_domctl_getvcpuinfo *	info )

#include <zephyr/xen/dom0/domctl.h>

Query runtime information for one domain vCPU.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

	domid	Target domain identifier.
	vcpu	vCPU index to query.
[out]	info	Buffer that receives the vCPU information.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_getvcpucontext()

int xen_domctl_getvcpucontext	(	int	domid,
		int	vcpu,
		vcpu_guest_context_t *	ctxt )

#include <zephyr/xen/dom0/domctl.h>

Get the guest context of a domain vCPU.

Attention
Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid The ID of the domain.

vcpu The ID of the virtual CPU.

[out] ctxt Pointer to the vcpu_guest_context_t structure where the virtual CPU context will be stored.

Returns
0 on success, negative errno value on failure.

◆ xen_domctl_iomem_permission()

int xen_domctl_iomem_permission	(	int	domid,
		uint64_t	first_mfn,
		uint64_t	nr_mfns,
		uint8_t	allow_access )

#include <zephyr/xen/dom0/domctl.h>

Allow or deny I/O-memory access for a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
first_mfn	First machine frame number in the range.
nr_mfns	Number of machine frames in the range.
allow_access	Set to non-zero to allow access, or zero to revoke it.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_max_mem()

int xen_domctl_max_mem	(	int	domid,
		uint64_t	max_memkb )

#include <zephyr/xen/dom0/domctl.h>

Set the maximum memory assigned to a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
max_memkb	Maximum memory in KiB.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_max_vcpus()

int xen_domctl_max_vcpus	(	int	domid,
		int	max_vcpus )

#include <zephyr/xen/dom0/domctl.h>

Set the maximum number of vCPUs available to a domain.

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.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
max_vcpus	Maximum number of Xen vCPUs to allocate.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_memory_mapping()

int xen_domctl_memory_mapping	(	int	domid,
		uint64_t	first_gfn,
		uint64_t	first_mfn,
		uint64_t	nr_mfns,
		uint32_t	add_mapping )

#include <zephyr/xen/dom0/domctl.h>

Map or unmap a machine-memory range into a guest frame range.

The implementation automatically retries the operation with smaller chunks if Xen reports that the request is too large.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
first_gfn	First guest frame number in the target range.
first_mfn	First machine frame number in the source range.
nr_mfns	Number of frames to process.
add_mapping	Set to non-zero to add the mapping, or zero to remove it.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_pausedomain()

int xen_domctl_pausedomain ( int domid )

#include <zephyr/xen/dom0/domctl.h>

Pause a domain in the Xen hypervisor.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid The ID of the domain to be paused.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_resumedomain()

int xen_domctl_resumedomain ( int domid )

#include <zephyr/xen/dom0/domctl.h>

Resumes a domain.

This function resumes the execution of a domain in the shutdown state.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid The ID of the domain to be resumed.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_scheduler_op()

int xen_domctl_scheduler_op	(	int	domid,
		struct xen_domctl_scheduler_op *	sched_op )

#include <zephyr/xen/dom0/domctl.h>

Perform a scheduler operation on a specified domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

	domid	The ID of the domain on which the scheduler operation is to be performed.
[in,out]	sched_op	A pointer to a struct xen_domctl_scheduler_op object that defines the specific scheduler operation to be performed.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_set_address_size()

int xen_domctl_set_address_size	(	int	domid,
		int	addr_size )

#include <zephyr/xen/dom0/domctl.h>

Set the address size used by a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
addr_size	Xen address-size selector.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_set_paging_mempool_size()

int xen_domctl_set_paging_mempool_size	(	int	domid,
		uint64_t	size )

#include <zephyr/xen/dom0/domctl.h>

Set the paging mempool size for a domain.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	Target domain identifier.
size	New paging mempool size in bytes.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_setvcpucontext()

int xen_domctl_setvcpucontext	(	int	domid,
		int	vcpu,
		vcpu_guest_context_t *	ctxt )

#include <zephyr/xen/dom0/domctl.h>

Set the guest context of a domain vCPU.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid	The ID of the domain.
vcpu	The ID of the virtual CPU.
ctxt	Pointer to the virtual CPU guest context structure.

Returns: 0 on success, negative errno value on failure.

◆ xen_domctl_unpausedomain()

int xen_domctl_unpausedomain ( int domid )

#include <zephyr/xen/dom0/domctl.h>

Unpause a domain in the Xen hypervisor.

Attention: Available only when the following Kconfig option is enabled: CONFIG_XEN_DOM0.

Parameters

domid The ID of the domain to be unpaused.

Returns: 0 on success, negative errno value on failure.

Files

Functions

Detailed Description

Function Documentation

◆ xen_domctl_assign_dt_device()

◆ xen_domctl_bind_pt_irq()

◆ xen_domctl_cacheflush()

◆ xen_domctl_createdomain()

◆ xen_domctl_deassign_dt_device()

◆ xen_domctl_destroydomain()

◆ xen_domctl_get_paging_mempool_size()

◆ xen_domctl_getdomaininfo()

◆ xen_domctl_getvcpu()

◆ xen_domctl_getvcpucontext()

◆ xen_domctl_iomem_permission()

◆ xen_domctl_max_mem()

◆ xen_domctl_max_vcpus()

◆ xen_domctl_memory_mapping()

◆ xen_domctl_pausedomain()

◆ xen_domctl_resumedomain()

◆ xen_domctl_scheduler_op()

◆ xen_domctl_set_address_size()

◆ xen_domctl_set_paging_mempool_size()

◆ xen_domctl_setvcpucontext()

◆ xen_domctl_unpausedomain()