A class representing a single Domain. More...

#include <Domain.hh>

Public Member Functions
virtual std::shared_ptr< Breakpoint >	create_breakpoint (const guest_ptr< void > &address, std::function< void(Event &)> callback)=0
	Create an execution breakpoint.

virtual std::unique_ptr< Watchpoint >	create_watchpoint (const guest_ptr< void > &address, uint64_t length, bool read, bool write, bool execute, std::function< void(Event &)> callback)=0
	Create a watchpoint on guest memory (e.g. break on read/write)

virtual std::unique_ptr< SingleStep >	single_step (Vcpu &vcpu, std::function< void(Event &)> callback)=0
	Start single stepping a VCPU.

virtual bool	detect_guest ()=0
	Attempt guest OS detection.

virtual Guest *	guest ()=0
	Get the guest detected by detect_guest()

virtual const Guest *	guest () const =0
	Get the guest detected by detect_guest()

virtual std::string	name () const =0
	Get the name of the Domain, if it exists.

virtual uint32_t	id () const =0
	Get the id of the Domain.

virtual Vcpu &	vcpu (uint32_t index)=0
	Get a vcpu by index.

virtual const Vcpu &	vcpu (uint32_t index) const =0
	Get a vcpu by index.

virtual uint32_t	vcpu_count () const =0
	Get the number of vcpus in the Domain.

virtual const x86::PageDirectory &	page_directory () const =0
	Get the page directory for address translation.

virtual void	poll (EventCallback &callback)=0
	Poll for events and deliver them to the callback.

virtual void	interrupt ()=0
	Interrupt a poll() call.

virtual void	pause ()=0
	Pause the entire Domain.

virtual void	resume ()=0
	Resume the Domain.

virtual TaskFilter &	task_filter ()=0
	Get the task filter for this domain.

virtual SystemCallFilter &	system_call_filter ()=0
	Get the system call filter for this Domain.

virtual const SystemCallFilter &	system_call_filter () const =0
	Get the system call filter for this Domain.

virtual const Hypervisor &	hypervisor () const =0
	Gets the hypervisor that the Domain is running on.

virtual std::shared_ptr< GuestMemoryMapping >	map_pfns (const uint64_t *pfns, size_t count) const =0
	Map a list of pfns into our address space.

virtual void	intercept_system_calls (bool enabled)=0
	Toggle system call interception for all VCPUs.

virtual void	intercept_cr_writes (int cr, bool enabled)=0
	Toggle control register write interception on all VCPUs.

virtual void	suspend_event (Event &event)=0
	Mark an event as suspended.

virtual void	suspend_event_step (Event &event)=0
	Mark an event as suspended for single step.

virtual	~Domain ()=default
	Destroy the instance.

Static Public Member Functions
static Domain &	thread_local_domain ()
	Get the domain for the current thread.

Detailed Description

A class representing a single Domain.

A Domain object is the mechanism for interacting with a virtual machine. It is subclassed for specific hypervisors, such as the KvmDomain and the XenDomain.

Examples: ivcallmon.cc, and ivexec.cc.

Constructor & Destructor Documentation

◆ ~Domain()

virtual introvirt::Domain::~Domain ( )

virtualdefault

Destroy the instance.

Member Function Documentation

◆ create_breakpoint()

virtual std::shared_ptr< Breakpoint > introvirt::Domain::create_breakpoint	(	const guest_ptr< void > &	address,
		std::function< void(Event &)>	callback
	)

pure virtual

Create an execution breakpoint.

Parameters

address	The address to place the breakpoint
callback	The callback function to run

Returns: std::shared_ptr<Breakpoint> That clears the breakpoint when it goes off-scope

Examples: ivcallmon.cc.

◆ create_watchpoint()

virtual std::unique_ptr< Watchpoint > introvirt::Domain::create_watchpoint	(	const guest_ptr< void > &	address,
		uint64_t	length,
		bool	read,
		bool	write,
		bool	execute,
		std::function< void(Event &)>	callback
	)

