xenaccess.h File Reference

The primary XenAccess API is defined here. More...

Go to the source code of this file.

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)


Detailed Description

The primary XenAccess API is defined here.

More detailed description can go here.


Define Documentation

#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 Documentation

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.


Function Documentation

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


Generated on Thu Dec 18 13:28:46 2008 for XenAccess by  doxygen 1.4.7