XenAccess: xenaccess.h File Reference

#define XA_MODE_XEN 0

Mode indicating that we are monitoring a live Xen VM

#define XA_MODE_FILE 1

Mode indicating that we are viewing a memory image from a disk file

#define XA_FILETYPE_DD 0

Reading from a dd file type (file offset == physical address). This value is only used when mode equals XA_MODE_FILE.

#define XA_SUCCESS 0

Return value indicating success.

#define XA_FAILURE -1

Return value indicating failure.

#define XA_FAILHARD 0

Failure mode where XenAccess will exit with failure if there are any problems found on startup. This will provide for strict checking of the configuration file parameters and the memory image itself. If initialization completes successfully in this mode, then you should then have full use of the XenAccess memory access functionality (e.g., virtual, physical, and symbolic lookups).

#define XA_FAILSOFT 1

Failure mode where XenAccess will try to complete initialization unless there is a fatal failure. Assuming that initialization does complete, memory access may be available with reduced functionality (e.g., only able to access physical addresses). The exact functionality available will depend on the problems that were bypassed during initialization.

#define XA_OS_LINUX 0

Constant used to specify Linux in the os_type member of the xa_instance struct.

#define XA_OS_WINDOWS 1

Constant used to specify Windows in the os_type member of the xa_instance struct.

#define XA_XENVER_UNKNOWN 0

Constant used to indicate that we are running on a version of Xen that XenAccess does not support. XenAccess might work, or it might not. This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_0_4 1

Constant used to indicate that we are running on Xen 3.0.4. This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_1_0 3

Constant used to indicate that we are running on Xen 3.1.0 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_1_1 4

Constant used to indicate that we are running on Xen 3.1.1 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_1_2 5

Constant used to indicate that we are running on Xen 3.1.2 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_1_3 6

Constant used to indicate that we are running on Xen 3.1.3 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_1_4 7

Constant used to indicate that we are running on Xen 3.1.4 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_2_0 8

Constant used to indicate that we are running on Xen 3.2.0 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_2_1 9

Constant used to indicate that we are running on Xen 3.2.1 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_2_2 10

Constant used to indicate that we are running on Xen 3.2.2 This is used in the xen_version member of the xa_instance struct.

#define XA_XENVER_3_3_0 11

Constant used to indicate that we are running on Xen 3.3.0 This is used in the xen_version member of the xa_instance struct.

typedef struct xa_instance xa_instance_t

XenAccess instance.

This struct holds all of the relavent information for an instance of XenAccess. Each time a new domain is accessed, a new instance must be created using the xa_init function. When you are done with an instance, its resources can be freed using the xa_destroy function.

typedef struct xa_linux_taskaddr xa_linux_taskaddr_t

Linux task information.

This struct holds the task addresses that are found in a task's memory descriptor. You can fill the values in the struct using the xa_linux_get_taskaddr function. The comments next to each entry are taken from Bovet & Cesati's excellent book Understanding the Linux Kernel 3rd Ed, p354.

typedef struct xa_windows_peb xa_windows_peb_t

Windows PEB information.

This struct holds process information found in the PEB, which is part of the EPROCESS structure. You can fill the values in the struct using the xa_windows_get_peb function. Note that this struct does not contain all information from the PEB.

int xa_init_vm_name_strict	(	char *	domain_name,
		xa_instance_t *	instance
	)

Initializes access to a specific domU given a domain name. All calls to xa_init must eventually call xa_destroy.

This function will fail if any problems are detected upon init. If you want to use XenAccess with reduced functionality instead of failing during initialization, then use the lax function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per domain, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	domain_name	Domain name to access, specified as a string
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_init_vm_name_lax	(	char *	domain_name,
		xa_instance_t *	instance
	)

Initializes access to a specific domU given a domain name. All calls to xa_init must eventually call xa_destroy.

This function will init unless a critical error is found. In some cases minor errors can lead to reduced functionality. If you want to ensure that XenAccess has full functionality, then use the strict function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per domain, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	domain_name	Domain name to access, specified as a string
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_init_vm_id_strict	(	uint32_t	domain_id,
		xa_instance_t *	instance
	)

Initializes access to a specific domU given a domain id. The domain id must represent an active domain and must be > 0. All calls to xa_init must eventually call xa_destroy.