pure virtual

Create a watchpoint on guest memory (e.g. break on read/write)

Parameters

address	The guest address to watch
length	Size in bytes of the watched region
read	Trigger on read access
write	Trigger on write access
execute	Trigger on execute access
callback	Called when the watchpoint fires

Returns: std::unique_ptr<Watchpoint> Clears the watchpoint when destroyed

◆ detect_guest()

virtual bool introvirt::Domain::detect_guest ( )

pure virtual

Attempt guest OS detection.

Waits for an incoming event and attempts to detect the guest

Returns: true if the guest OS was detected; false if the guest OS was not detected

◆ guest() [1/2]

virtual const Guest * introvirt::Domain::guest ( ) const

pure virtual

Get the guest detected by detect_guest()

Returns: The guest instance, or nullptr of one has not been detected

◆ guest() [2/2]

virtual Guest * introvirt::Domain::guest ( )

pure virtual

Get the guest detected by detect_guest()

Returns: The guest instance, or nullptr of one has not been detected

◆ hypervisor()

virtual const Hypervisor & introvirt::Domain::hypervisor ( ) const

pure virtual

Gets the hypervisor that the Domain is running on.

Returns: The hypervisor running the Domain

◆ id()

virtual uint32_t introvirt::Domain::id ( ) const

pure virtual

Get the id of the Domain.

The Domain identifier is specific to a hypervisor. On Xen, the ID increases each time a new one is created. On KVM, the ID is the PID of the QEMU process.

Returns: uint32_t id of the Domain

◆ intercept_cr_writes()

virtual void introvirt::Domain::intercept_cr_writes	(	int	cr,
		bool	enabled
	)

pure virtual

Toggle control register write interception on all VCPUs.

Parameters

cr	The control register to toggle interception for
enabled	If set to true, writes to the given control register will be intercepted

Exceptions

NotImplementedException	if writes to the given CR cannot be intercepted
CommandFailedException	If the hypervisor reports an error

◆ intercept_system_calls()

virtual void introvirt::Domain::intercept_system_calls ( bool enabled )

pure virtual

Toggle system call interception for all VCPUs.

Enables events of type EVENT_FAST_SYSCALL and EVENT_FAST_SYSCALL_RET.

When system call interception is enabled, SYSCALL/SYSENTER instructions are intercepted by the hypervisor. If the call number matches our SystemCallFilter (or the filter is disabled), a EVENT_FAST_SYSCALL event will be delivered.

While enabled, the hypervisor also intercept all SYSRET/SYSEXIT instructions.

Parameters

enabled If set to true, system calls and returns that match our filters will be intercepted.

Exceptions

NotImplementedException	if system call hooking is not supported
CommandFailedException	If the hypervisor reports an error

◆ interrupt()

virtual void introvirt::Domain::interrupt ( )

pure virtual

Interrupt a poll() call.

Examples: ivexec.cc.

◆ map_pfns()

virtual std::shared_ptr< GuestMemoryMapping > introvirt::Domain::map_pfns	(	const uint64_t *	pfns,
		size_t	count
	)		const

pure virtual

Map a list of pfns into our address space.

Generally you will not use this directly. Use a guest_ptr instead.

Parameters

pfns	An array of pfns to map
count	The number of pfns in the array

Returns: The mapped memory

Exceptions

BadPhysicalAddressException If the guest physical address could not be mapped

◆ name()

virtual std::string introvirt::Domain::name ( ) const

pure virtual

Get the name of the Domain, if it exists.

Returns: std::string containing the name of the Domain.

Examples: ivcallmon.cc.

◆ page_directory()

virtual const x86::PageDirectory & introvirt::Domain::page_directory ( ) const

pure virtual

Get the page directory for address translation.

Returns: The page directory

◆ pause()

