domctl.h File Reference

Xen Domain Control Interface. More...

#include <zephyr/xen/generic.h>
#include <zephyr/xen/public/domctl.h>
#include <zephyr/xen/public/xen.h>
#include <zephyr/kernel.h>

Go to the source code of this file.

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)
	Pauses a domain in the Xen hypervisor.
int	xen_domctl_unpausedomain (int domid)
	Unpauses 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)
	Retrieves the virtual CPU context for a specific domain and virtual CPU.
int	xen_domctl_setvcpucontext (int domid, int vcpu, vcpu_guest_context_t *ctxt)
	Sets the virtual CPU context for a specified domain and virtual CPU.
int	xen_domctl_getdomaininfo (int domid, xen_domctl_getdomaininfo_t *dom_info)
	Retrieves information about a Xen domain.
int	xen_domctl_get_paging_mempool_size (int domid, uint64_t *size)
	Gets the paging mempool size for a specified domain.
int	xen_domctl_set_paging_mempool_size (int domid, uint64_t size)
	Sets the paging mempool size for a specified domain.
int	xen_domctl_max_mem (int domid, uint64_t max_memkb)
	Sets the maximum memory for a specified domain.
int	xen_domctl_set_address_size (int domid, int addr_size)
	Sets the address size for a specified domain.
int	xen_domctl_iomem_permission (int domid, uint64_t first_mfn, uint64_t nr_mfns, uint8_t allow_access)
	Set IOMEM permission 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)
	Maps a range of machine memory to a range of guest memory.
int	xen_domctl_assign_dt_device (int domid, char *dtdev_path)
	Assign a device to a guest.
int	xen_domctl_deassign_dt_device (int domid, char *dtdev_path)
	Deassign a device 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)
	Binds a physical IRQ to a specified domain.
int	xen_domctl_max_vcpus (int domid, int max_vcpus)
	Set the maximum number of vCPUs for a domain.
int	xen_domctl_createdomain (int *domid, struct xen_domctl_createdomain *config)
	Creates a new domain with the specified domain ID and configuration.
int	xen_domctl_cacheflush (int domid, struct xen_domctl_cacheflush *cacheflush)
	Clean and invalidate caches associated with given region of guest memory.
int	xen_domctl_destroydomain (int domid)
	Destroys a Xen domain.
int	xen_domctl_getvcpu (int domid, uint32_t vcpu, struct xen_domctl_getvcpuinfo *info)
	Retrieves information about a specific virtual CPU (vCPU) in a Xen domain.

Detailed Description

Xen Domain Control Interface.

Function Documentation

xen_domctl_assign_dt_device()

int xen_domctl_assign_dt_device	(	int	domid,
		char *	dtdev_path )

Assign a device to a guest.

Sets up IOMMU structures.

Parameters

domid	The ID of the domain to which the device is to be assigned.
dtdev_path	The path of the device tree device to be assigned.

Return values

0	on success.
-errno	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 )

Binds a physical IRQ to a specified domain.

Only supports SPI IRQs for now.

Parameters

domid	The ID of the domain to bind the IRQ to.
machine_irq	The machine IRQ number to bind.
irq_type	The type of IRQ to bind (PT_IRQ_TYPE_SPI).
bus	The PCI bus number of the device generating the IRQ. (optional)
device	The PCI device number generating the IRQ. (optional)
intx	The PCI INTx line number of the device generating the IRQ. (optional)
isa_irq	The ISA IRQ number to bind. (optional)
spi	The shared peripheral interrupt (SPI) number to bind. (optional)

Return values

0	on success.
-errno	on failure.

xen_domctl_cacheflush()

int xen_domctl_cacheflush	(	int	domid,
		struct xen_domctl_cacheflush *	cacheflush )

Clean and invalidate caches associated with given region of guest memory.

Parameters

domid	The ID of the domain for which the cache needs to be flushed.
cacheflush	A pointer to the xen_domctl_cacheflush structure that contains the cache flush parameters.

Return values

0	on success.
-errno	on failure.

xen_domctl_createdomain()

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

Creates a new domain with the specified domain ID and configuration.

NB. domid 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.

Parameters

[in,out]	domid	Pointer to domain ID of the new domain.
	config	Pointer to a structure containing the configuration for the new domain.

Return values

0	on success.
-errno	on failure.

xen_domctl_deassign_dt_device()

int xen_domctl_deassign_dt_device	(	int	domid,
		char *	dtdev_path )

Deassign a device from a guest domain.

Parameters

domid	The ID of the domain from which the device should be deassigned.
dtdev_path	The path of the device tree device to be deassigned.