This function will fail if any problems are detected upon init. If you want to use XenAccess with reduced functionality instead of failing during initialization, then use the lax function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per domain, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	domain_id	Domain id to access, specified as a number
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_init_vm_id_lax	(	uint32_t	domain_id,
		xa_instance_t *	instance
	)

Initializes access to a specific domU given a domain id. The domain id must represent an active domain and must be > 0. All calls to xa_init must eventually call xa_destroy.

This function will init unless a critical error is found. In some cases minor errors can lead to reduced functionality. If you want to ensure that XenAccess has full functionality, then use the strict function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per domain, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	domain_id	Domain id to access, specified as a number
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_init_file_strict	(	char *	filename,
		char *	image_type,
		xa_instance_t *	instance
	)

Initializes access to a memory image stored in the given file. All calls to xa_init_file must eventually call xa_destroy.

This function will fail if any problems are detected upon init. If you want to use XenAccess with reduced functionality instead of failing during initialization, then use the lax function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per file, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	filename	Name of memory image file
`[in]`	image_type	Name of config file entry for this image
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_init_file_lax	(	char *	filename,
		char *	image_type,
		xa_instance_t *	instance
	)

Initializes access to a memory image stored in the given file. All calls to xa_init_file must eventually call xa_destroy.

This function will init unless a critical error is found. In some cases minor errors can lead to reduced functionality. If you want to ensure that XenAccess has full functionality, then use the strict function instead.

This is a costly funtion in terms of the time needed to execute. You should call this function only once per file, and then use the resulting instance when calling any of the other library functions.

Parameters:

`[in]`	filename	Name of memory image file
`[in]`	image_type	Name of config file entry for this image
`[out]`	instance	Struct that holds instance information

Returns:: XA_SUCCESS or XA_FAILURE

int xa_destroy ( xa_instance_t * instance )

Destroys an instance by freeing memory and closing any open handles.

Parameters:

[in] instance Instance to destroy

Returns:: XA_SUCCESS or XA_FAILURE

void* xa_access_pa	(	xa_instance_t *	instance,
		uint32_t	phys_address,
		uint32_t *	offset,
		int	prot
	)

Memory maps page in domU that contains given physical address. The mapped memory is read-only.

Parameters:

`[in]`	instance	Handle to xenaccess instance.
`[in]`	phys_address	Requested physical address.
`[out]`	offset	Offset of the address in returned page.
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Address of a page copy that contains phys_address.

void* xa_access_ma	(	xa_instance_t *	instance,
		uint32_t	mach_address,
		uint32_t *	offset,
		int	prot
	)

Memory maps page in domU that contains given machine address. For more info about machine, virtual and pseudo-physical page see xen dev docs.

Parameters:

`[in]`	instance	Handle to xenaccess instance.
`[in]`	mach_address	Requested machine address.
`[out]`	offset	Offset of the address in returned page.
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Address of a page copy with content like mach_address.

void* xa_access_kernel_sym	(	xa_instance_t *	instance,
		char *	symbol,
		uint32_t *	offset,
		int	prot
	)

Memory maps one page from domU to a local address range. The memory to be mapped is specified with a kernel symbol (e.g., from System.map on linux). This memory must be unmapped manually with munmap.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	symbol	Desired kernel symbol to access
`[out]`	offset	Offset to kernel symbol within the mapped memory
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Beginning of mapped memory page or NULL on error

void* xa_access_kernel_va	(	xa_instance_t *	instance,
		uint32_t	virt_address,
		uint32_t *	offset,
		int	prot
	)

Memory maps one page from domU to a local address range. The memory to be mapped is specified with a kernel virtual address. This memory must be unmapped manually with munmap.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	virt_address	Virtual address to access
`[out]`	offset	Offset to address within the mapped memory
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Beginning of mapped memory page or NULL on error

void* xa_access_kernel_va_range	(	xa_instance_t *	instance,
		uint32_t	virt_address,
		uint32_t	size,
		uint32_t *	offset,
		int	prot
	)

Memory maps multiple pages from domU to a local address range. The memory to be mapped is specified with a kernel virtual address. This memory must be unmapped manually with munmap.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	virt_address	Desired virtual address to access
`[in]`	size	Size in bytes of the accessed range
`[out]`	offset	Offset to the address within mapped memory
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Beginning of the mapped memory pages or NULL on error

void* xa_access_user_va	(	xa_instance_t *	instance,
		uint32_t	virt_address,
		uint32_t *	offset,
		int	pid,
		int	prot
	)