virtual void introvirt::Domain::pause ( )

pure virtual

Pause the entire Domain.

◆ poll()

virtual void introvirt::Domain::poll ( EventCallback & callback )

pure virtual

Poll for events and deliver them to the callback.

This is a single threaded event poller. One thread handles all Vcpus.

Parameters

callback The callback to deliver events to

◆ resume()

virtual void introvirt::Domain::resume ( )

pure virtual

Resume the Domain.

◆ single_step()

virtual std::unique_ptr< SingleStep > introvirt::Domain::single_step	(	Vcpu &	vcpu,
		std::function< void(Event &)>	callback
	)

pure virtual

Start single stepping a VCPU.

Parameters

vcpu
callback

Returns: std::unique_ptr<SingleStepImpl>

◆ suspend_event()

virtual void introvirt::Domain::suspend_event ( Event & event )

pure virtual

Mark an event as suspended.

Parameters

event

◆ suspend_event_step()

virtual void introvirt::Domain::suspend_event_step ( Event & event )

pure virtual

Mark an event as suspended for single step.

Parameters

event

◆ system_call_filter() [1/2]

virtual const SystemCallFilter & introvirt::Domain::system_call_filter ( ) const

pure virtual

Get the system call filter for this Domain.

This is the Domain-level system call filter.

If enabled, it will be checked only if the vcpu-level filter doesn't match.

Returns: The Domain system call filter

◆ system_call_filter() [2/2]

virtual SystemCallFilter & introvirt::Domain::system_call_filter ( )

pure virtual

Get the system call filter for this Domain.

This is the Domain-level system call filter.

If enabled, it will be checked only if the vcpu-level filter doesn't match.

Returns: The Domain system call filter

Examples: ivexec.cc.

◆ task_filter()

virtual TaskFilter & introvirt::Domain::task_filter ( )

pure virtual

Get the task filter for this domain.

The task filter can be used to filter events for specific threads and processes.

Examples: ivexec.cc.

◆ thread_local_domain()

static Domain & introvirt::Domain::thread_local_domain ( )

static

Get the domain for the current thread.

Returns: Domain&

Exceptions

TODO	if domain is nullptr

◆ vcpu() [1/2]

virtual const Vcpu & introvirt::Domain::vcpu ( uint32_t index ) const

pure virtual

Get a vcpu by index.

Parameters

index The index of the vcpu to retreive

Returns: std::unique_ptr<Vcpu>

Exceptions

InvalidVcpuException if the specified vcpu does not exist

◆ vcpu() [2/2]

virtual Vcpu & introvirt::Domain::vcpu ( uint32_t index )

pure virtual

Get a vcpu by index.

Parameters

index The index of the vcpu to retreive

Returns: std::unique_ptr<Vcpu>

Exceptions

InvalidVcpuException if the specified vcpu does not exist

◆ vcpu_count()

virtual uint32_t introvirt::Domain::vcpu_count ( ) const

pure virtual

Get the number of vcpus in the Domain.

Returns: int indicating the number of vcpus

The documentation for this class was generated from the following file:

/home/runner/work/IntroVirt/IntroVirt/include/introvirt/core/domain/Domain.hh

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Domain()

Member Function Documentation

◆ create_breakpoint()

◆ create_watchpoint()

◆ detect_guest()

◆ guest() [1/2]

◆ guest() [2/2]

◆ hypervisor()

◆ id()

◆ intercept_cr_writes()

◆ intercept_system_calls()

◆ interrupt()

◆ map_pfns()

◆ name()

◆ page_directory()

◆ pause()

◆ poll()

◆ resume()

◆ single_step()

◆ suspend_event()

◆ suspend_event_step()

◆ system_call_filter() [1/2]

◆ system_call_filter() [2/2]

◆ task_filter()

◆ thread_local_domain()

◆ vcpu() [1/2]

◆ vcpu() [2/2]

◆ vcpu_count()