Return values

0	on success.
-errno	on failure.

xen_domctl_destroydomain()

int xen_domctl_destroydomain

(

int

domid

)

Destroys a Xen domain.

Parameters

domid

The ID of the domain to be destroyed.

Return values

0	on success.
-errno	on failure.

xen_domctl_get_paging_mempool_size()

int xen_domctl_get_paging_mempool_size	(	int	domid,
		uint64_t *	size )

Gets the paging mempool size for a specified domain.

Parameters

domid	The ID of the domain.
size	pointer where to store size of the paging mempool.

Return values

0	on success.
-errno	on failure.

xen_domctl_getdomaininfo()

int xen_domctl_getdomaininfo	(	int	domid,
		xen_domctl_getdomaininfo_t *	dom_info )

Retrieves information about a Xen domain.

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.

Return values

0	on success.
-errno	on failure.

xen_domctl_getvcpu()

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

Retrieves information about a specific virtual CPU (vCPU) in a Xen domain.

Parameters

	domid	The ID of the domain.
	vcpu	The index of the vCPU.
[out]	info	Pointer to a structure to store the vCPU information.

Return values

0	on success.
-errno	on failure.

xen_domctl_getvcpucontext()

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

Retrieves the virtual CPU context for a specific domain and virtual CPU.

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

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.

Return values

0	on success.
-errno	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 )

Set IOMEM permission for a domain.

Parameters

domid	The ID of the domain for which IOMEM permission is being set.
first_mfn	The starting machine frame number of the memory range.
nr_mfns	The number of MFNs in the memory range.
allow_access	Flag indicating whether to allow or deny access to the specified memory range. A non-zero value allows access, while a zero value denies access.

Return values

0	on success.
-errno	on failure.

xen_domctl_max_mem()

int xen_domctl_max_mem	(	int	domid,
		uint64_t	max_memkb )

Sets the maximum memory for a specified domain.

Parameters

domid	The domain ID of the domain to set the maximum memory for.
max_memkb	The maximum memory (in kilobytes) to set for the domain.

Return values

0	on success.
-errno	on failure.

xen_domctl_max_vcpus()

int xen_domctl_max_vcpus	(	int	domid,
		int	max_vcpus )

Set the maximum number of vCPUs for a domain.

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.

Parameters

domid	The ID of the domain.
max_vcpus	Maximum number of vCPUs to set.

Return values

0	on success.
-errno	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 )

Maps a range of machine memory to a range of guest memory.

Parameters

domid	The domain ID of the target domain.
first_gfn	The first guest frame number to map.
first_mfn	The first machine frame number to map.
nr_mfns	The number of machine frames to map.
add_mapping	Flag indicating whether to add or remove the mapping.

Return values

0	on success.
-errno	on failure.

xen_domctl_pausedomain()

int xen_domctl_pausedomain

(

int

domid

)

Pauses a domain in the Xen hypervisor.

Parameters

domid

The ID of the domain to be paused.

Return values

0	on success.
-errno	on failure.s

xen_domctl_resumedomain()

int xen_domctl_resumedomain

(

int

domid

)

Resumes a domain.

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

Parameters

domid

The ID of the domain to be resumed.

Return values

0	on success.
-errno	on failure.

xen_domctl_scheduler_op()

int xen_domctl_scheduler_op	(	int	domid,
		struct xen_domctl_scheduler_op *	sched_op )

Perform a scheduler operation on a specified domain.

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.

Return values

0	on success.
-errno	on failure.

xen_domctl_set_address_size()

int xen_domctl_set_address_size	(	int	domid,
		int	addr_size )

Sets the address size for a specified domain.

Parameters

domid	The ID of the domain.
addr_size	The address size to be set.

Return values

0	on success.
-errno	on failure.

xen_domctl_set_paging_mempool_size()

int xen_domctl_set_paging_mempool_size	(	int	domid,
		uint64_t	size )

Sets the paging mempool size for a specified domain.

Parameters

domid	The ID of the domain.
size	The size of the paging mempool in bytes.

Return values

0	on success.
-errno	on failure.

xen_domctl_setvcpucontext()

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

Sets the virtual CPU context for a specified domain and virtual CPU.

Parameters

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

Return values

0	on success.
-errno	on failure.

xen_domctl_unpausedomain()

int xen_domctl_unpausedomain

(

int

domid

)

Unpauses a domain in the Xen hypervisor.

Parameters

domid

The domain ID of the domain to be unpaused.

Return values

0	on success.
-errno	on failure.