Memory maps one page from domU to a local address range. The memory to be mapped is specified with a virtual address from a process' address space. This memory must be unmapped manually with munmap.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	virt_address	Desired virtual address to access
`[out]`	offset	Offset to address within the mapped memory
`[in]`	pid	PID of process' address space to use. If you specify 0 here, XenAccess will access the kernel virtual address space and this function's behavior will be the same as xa_access_virtual_address.
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Beginning of mapped memory page or NULL on error

void* xa_access_user_va_range	(	xa_instance_t *	instance,
		uint32_t	virt_address,
		uint32_t	size,
		uint32_t *	offset,
		int	pid,
		int	prot
	)

Memory maps multiple pages from domU to a local address range. the memory to be mapped is specified by a virtual address from process' address space. Data structures that span multiple pages can be mapped without dealing with fragmentation.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	virt_address	Desired virtual address to access
`[in]`	size	Size in bytes of the accessed range
`[out]`	offset	Offset to the address within mapped memory
`[in]`	pid	PID of process' address space to use. If you specify 0 here, XenAccess will access the kernel virtual address space and this function's be the same as xa_access_virtual_range.
`[in]`	prot	Desired memory protection (PROT_READ, PROT_WRITE, etc)

Returns:: Beginning of the mapped memory pages or NULL on error

uint32_t xa_translate_kv2p	(	xa_instance_t *	instance,
		uint32_t	virt_address
	)

Performs the translation from a kernel virtual address to a physical address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	virt_address	Desired kernel virtual address to translate

Returns:: Physical address, or zero on error

int xa_read_long_sym	(	xa_instance_t *	instance,
		char *	sym,
		uint32_t *	value
	)

Reads a long (32 bit) value from memory, given a kernel symbol.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	sym	Kernel symbol to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_long_sym	(	xa_instance_t *	instance,
		char *	sym,
		uint64_t *	value
	)

Reads a long long (64 bit) value from memory, given a kernel symbol.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	sym	Kernel symbol to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_virt	(	xa_instance_t *	instance,
		uint32_t	vaddr,
		int	pid,
		uint32_t *	value
	)

Reads a long (32 bit) value from memory, given a virtual address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	vaddr	Virtual address to read from
`[in]`	pid	Pid of the virtual address space (0 for kernel)
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_long_virt	(	xa_instance_t *	instance,
		uint32_t	vaddr,
		int	pid,
		uint64_t *	value
	)

Reads a long long (64 bit) value from memory, given a virtual address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	vaddr	Virtual address to read from
`[in]`	pid	Pid of the virtual address space (0 for kernel)
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_phys	(	xa_instance_t *	instance,
		uint32_t	paddr,
		uint32_t *	value
	)

Reads a long (32 bit) value from memory, given a physical address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	paddr	Physical address to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_long_phys	(	xa_instance_t *	instance,
		uint32_t	paddr,
		uint64_t *	value
	)

Reads a long long (64 bit) value from memory, given a physical address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	paddr	Physical address to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_mach	(	xa_instance_t *	instance,
		uint32_t	maddr,
		uint32_t *	value
	)

Reads a long (32 bit) value from memory, given a machine address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	maddr	Machine address to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_read_long_long_mach	(	xa_instance_t *	instance,
		uint32_t	maddr,
		uint64_t *	value
	)

Reads a long long (64 bit) value from memory, given a machine address.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	maddr	Machine address to read from
`[out]`	value	The value read from memory

Returns:: XA_SUCCESS or XA_FAILURE

int xa_symbol_to_address	(	xa_instance_t *	instance,
		char *	sym,
		uint32_t *	vaddr
	)

Looks up the virtual address of an exported kernel symbol.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	sym	Kernel symbol (must be exported)
`[out]`	vaddr	The virtual address of the symbol

Returns:: XA_SUCCESS or XA_FAILURE

int xa_linux_get_taskaddr	(	xa_instance_t *	instance,
		int	pid,
		xa_linux_taskaddr_t *	taskaddr
	)

Extracts information about the specified process' location in memory from the task struct specified by pid.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	pid	The PID for the task to read from
`[out]`	taskaddr	Information from the specified task struct

Returns:: XA_SUCCESS or XA_FAILURE

int xa_windows_get_peb	(	xa_instance_t *	instance,
		int	pid,
		xa_windows_peb_t *	peb
	)

Extracts information from the PEB struct, which is located at the top of the EPROCESS struct with the specified pid.

Parameters:

`[in]`	instance	XenAccess instance
`[in]`	pid	The unique ID for the PEB to read from
`[out]`	peb	Information from the specified PEB

Returns:: XA_SUCCESS or XA_FAILURE

xenaccess.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation


Data Structures
struct	xa_cache_entry
struct	xa_pid_cache_entry
struct	xa_instance
	XenAccess instance. More...
struct	xa_linux_taskaddr
	Linux task information. More...
struct	xa_windows_peb
	Windows PEB information. More...
Defines
#define	XA_MODE_XEN 0
#define	XA_MODE_FILE 1
#define	XA_FILETYPE_DD 0
#define	XA_SUCCESS 0
#define	XA_FAILURE -1
#define	XA_FAILHARD 0
#define	XA_FAILSOFT 1
#define	XA_OS_LINUX 0
#define	XA_OS_WINDOWS 1
#define	XA_XENVER_UNKNOWN 0
#define	XA_XENVER_3_0_4 1
#define	XA_XENVER_3_1_0 3
#define	XA_XENVER_3_1_1 4
#define	XA_XENVER_3_1_2 5
#define	XA_XENVER_3_1_3 6
#define	XA_XENVER_3_1_4 7
#define	XA_XENVER_3_2_0 8
#define	XA_XENVER_3_2_1 9
#define	XA_XENVER_3_2_2 10
#define	XA_XENVER_3_3_0 11
Typedefs
typedef xa_instance	xa_instance_t
	XenAccess instance.
typedef xa_linux_taskaddr	xa_linux_taskaddr_t
	Linux task information.
typedef xa_windows_peb	xa_windows_peb_t
	Windows PEB information.
Functions
int	xa_init_vm_name_strict (char domain_name, xa_instance_t instance)
int	xa_init_vm_name_lax (char domain_name, xa_instance_t instance)
int	xa_init_vm_id_strict (uint32_t domain_id, xa_instance_t *instance)
int	xa_init_vm_id_lax (uint32_t domain_id, xa_instance_t *instance)
int	xa_init_file_strict (char filename, char image_type, xa_instance_t *instance)
int	xa_init_file_lax (char filename, char image_type, xa_instance_t *instance)
int	xa_destroy (xa_instance_t *instance)
void *	xa_access_pa (xa_instance_t instance, uint32_t phys_address, uint32_t offset, int prot)
void *	xa_access_ma (xa_instance_t instance, uint32_t mach_address, uint32_t offset, int prot)
void *	xa_access_kernel_sym (xa_instance_t instance, char symbol, uint32_t *offset, int prot)
void *	xa_access_kernel_va (xa_instance_t instance, uint32_t virt_address, uint32_t offset, int prot)
void *	xa_access_kernel_va_range (xa_instance_t instance, uint32_t virt_address, uint32_t size, uint32_t offset, int prot)
void *	xa_access_user_va (xa_instance_t instance, uint32_t virt_address, uint32_t offset, int pid, int prot)
void *	xa_access_user_va_range (xa_instance_t instance, uint32_t virt_address, uint32_t size, uint32_t offset, int pid, int prot)
uint32_t	xa_translate_kv2p (xa_instance_t *instance, uint32_t virt_address)
int	xa_read_long_sym (xa_instance_t instance, char sym, uint32_t *value)
int	xa_read_long_long_sym (xa_instance_t instance, char sym, uint64_t *value)
int	xa_read_long_virt (xa_instance_t instance, uint32_t vaddr, int pid, uint32_t value)
int	xa_read_long_long_virt (xa_instance_t instance, uint32_t vaddr, int pid, uint64_t value)
int	xa_read_long_phys (xa_instance_t instance, uint32_t paddr, uint32_t value)
int	xa_read_long_long_phys (xa_instance_t instance, uint32_t paddr, uint64_t value)
int	xa_read_long_mach (xa_instance_t instance, uint32_t maddr, uint32_t value)
int	xa_read_long_long_mach (xa_instance_t instance, uint32_t maddr, uint64_t value)
int	xa_symbol_to_address (xa_instance_t instance, char sym, uint32_t *vaddr)
int	xa_linux_get_taskaddr (xa_instance_t instance, int pid, xa_linux_taskaddr_t taskaddr)
int	xa_windows_get_peb (xa_instance_t instance, int pid, xa_windows_peb_t peb)