Functions

status_t vmi_init (vmi_instance_t *vmi, vmi_mode_t mode, const void *domain, uint64_t init_flags, vmi_init_data_t *init_data, vmi_init_error_t *error) NOEXCEPT
Initializes access to a specific VM or file given a name or an ID. All calls to vmi_init must eventually call vmi_destroy.
This is a costly funtion in terms of the time needed to execute. You should call this function only once per VM or file, and then use the resulting instance when calling any of the other library functions.
When this function returns VMI_SUCCESS, you will have access to the physical memory of the target VM, as well as vCPU register functions. If you need access to virtual-to-physical translation or OS specific information, you will further need to call the appropriate init functions. Alternatively, you can use vmi_init_complete to initialize access to all LibVMI functions.
Parameters
- [out] vmi Struct that holds instance information
- [in] mode Specifying the hypervisor mode to init You can call vmi_get_access_mode prior to calling vmi_init to automatically determine this.
- [in] domain Unique name or id specifying the VM or file to view Need to specify whether this is a domainname or domainid by setting either VMI_INIT_DOMAINNAME or VMI_INIT_DOMAINID on init_flags.
- [in] init_flags Init flags to specify the domain input (name or id) and to initialize further LibVMI features, such as events. See VMI_INIT_* declarations above.
- [in] init_data In case initialization requires additional information for a given hypervisor, it can be provided via this input.
- [out] error Optional. If not NULL and the function returns VMI_FAILURE, this will specify the stage at which initialization failed.
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_init_complete (vmi_instance_t *vmi, const void *domain, uint64_t init_flags, vmi_init_data_t *init_data, vmi_config_t config_mode, void *config, vmi_init_error_t *error) NOEXCEPT
Initializes access to a specific VM or file given a name or an ID. All calls to vmi_init_complete must eventually call vmi_destroy.
This is a costly funtion in terms of the time needed to execute. You should call this function only once per VM or file, and then use the resulting instance when calling any of the other library functions.
When this function returns VMI_SUCCESS, you will have access to the physical memory of the target VM, accessing vCPU registers, virtual-to-physcal translation as well as OS specific functions.
Parameters
- [out] vmi Struct that holds instance information
- [in] domain Unique name or id specifying the VM or file to view Need to specify whether this is a domainname or domainid by setting either VMI_INIT_DOMAINNAME or VMI_INIT_DOMAINID on init_flags.
- [in] init_flags Additional flags to initialize See VMI_INIT_* declarations above.
- [in] init_data In case initialization requires additional information for a given hypervisor, it can be provided via this input.
- [in] config_mode The type of OS configuration that is provided.
- [in] config Configuration is passed directly to LibVMI (ie. in a string or in a GHashTable) or NULL of global config file is used.
- [out] error Optional. If not NULL and the function returns VMI_FAILURE, this will specify the stage at which initialization failed.
Returns
- VMI_SUCCESS or VMI_FAILURE

page_mode_t vmi_init_paging (vmi_instance_t vmi, uint64_t flags) NOEXCEPT
Initialize or reinitialize the paging specific functionality of LibVMI required for virtual-to-physical translation.
Note: this function is designed only for live VMs (ie. VMI_XEN or VMI_KVM). and will not work in VMI_FILE mode as that requires OS-specific heuristics.
Parameters
- [in] vmi LibVMI instance
- [in] paging_flags Additional flags to configure paging using VMI_PM_INITFLAG_* values.
Returns
- The page mode that was initialized, or VMI_PM_UNKNOWN.

os_t vmi_init_os (vmi_instance_t vmi, vmi_config_t config_mode, void *config, vmi_init_error_t *error) NOEXCEPT
Initialize the OS specific functionality of LibVMI required for functions such as vmi_*_ksym. If the user hasn't called vmi_init_paging yet, this function will do that automatically.
Parameters
- [in] vmi LibVMI instance
- [in] config_mode The type of OS configuration that is provided.
- [in] config Configuration is passed directly to LibVMI (ie. in a string or in a GHashTable) or NULL if global config file is used.
- [out] error Optional. If not NULL and the function returns VMI_OS_UNKNOWN, this will specify the stage at which initialization failed.
Returns
- VMI_OS_UNKNOWN when the configuration didn't work for the VM, otherwise the OS type that has been initialized (ie. VMI_OS_WINDOWS or VMI_OS_LINUX).

status_t vmi_destroy (vmi_instance_t vmi) NOEXCEPT
Destroys an instance by freeing memory and closing any open handles.
Parameters
- [in] vmi Instance to destroy
Returns
- VMI_SUCCESS or VMI_FAILURE

vmi_arch_t vmi_get_library_arch (void) NOEXCEPT
Obtain the library arch mode that was used for compiling.
Parameters
- [in] vmi LibVMI instance
Returns
- The architecture of the library

status_t vmi_translate_kv2p (vmi_instance_t vmi, addr_t vaddr, addr_t *paddr) NOEXCEPT
Performs the translation from a kernel virtual address to a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Desired kernel virtual address to translate
- [out] paddr Physical address
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_translate_uv2p (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, addr_t *paddr) NOEXCEPT
Performs the translation from a user virtual address to a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Desired kernel virtual address to translate
- [in] pid Process id for desired user address space
- [out] paddr Physical address
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_translate_ksym2v (vmi_instance_t vmi, const char *symbol, addr_t *vaddr) NOEXCEPT
Performs the translation from a kernel symbol to a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] symbol Desired kernel symbol to translate
- [out] paddr Virtual address
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_translate_sym2v (vmi_instance_t vmi, const access_context_t *ctx, const char *symbol, addr_t *vaddr) NOEXCEPT
Performs the translation from a symbol to a virtual address. On Windows this function walks the PE export table. Linux is unimplemented at this time.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context (beginning of PE header in Windows)
- [in] symbol Desired symbol to translate
- [out] vaddr Virtual address
Returns
- VMI_SUCCESS or VMI_FAILURE

const char* vmi_translate_v2sym (vmi_instance_t vmi, const access_context_t *ctx, addr_t rva) NOEXCEPT
Performs the translation from an RVA to a symbol On Windows this function walks the PE export table. Only the first matching symbol of System.map is returned. ELF Headers are not supported.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context (beginning of PE header in Windows)
- [in] rva RVA to translate
Returns
- Symbol, or NULL on error

const char* vmi_translate_v2ksym (vmi_instance_t vmi, const access_context_t *ctx, addr_t va) NOEXCEPT
Performs the translation from VA to a symbol for Linux with KASLR offset Windows is not supported at this moment Only the first matching symbol of System.map is returned.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] va VA to translate
Returns
- Symbol, or NULL on error

status_t vmi_pid_to_dtb (vmi_instance_t vmi, vmi_pid_t pid, addr_t *dtb) NOEXCEPT
Given a pid, this function returns the virtual address of the directory table base for this process' address space. This value is effectively what would be in the CR3 register while this process is running.
Note: this function uses OS internal linked-lists to find a match but these lists are not guaranteed to be complete and accurate. Use of this function is discouraged when using events.
Note: Use of this function is discouraged with events.
Parameters
- [in] vmi LibVMI instance
- [in] pid Desired process id to lookup
- [out] dtb The directory table base virtual address for a pid
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_dtb_to_pid (vmi_instance_t vmi, addr_t dtb, vmi_pid_t *pid) NOEXCEPT
Given a dtb, this function returns the PID corresponding to the virtual address of the directory table base. This function does NOT implement caching as to avoid false mappings.
Note: this function uses OS internal linked-lists to find a match but these lists are not guaranteed to be complete and accurate. Use of this function is discouraged when using events.
Note: On Linux certain PIDs don't have their own dtb (task->mm) and rather re-use other process' dtb (task->active_mm). In such case the PID returned by this function will be that of the "owning" process.
Note: Use of this function is discouraged with events.
Parameters
- [in] vmi LibVMI instance
- [in] dtb Desired dtb to lookup
- [out] pid The PID corresponding to the dtb
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_pagetable_lookup (vmi_instance_t vmi, addr_t pt, addr_t vaddr, addr_t *paddr) NOEXCEPT
Translates a virtual address to a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] pt address of the relevant pagetable
- [in] vaddr virtual address to translate via dtb
- [out] paddr Physical address
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_pagetable_lookup_extended (vmi_instance_t vmi, addr_t pt, addr_t vaddr, page_info_t *info) NOEXCEPT
Gets the physical address and page size of the VA as well as the addresses of other paging related structures depending on the page mode of the VM.
Parameters
- [in] vmi LibVMI instance
- [in] pt address of the relevant pagetable
- [in] vaddr virtual address to translate via dtb
- [inout] info Pointer to the struct to store the lookup information in
Returns
- VMI_SUCCESS or VMI_FAILURE of the VA is invalid

status_t vmi_nested_pagetable_lookup (vmi_instance_t vmi, addr_t npt, page_mode_t npm, addr_t pt, page_mode_t pm, addr_t vaddr, addr_t *paddr, addr_t *naddr) NOEXCEPT
Translates a virtual address to a physical address, supporting nested pagetables (ie. EPT). Can be called with npm set to VMI_PM_NONE, in which case this function is equivalent to vmi_pagetable_lookup.
To perform only nested pagetable lookup of an l2 guest paddr use pt and pm with the nested pagetable address and mode.
Parameters
- [in] vmi LibVMI instance
- [in] npt address of the nested pagetable
- [in] npm page mode to use for lookup in nested pagetable
- [in] pt address of the relevant pagetable
- [in] pm page mode to use for lookup.
- [in] vaddr virtual address to translate via dtb
- [out] paddr Guest physical address (l2) value is set to ~0ull if npm is set and translation was in the v2p cache
- [out] naddr Guest nested physical address (l1) if npm is set
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_nested_pagetable_lookup_extended (vmi_instance_t vmi, addr_t npt, page_mode_t npm, addr_t pt, page_mode_t pm, addr_t vaddr, page_info_t *info) NOEXCEPT
Gets the physical address and page size of the VA as well as the addresses of other paging related structures depending on the page mode(s), supprting nested pagetables (ie. EPT).
Parameters
- [in] vmi LibVMI instance
- [in] npt address of the nested pagetable
- [in] npm page mode to use for lookup in nested pagetable
- [in] pt address of the relevant pagetable
- [in] pm page mode to use for lookup
- [in] vaddr virtual address to translate via dtb
- [inout] info Pointer to the struct to store the lookup information in
Returns
- VMI_SUCCESS or VMI_FAILURE of the VA is invalid

status_t vmi_read (vmi_instance_t vmi, const access_context_t *ctx, size_t count, void *buf, size_t *bytes_read) NOEXCEPT
Reads count bytes from memory and stores the output in a buf.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] count The number of bytes to read
- [out] buf The data read from memory
- [out] bytes_read Optional. The number of bytes read
Returns
- VMI_SUCCESS if read is complete, VMI_FAILURE otherwise

status_t vmi_read_8 (vmi_instance_t vmi, const access_context_t *ctx, uint8_t *value) NOEXCEPT
Reads 8 bits from memory.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_16 (vmi_instance_t vmi, const access_context_t *ctx, uint16_t *value) NOEXCEPT
Reads 16 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_32 (vmi_instance_t vmi, const access_context_t *ctx, uint32_t *value) NOEXCEPT
Reads 32 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_64 (vmi_instance_t vmi, const access_context_t *ctx, uint64_t *value) NOEXCEPT
Reads 64 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_addr (vmi_instance_t vmi, const access_context_t *ctx, addr_t *value) NOEXCEPT
Reads an address from memory, given a virtual address. The number of bytes read is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

char* vmi_read_str (vmi_instance_t vmi, const access_context_t *ctx) NOEXCEPT
Reads a null terminated string from memory, starting at the given virtual address. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
Returns
- String read from memory or NULL on error

unicode_string_t* vmi_read_unicode_str (vmi_instance_t vmi, const access_context_t *ctx) NOEXCEPT
Reads a Unicode string from the given address. If the guest is running Windows, a UNICODE_STRING struct is read. Linux is not yet supported. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
Returns
- String read from memory or NULL on error; this function will set the encoding field.

unicode_string_t* vmi_read_unicode_str_pm (vmi_instance_t vmi, const access_context_t *ctx, page_mode_t mode) NOEXCEPT
Reads a Unicode string from the given address using the specified page mode. This is needed for introspecting Windows-on-Windows (WoW) processes that are 32-bit code running on 64-bit OS. If the guest is running Windows, a UNICODE_STRING struct is read. Linux is not yet supported. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] mode Memory page mode
Returns
- String read from memory or NULL on error; this function will set the encoding field.

status_t vmi_read_ksym (vmi_instance_t vmi, const char *sym, size_t count, void *buf, size_t *bytes_read) NOEXCEPT
Reads count bytes from memory located at the kernel symbol sym and stores the output in a buf.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [in] count The number of bytes to read
- [out] buf The data read from memory
- [out] bytes_read Optional. The number of bytes read
Returns
- VMI_SUCCESS if read is complete, VMI_FAILURE otherwise

status_t vmi_read_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, size_t count, void *buf, size_t *bytes_read) NOEXCEPT
Reads count bytes from memory located at the virtual address vaddr and stores the output in buf.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to read from
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] count The number of bytes to read
- [out] buf The data read from memory
- [out] bytes_read Optional. The number of bytes read
Returns
- VMI_SUCCESS if read is complete, VMI_FAILURE otherwise

status_t vmi_mmap_guest (vmi_instance_t vmi, const access_context_t *ctx, size_t num_pages, void **access_ptrs) NOEXCEPT
Maps num_pages of the guest's virtual memory into host, starting at the provided vaddr. Each page will have it's own pointer in access_ptrs output array. Be aware that not all virtual pages may be allocated and in such case, the corresponding array item will be set to NULL. Remember to call munmap() on each array item afterwards.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] num_pages Number of guest pages to be mapped (starting from ctx.addr)
- [out] access_ptrs Output array of size [num_pages] containing pointers to the respective guest's pages

status_t vmi_read_pa (vmi_instance_t vmi, addr_t paddr, size_t count, void *buf, size_t *bytes_read) NOEXCEPT
Reads count bytes from memory located at the physical address paddr and stores the output in a buf.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [in] count The number of bytes to read
- [out] buf The data read from memory
- [out] bytes_read Optional. The number of bytes read
Returns
- VMI_SUCCESS if read is complete, VMI_FAILURE otherwise

status_t vmi_read_8_ksym (vmi_instance_t vmi, const char *sym, uint8_t *value) NOEXCEPT
Reads 8 bits from memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_16_ksym (vmi_instance_t vmi, const char *sym, uint16_t *value) NOEXCEPT
Reads 16 bits from memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_32_ksym (vmi_instance_t vmi, const char *sym, uint32_t *value) NOEXCEPT
Reads 32 bits from memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_64_ksym (vmi_instance_t vmi, const char *sym, uint64_t *value) NOEXCEPT
Reads 64 bits from memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_addr_ksym (vmi_instance_t vmi, const char *sym, addr_t *value) NOEXCEPT
Reads an address from memory, given a kernel symbol. The number of bytes read is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

char* vmi_read_str_ksym (vmi_instance_t vmi, const char *sym) NOEXCEPT
Reads a null-terminated string from memory, starting at the given kernel symbol. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol for memory location where string starts
Returns
- String read from memory or NULL on error

status_t vmi_read_8_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint8_t *value) NOEXCEPT
Reads 8 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_16_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint16_t *value) NOEXCEPT
Reads 16 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_32_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint32_t *value) NOEXCEPT
Reads 32 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_64_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint64_t *value) NOEXCEPT
Reads 64 bits from memory, given a virtual address.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_addr_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, addr_t *value) NOEXCEPT
Reads an address from memory, given a virtual address. The number of bytes read is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI 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
- VMI_SUCCESS or VMI_FAILURE

char* vmi_read_str_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid) NOEXCEPT
Reads a null terminated string from memory, starting at the given virtual address. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address for start of string
- [in] pid Pid of the virtual address space (0 for kernel)
Returns
- String read from memory or NULL on error

unicode_string_t* vmi_read_unicode_str_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid) NOEXCEPT
Reads a Unicode string from the given address. If the guest is running Windows, a UNICODE_STRING struct is read. Linux is not yet supported. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address of the UNICODE_STRING structure
- [in] pid Pid of the virtual address space (0 for kernel)
Returns
- String read from memory or NULL on error; this function will set the encoding field.

status_t vmi_convert_str_encoding (const unicode_string_t *in, unicode_string_t *out, const char *outencoding) NOEXCEPT
Converts character encoding from that in the input string to another specified encoding. Two common ways to use this function are: (1) convert a string to the "UTF-8" encoding and output with printf("%s") NOEXCEPT; (2) convert a string to the "WCHAR_T" encoding and output with printf("%ls").
Parameters
- [in] in unicode_string_t to be converted; encoding field must be set
- [in] out output unicode_string_t, allocated by caller (this function allocates the contents field)
- [in] outencoding output encoding, must be compatible with the iconv function
Returns
- status code

void vmi_free_unicode_str (unicode_string_t *p_us) NOEXCEPT
Convenience function to free a unicode_string_t struct.
Parameters
- [in] p_us Pointer to a unicode_string_t struct
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_8_pa (vmi_instance_t vmi, addr_t paddr, uint8_t *value) NOEXCEPT
Reads 8 bits from memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_16_pa (vmi_instance_t vmi, addr_t paddr, uint16_t *value) NOEXCEPT
Reads 16 bits from memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_32_pa (vmi_instance_t vmi, addr_t paddr, uint32_t *value) NOEXCEPT
Reads 32 bits from memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_64_pa (vmi_instance_t vmi, addr_t paddr, uint64_t *value) NOEXCEPT
Reads 64 bits from memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_read_addr_pa (vmi_instance_t vmi, addr_t paddr, addr_t *value) NOEXCEPT
Reads an address from memory, given a physical address. The number of bytes read is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to read from
- [out] value The value read from memory
Returns
- VMI_SUCCESS or VMI_FAILURE

char* vmi_read_str_pa (vmi_instance_t vmi, addr_t paddr) NOEXCEPT
Reads a nul terminated string from memory, starting at the given physical address. The returned value must be freed by the caller.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address for start of string
Returns
- String read from memory or NULL on error

status_t vmi_write (vmi_instance_t vmi, const access_context_t *ctx, size_t count, void *buf, size_t *bytes_written) NOEXCEPT
Writes count bytes to memory
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] count The number of bytes to write
- [in] buf The data written to memory
- [out] bytes_written Optional. The numer of bytes written
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_ksym (vmi_instance_t vmi, const char *sym, size_t count, void *buf, size_t *bytes_written) NOEXCEPT
Writes count bytes to memory located at the kernel symbol sym from a buf.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] count The number of bytes to write
- [in] buf The data written to memory
- [out] bytes_written Optional. The numer of bytes written
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, size_t count, void *buf, size_t *bytes_written) NOEXCEPT
Writes count bytes to memory located at the virtual address vaddr from buf.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] count The number of bytes to write
- [in] buf The data written to memory
- [out] bytes_written Optional. The numer of bytes written
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_pa (vmi_instance_t vmi, addr_t paddr, size_t count, void *buf, size_t *bytes_written) NOEXCEPT
Writes count bytes to memory located at the physical address paddr from buf.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] buf The data written to memory
- [in] count The number of bytes to write
- [out] bytes_written Optional. The numer of bytes written
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_8 (vmi_instance_t vmi, const access_context_t *ctx, uint8_t *value) NOEXCEPT
Writes 8 bits to memory
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_16 (vmi_instance_t vmi, const access_context_t *ctx, uint16_t *value) NOEXCEPT
Writes 16 bits to memory
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_32 (vmi_instance_t vmi, const access_context_t *ctx, uint32_t *value) NOEXCEPT
Writes 32 bits to memory
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_64 (vmi_instance_t vmi, const access_context_t *ctx, uint64_t *value) NOEXCEPT
Writes 64 bits to memory
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_addr (vmi_instance_t vmi, const access_context_t *ctx, addr_t *value) NOEXCEPT
Writes the address to memory. The number of bytes written is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] ctx Access context
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_8_ksym (vmi_instance_t vmi, const char *sym, uint8_t *value) NOEXCEPT
Writes 8 bits to memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_16_ksym (vmi_instance_t vmi, const char *sym, uint16_t *value) NOEXCEPT
Writes 16 bits to memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_32_ksym (vmi_instance_t vmi, const char *sym, uint32_t *value) NOEXCEPT
Writes 32 bits to memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_64_ksym (vmi_instance_t vmi, const char *sym, uint64_t *value) NOEXCEPT
Writes 64 bits to memory, given a kernel symbol.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_addr_ksym (vmi_instance_t vmi, const char *sym, addr_t *value) NOEXCEPT
Writes the address to memory. The number of bytes written is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_8_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint8_t *value) NOEXCEPT
Writes 8 bits to memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_16_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint16_t *value) NOEXCEPT
Writes 16 bits to memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_32_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint32_t *value) NOEXCEPT
Writes 32 bits to memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_64_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, uint64_t *value) NOEXCEPT
Writes 64 bits to memory, given a virtual address.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_addr_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, addr_t *value) NOEXCEPT
Writes the address to memory. The number of bytes written is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to write to
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_8_pa (vmi_instance_t vmi, addr_t paddr, uint8_t *value) NOEXCEPT
Writes 8 bits to memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_16_pa (vmi_instance_t vmi, addr_t paddr, uint16_t *value) NOEXCEPT
Writes 16 bits to memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_32_pa (vmi_instance_t vmi, addr_t paddr, uint32_t *value) NOEXCEPT
Writes 32 bits to memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_64_pa (vmi_instance_t vmi, addr_t paddr, uint64_t *value) NOEXCEPT
Writes 64 bits from memory, given a physical address.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_write_addr_pa (vmi_instance_t vmi, addr_t paddr, addr_t *value) NOEXCEPT
Writes the address to memory. The number of bytes written is 8 for 64-bit systems and 4 for 32-bit systems.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to write to
- [in] value The value written to memory
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_print_hex (const unsigned char *data, unsigned long length) NOEXCEPT
Prints out the hex and ascii version of a chunk of bytes. The output is similar to what you would get with 'od -h' with the additional ascii information on the right side of the display.
Parameters
- [in] data The bytes that will be printed to stdout
- [in] length The length (in bytes) of data

void vmi_print_hex_ksym (vmi_instance_t vmi, const char *sym, size_t length) NOEXCEPT
Prints out the hex and ascii version of a chunk of bytes. The output is similar to what you would get with 'od -h' with the additional ascii information on the right side of the display.
Parameters
- [in] vmi LibVMI instance
- [in] sym Kernel symbol to use as starting address
- [in] length The length (in bytes) of data to print

void vmi_print_hex_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, size_t length) NOEXCEPT
Prints out the hex and ascii version of a chunk of bytes. The output is similar to what you would get with 'od -h' with the additional ascii information on the right side of the display.
Parameters
- [in] vmi LibVMI instance
- [in] vaddr Virtual address to use as starting address
- [in] pid Pid of the virtual address space (0 for kernel)
- [in] length The length (in bytes) of data to print

void vmi_print_hex_pa (vmi_instance_t vmi, addr_t paddr, size_t length) NOEXCEPT
Prints out the hex and ascii version of a chunk of bytes. The output is similar to what you would get with 'od -h' with the additional ascii information on the right side of the display.
Parameters
- [in] vmi LibVMI instance
- [in] paddr Physical address to use as starting address
- [in] length The length (in bytes) of data to print

char* vmi_get_name (vmi_instance_t vmi) NOEXCEPT
Gets the name of the VM (or file) that LibVMI is accessing.
Parameters
- [in] vmi LibVMI instance
Returns
- VM (or file) name, must be free'd by caller

uint64_t vmi_get_vmid (vmi_instance_t vmi) NOEXCEPT
Gets the id of the VM that LibVMI is accessing.
Parameters
- [in] vmi LibVMI instance
Returns
- VM id, or zero on error

status_t vmi_get_access_mode (vmi_instance_t vmi, const void *domain, uint64_t init_flags, vmi_init_data_t *init_data, vmi_mode_t *mode) NOEXCEPT
Gets the current access mode for LibVMI, which tells what resource is being using to access the memory (e.g., VMI_XEN, VMI_KVM, or VMI_FILE).
If LibVMI is already initialized it will return the active mode. If the LibVMI instance passed is NULL, it will automatically determine the mode.
Parameters
- [in] vmi LibVMI instance or NULL
- [in] domain Unique name or id specifying the VM or file to view Need to specify whether this is a domainname or domainid by setting either VMI_INIT_DOMAINNAME or VMI_INIT_DOMAINID on init_flags.
- [in] init_flags Init flags to specify the domain input (name or id) and to initialize further LibVMI features, such as events.
- [in] init_data In case initialization requires additional information for a given hypervisor, it can be provided via this input.
- [out] mode The access mode that was identified.
Returns
- VMI_SUCCESS if LibVMI was able to access a hypervisor and found the given domain; VMI_FAILURE otherwise.

page_mode_t vmi_get_page_mode (vmi_instance_t vmi, unsigned long vcpu) NOEXCEPT
Gets the current page mode for LibVMI, which tells what type of address translation is in use (e.g., VMI_PM_LEGACY, VMI_PM_PAE, or VMI_PM_IA32E).
On live VMs every call to this function will re-check the current state of the specified vCPU. For file-mode it will just return the page-mode that was determined using OS-specific heuristics.
Parameters
- [in] vmi LibVMI instance
Returns
- Page mode

uint8_t vmi_get_address_width (vmi_instance_t vmi) NOEXCEPT
Gets the current address width for the given vmi_instance_t
Note: relative to the OS mode, not that of a process. Also, if paging mode is altered after vmi_init, the information as recorded in vmi_instance_t will be stale and require re-initialization.
Parameters
- [in] vmi LibVMI instance
Returns
- address size in bytes

os_t vmi_get_ostype (vmi_instance_t vmi) NOEXCEPT
Get the OS type that LibVMI is currently accessing. This is simple windows or linux (no version information).
Parameters
- [in] vmi LibVMI instance
Returns
- OS type

bool vmi_get_windows_build_info (vmi_instance_t vmi, win_build_info_t *info) NOEXCEPT
Get the version info of Windows that LibVMI is currently accessing.
Parameters
- [in] vmi LibVMI instance
- [in] info Pointer to structure to fill
Returns
- True if success. False otherwise

win_ver_t vmi_get_winver (vmi_instance_t vmi) NOEXCEPT
Get the version of Windows that LibVMI is currently accessing. This is the simple Windows version - no service pack or patch level is provided.
Parameters
- [in] vmi LibVMI instance
Returns
- Windows version

uint16_t vmi_get_win_buildnumber (vmi_instance_t vmi) NOEXCEPT
Get the build number of Windows that LibVMI is currently accessing.
Parameters
- [in] vmi LibVMI instance
Returns
- Windows build number

const char* vmi_get_winver_str (vmi_instance_t vmi) NOEXCEPT
Get string represenatation of the version of Windows that LibVMI is currently accessing.
Parameters
- [in] vmi LibVMI instance
Returns
- string description of Windows version (do not free)

win_ver_t vmi_get_winver_manual (vmi_instance_t vmi, addr_t kdvb_pa) NOEXCEPT
Get the version of Windows based on the provided KDVB address. This is the simple Windows version - no service pack or patch level is provided.
This function is intended to be used during partial init as an aid to elevate to full init.
Parameters
- [in] vmi LibVMI instance
- [in] kdvb_pa The physical address of the KDVB
Returns
- Windows version

status_t vmi_get_offset (vmi_instance_t vmi, const char *offset_name, addr_t *offset) NOEXCEPT
Get the memory offset associated with the given offset_name. Valid names include everything in the /etc/libvmi.conf file.
Parameters
- [in] vmi LibVMI instance
- [in] offset_name String name for desired offset
- [out] offset The offset value
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_get_kernel_struct_offset (vmi_instance_t vmi, const char *struct_name, const char *member, addr_t *addr) NOEXCEPT
parameterlist
simplesect
#text

status_t vmi_get_xsave_info (vmi_instance_t vmi, unsigned long vcpu, xsave_area_t *xsave_info) NOEXCEPT
Gets the current value for a VCPU xsave info.When LibVMI is accessing a raw memory file or KVM, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
- [out] xsave_info Returned value of the xsave_info
Returns
- VMI_SUCCESS or VMI_FAILURE

uint64_t vmi_get_memsize (vmi_instance_t vmi) NOEXCEPT
Gets the memory size of the guest or file that LibVMI is currently accessing. This is the amount of RAM allocated to the guest, but does not necessarily indicate the highest addressable physical address; get_max_physical_address() should be used.
NOTE: if memory ballooning alters the allocation of memory to a VM after vmi_init, this information will have become stale and a re-initialization will be required.
Parameters
- [in] vmi LibVMI instance
Returns
- Memory size

addr_t vmi_get_max_physical_address (vmi_instance_t vmi) NOEXCEPT
Gets highest addressable physical memory address of the guest or file that LibVMI is currently accessing plus one. That is, any address less then the returned value "may be" a valid physical memory address, but the layout of the guest RAM is hypervisor specific, so there can and will be holes that are not memory pages and can't be read by libvmi.
NOTE: if memory ballooning alters the allocation of memory to a VM after vmi_init, this information will have become stale and a re-initialization will be required.
Parameters
- [in] vmi LibVMI instance
Returns
- physical memory size

unsigned int vmi_get_num_vcpus (vmi_instance_t vmi) NOEXCEPT
Gets the memory size of the guest that LibVMI is accessing. This information is required for any interaction with of VCPU registers.
Parameters
- [in] vmi LibVMI instance
Returns
- Number of VCPUs

status_t vmi_request_page_fault (vmi_instance_t vmi, unsigned long vcpu, uint64_t virtual_address, uint32_t error_code) NOEXCEPT
Injects a page fault trap. It is assumed that the guest is in user-mode and in the proper address space for the request to work.
Parameters
- [in] vmi LibVMI instance
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
- [in] virtual_address The cr2 address for requested page fault
- [in] error_code The error code for the requested page fault. ~0u means 'ignore'
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_get_tsc_info (vmi_instance_t vmi, uint32_t *tsc_mode, uint64_t *elapsed_nsec, uint32_t *gtsc_khz, uint32_t *incarnation) NOEXCEPT
Gets the current value for tsc info. This currently only supports x86 registers. When LibVMI is accessing a raw memory file or KVM, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [out] tsc_mode The tsc_mode value to be filled
- [out] elapsed_nsec The elapsed time in nano sec to be filled
- [out] gtsc_khz The guest tsc frequency in kHz
- [out] incarnation The guest tsc incarnation (migration count)
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_get_vcpumtrr (vmi_instance_t vmi, mtrr_regs_t *hwMtrr, unsigned long vcpu) NOEXCEPT
Gets the current value of VCPU mtrr registers. This currently only supports x86 registers. When LibVMI is accessing a raw memory file or KVM, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [out] hwMtrr The mtrr struct to be filled
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_get_vcpureg (vmi_instance_t vmi, uint64_t *value, reg_t reg, unsigned long vcpu) NOEXCEPT
Gets the current value of a VCPU register. This currently only supports control registers. When LibVMI is accessing a raw memory file, this function will fail.
NOTE: for some hypervisor drivers, it is important to understand the validity of the values that registers hold. For example, CR3 for Xen paravirtual VMs may hold a physical address higher than the maximum psuedophysical address of the given VM (this is an expected and correct idiosyncrasy of that platform). Similar scenarios exist for IDTR, etc.
Parameters
- [in] vmi LibVMI instance
- [out] value Returned value from the register, only valid on VMI_SUCCESS
- [in] reg The register to access
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_get_vcpuregs (vmi_instance_t vmi, registers_t *regs, unsigned long vcpu) NOEXCEPT
Gets the current value of VCPU registers. This currently only supports x86 registers. When LibVMI is accessing a raw memory file or KVM, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [out] regs The register struct to be filled
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_set_vcpureg (vmi_instance_t vmi, uint64_t value, reg_t reg, unsigned long vcpu) NOEXCEPT
Sets the current value of a VCPU register. This currently only supports control registers. When LibVMI is accessing a raw memory file, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [in] value Value to assign to the register
- [in] reg The register to access
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_set_vcpuregs (vmi_instance_t vmi, registers_t *regs, unsigned long vcpu) NOEXCEPT
Sets the vCPU registers to the ones passed in the struct. It is important to have a valid value in all registers when calling this function, so the user likely wants to call vmi_get_vcpuregs before calling this function. When LibVMI is accessing a raw memory file or KVM, this function will fail.
Parameters
- [in] vmi LibVMI instance
- [] LibVMI instance
- [in] vcpu The index of the VCPU to access, use 0 for single VCPU systems
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_pause_vm (vmi_instance_t vmi) NOEXCEPT
Pauses the VM. Use vmi_resume_vm to resume the VM after pausing it. If accessing a memory file, this has no effect.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

status_t vmi_resume_vm (vmi_instance_t vmi) NOEXCEPT
Resumes the VM. Use vmi_pause_vm to pause the VM before calling this function. If accessing a memory file, this has no effect.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_v2pcache_flush (vmi_instance_t vmi, addr_t pt) NOEXCEPT
Removes all entries from LibVMI's internal virtual to physical address cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
- [in] dtb The process address space to flush, or ~0ull for all.
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_v2pcache_nested_flush (vmi_instance_t vmi, addr_t pt, addr_t npt) NOEXCEPT
Removes all entries from LibVMI's internal virtual to physical address cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
- [in] dtb The process address space to flush, or ~0ull for all.
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_v2pcache_add (vmi_instance_t vmi, addr_t va, addr_t pt, addr_t pa) NOEXCEPT
Adds one entry to LibVMI's internal virtual to physical address cache.
Parameters
- [in] vmi LibVMI instance
- [in] va Virtual address
- [in] dtb Directory table base for va
- [in] pa Physical address
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_v2pcache_nested_add (vmi_instance_t vmi, addr_t va, addr_t pt, addr_t npt, addr_t pa) NOEXCEPT
Adds one entry to LibVMI's internal virtual to physical address cache.
Parameters
- [in] vmi LibVMI instance
- [in] va Virtual address
- [in] dtb Directory table base for va
- [in] pa Physical address
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_symcache_flush (vmi_instance_t vmi) NOEXCEPT
Removes all entries from LibVMI's internal kernel symbol to virtual address cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_symcache_add (vmi_instance_t vmi, addr_t base_addr, vmi_pid_t pid, char *sym, addr_t va) NOEXCEPT
Adds one entry to LibVMI's internal symbol to virtual address cache.
Parameters
- [in] vmi LibVMI instance
- [in] base_addr Base address
- [in] pid PID
- [in] sym Symbol
- [in] va Virtual address
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_rvacache_flush (vmi_instance_t vmi) NOEXCEPT
Removes all entries from LibVMI's internal RVA to symbol cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_rvacache_add (vmi_instance_t vmi, addr_t base_addr, vmi_pid_t pid, addr_t rva, char *sym) NOEXCEPT
Adds one entry to LibVMI's internal RVA to symbol cache.
Parameters
- [in] vmi LibVMI instance
- [in] base_addr Base address
- [in] pid PID
- [in] rva Relative virtual address
- [in] sym Symbol
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_pidcache_flush (vmi_instance_t vmi) NOEXCEPT
Removes all entries from LibVMI's internal pid to directory table base cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_pidcache_add (vmi_instance_t vmi, vmi_pid_t pid, addr_t dtb) NOEXCEPT
Adds one entry to LibVMI's internal pid to directory table base cache.
Parameters
- [in] vmi LibVMI instance
- [in] pid Process id
- [in] dtb Directory table base
Returns
- VMI_SUCCESS or VMI_FAILURE

void vmi_pagecache_flush (vmi_instance_t vmi) NOEXCEPT
Removes all entries from LibVMI's internal page cache. This is generally only useful if you believe that an entry in the cache is incorrect, or out of date.
Parameters
- [in] vmi LibVMI instance
Returns
- VMI_SUCCESS or VMI_FAILURE

const char* vmi_get_linux_sysmap (vmi_instance_t vmi) NOEXCEPT
Returns the path of the Linux system map file for the given vmi instance
DEPRECATED. Please use vmi_get_os_profile_path instead.
Parameters
- [in] vmi LibVMI instance
Returns
- String file path location of the Linux system map

const char* vmi_get_freebsd_sysmap (vmi_instance_t vmi) NOEXCEPT
Returns the path of the FreeBSD system map file for the given vmi instance
DEPRECATED. Please use vmi_get_os_profile_path instead.
Parameters
- [in] vmi LibVMI instance
Returns
- String file path location of the FreeBSD system map

const char* vmi_get_rekall_path (vmi_instance_t vmi) NOEXCEPT
Get full path of associated rekall profile
DEPRECATED. Please use vmi_get_os_profile_path instead.
Parameters
- [in] vmi LibVMI instance
Returns
- Full path of the rekall profile

const char* vmi_get_os_profile_path (vmi_instance_t vmi) NOEXCEPT
Get full path of associated OS profile.
This can be either the Rekall profile, Volatility ISF or System.map file.
Parameters
- [in] vmi LibVMI instance
Returns
- Full path of the OS profile

Macros

#define NOEXCEPT

#define VMI_INIT_DOMAINNAME (1u << 0)
initialize using domain name

#define VMI_INIT_DOMAINID (1u << 1)
initialize using domain id

#define VMI_INIT_EVENTS (1u << 2)
initialize events

#define VMI_INIT_DOMAINUUID (1u << 3)
initialize using domain uuid

#define VMI_INIT_DOMAINWATCH (1u << 4)
initialize using a domain watcher

#define VMI_PM_NONE 0
no page mode

#define VMI_PM_UNKNOWN 1
unknown paging mode

#define VMI_PM_LEGACY 2
x86 32-bit paging

#define VMI_PM_PAE 3
x86 PAE paging

#define VMI_PM_IA32E 4
x86 IA-32e paging

#define VMI_PM_AARCH32 5
ARM 32-bit paging

#define VMI_PM_AARCH64 6
ARM 64-bit paging

#define VMI_PM_EPT_4L 7
x86 4-level EPT

#define VMI_PM_EPT_5L 8
x86 5-level EPT

#define VMI_PM_INITFLAG_TRANSITION_PAGES (1u << 0)
Allow the use of transition-pages when checking PTE.present bit. This is a Windows-specific paging feature.

#define VMI_INVALID_DOMID ~0ULL
invalid domain id

#define EAX 0

#define EBX 1

#define ECX 2

#define EDX 3

#define EBP 4

#define ESI 5

#define EDI 6

#define ESP 7

#define EIP 8

#define EFLAGS 9

#define RAX

#define RBX EBX

#define RCX ECX

#define RDX EDX

#define RBP EBP

#define RSI ESI

#define RDI EDI

#define RSP ESP

#define RIP EIP

#define RFLAGS EFLAGS

#define R8 10

#define R9 11

#define R10 12

#define R11 13

#define R12 14

#define R13 15

#define R14 16

#define R15 17

#define CR0 18

#define CR2 19

#define CR3 20

#define CR4 21

#define XCR0 22

#define DR0 23

#define DR1 24

#define DR2 25

#define DR3 26

#define DR6 27

#define DR7 28

#define CS_SEL 29

#define DS_SEL 30

#define ES_SEL 31

#define FS_SEL 32

#define GS_SEL 33

#define SS_SEL 34

#define TR_SEL 35

#define LDTR_SEL 36

#define CS_LIMIT 37

#define DS_LIMIT 38

#define ES_LIMIT 39

#define FS_LIMIT 40

#define GS_LIMIT 41

#define SS_LIMIT 42

#define TR_LIMIT 43

#define LDTR_LIMIT 44

#define IDTR_LIMIT 45

#define GDTR_LIMIT 46

#define CS_BASE 47

#define DS_BASE 48

#define ES_BASE 49

#define FS_BASE 50

#define GS_BASE 51

#define SS_BASE 52

#define TR_BASE 53

#define LDTR_BASE 54

#define IDTR_BASE 55

#define GDTR_BASE 56

#define CS_ARBYTES 57

#define DS_ARBYTES 58

#define ES_ARBYTES 59

#define FS_ARBYTES 60

#define GS_ARBYTES 61

#define SS_ARBYTES 62

#define TR_ARBYTES 63

#define LDTR_ARBYTES 64

#define SYSENTER_CS 65

#define SYSENTER_ESP 66

#define SYSENTER_EIP 67

#define SHADOW_GS 68

#define TSC 69

#define MSR_FLAGS 70

#define MSR_LSTAR 71

#define MSR_CSTAR 72

#define MSR_SYSCALL_MASK 73

#define MSR_EFER 74

#define MSR_TSC_AUX 75

#define MSR_STAR 119

#define MSR_SHADOW_GS_BASE 120

#define MSR_MTRRfix64K_00000 121

#define MSR_MTRRfix16K_80000 122

#define MSR_MTRRfix16K_A0000 123

#define MSR_MTRRfix4K_C0000 124

#define MSR_MTRRfix4K_C8000 125

#define MSR_MTRRfix4K_D0000 126

#define MSR_MTRRfix4K_D8000 127

#define MSR_MTRRfix4K_E0000 128

#define MSR_MTRRfix4K_E8000 129

#define MSR_MTRRfix4K_F0000 130

#define MSR_MTRRfix4K_F8000 131

#define MSR_MTRRdefType 132

#define MSR_IA32_MC0_CTL 133

#define MSR_IA32_MC0_STATUS 134

#define MSR_IA32_MC0_ADDR 135

#define MSR_IA32_MC0_MISC 136

#define MSR_IA32_MC1_CTL 137

#define MSR_IA32_MC0_CTL2 138

#define MSR_AMD_PATCHLEVEL 139

#define MSR_AMD64_TSC_RATIO 140

#define MSR_IA32_P5_MC_ADDR 141

#define MSR_IA32_P5_MC_TYPE 142

#define MSR_IA32_TSC 143

#define MSR_IA32_PLATFORM_ID 144

#define MSR_IA32_EBL_CR_POWERON 145

#define MSR_IA32_EBC_FREQUENCY_ID 146

#define MSR_IA32_FEATURE_CONTROL 147

#define MSR_IA32_SYSENTER_CS 148

#define MSR_IA32_SYSENTER_ESP 149

#define MSR_IA32_SYSENTER_EIP 150

#define MSR_IA32_MISC_ENABLE 151

#define MSR_HYPERVISOR 152

#define MSR_ANY 153
Special generic case for specifying arbitrary MSRs

#define MSR_UNDEFINED /* deprecated */

#define MSR_ALL 76
Special generic case for handling MSRs, given their understandably generic treatment for events in Xen and elsewhere. Not relevant for vCPU get/set of register data.

#define SCTLR 77
ARM32 Registers

#define CPSR 78

#define TTBCR 79

#define TTBR0 80

#define TTBR1 81

#define R0 82

#define R1 83

#define R2 84

#define R3 85

#define R4 86

#define R5 87

#define R6 88

#define R7 89

#define SPSR_SVC 90

#define SPSR_FIQ 91

#define SPSR_IRQ 92

#define SPSR_UND 93

#define SPSR_ABT 94

#define LR_IRQ 95

#define SP_IRQ 96

#define LR_SVC 97

#define SP_SVC 98

#define LR_ABT 99

#define SP_ABT 100

#define LR_UND 101

#define SP_UND 102

#define R8_FIQ 103

#define R9_FIQ 104

#define R10_FIQ 105

#define R11_FIQ 106

#define R12_FIQ 107

#define SP_FIQ 108

#define LR_FIQ 109

#define PC 118

#define SP_USR R13
Compatibility naming

#define LR_USR R14

#define PC32 PC

#define SP_EL0 110
ARM64 register

#define SP_EL1 111

#define ELR_EL1 112

#define X0 R0
Many ARM64 registers are architecturally mapped over ARM32 registers

#define X1 R1

#define X2 R2

#define X3 R3

#define X4 R4

#define X5 R5

#define X6 R6

#define X7 R7

#define X8 R8

#define X9 R9

#define X10 R10

#define X11 R11

#define X12 R12

#define X13 R13

#define X14 R14

#define X15 R15

#define X16 LR_IRQ

#define X17 SP_IRQ

#define X18 LR_SVC

#define X19 SP_SVC

#define X20 LR_ABT

#define X21 SP_ABT

#define X22 LR_UND

#define X23 SP_UND

#define X24 R8_FIQ

#define X25 R9_FIQ

#define X26 R10_FIQ

#define X27 R11_FIQ

#define X28 R12_FIQ

#define X29 SP_FIQ

#define X30 LR_FIQ

#define PC64 PC

#define SPSR_EL1 SPSR_SVC

#define TCR_EL1 TTBCR

#define VMI_TM_NONE 0
No translation is required, address is physical address

#define VMI_TM_PROCESS_DTB 1
Translate addr via specified pagetable (aka. directory table base).

#define VMI_TM_PROCESS_PT 1
Translate addr via specified pagetable.

#define VMI_TM_PROCESS_PID 2
Translate addr by finding process first to use its DTB.

#define VMI_TM_KERNEL_SYMBOL 3
Find virtual address of kernel symbol and translate it via kernel DTB.

#define ACCESS_CONTEXT_VERSION 0x1u
Structure to use as input to accessor functions specifying how the access should be performed. Must specify ABI version.

#define ACCESS_CONTEXT (C, ...)

Value

C = {                      \
        .version = ,      \
        __VA_ARGS__                             \
    }

#define VMI_GET_BIT (reg, bit)
Macro to test bitfield values (up to 64-bits)
Value
```
(!!(reg & (1ULL<<bit)))
```

#define VMI_BIT_MASK (a, b)

Macro to compute bitfield masks (up to 64-bits)

Value

(((unsigned long long) -1 >> (63 - (b))) & ~((1ULL << (a)) - 1))

Typedefs

typedef enum vmi_mode vmi_mode_t

typedef enum vmi_config vmi_config_t

typedef enum status status_t

typedef enum vmi_init_error vmi_init_error_t

typedef enum os os_t

typedef enum win_ver win_ver_t
Windows version enumeration.

typedef uint32_t page_mode_t

typedef enum page_size page_size_t

typedef uint64_t reg_t

typedef struct x86_mtrr_regs mtrr_regs_t

typedef struct x86_regs x86_registers_t

typedef struct arm_registers arm_registers_t

typedef struct registers registers_t

typedef struct xsave_area xsave_area_t

typedef uint64_t addr_t
typedef for forward compatibility with 64-bit guests

typedef int32_t vmi_pid_t
type def for consistent pid_t usage

typedef struct page_info page_info_t
Struct for holding page lookup information

typedef enum arch vmi_arch_t
Supported architectures by LibVMI

typedef uint32_t translation_mechanism_t
Available translation mechanism for v2p conversion.

typedef struct _ustring unicode_string_t
Generic representation of Unicode string to be used within libvmi

typedef struct vmi_instance* vmi_instance_t
This struct holds all of the relavent information for an instance of LibVMI. Each time a new domain is accessed, a new instance must be created using the vmi_init function. When you are done with an instance, its resources can be freed using the vmi_destroy function.

Enums

enum vmi_mode
VMI_XEN libvmi is monitoring a Xen VM
VMI_KVM libvmi is monitoring a KVM VM
VMI_FILE libvmi is viewing a file on disk
VMI_BAREFLANK

enum vmi_config

VMI_CONFIG_GLOBAL_FILE_ENTRY	config in file provided
VMI_CONFIG_STRING	config string provided
VMI_CONFIG_GHASHTABLE	config GHashTable provided
VMI_CONFIG_JSON_PATH	config in json file at the location provided

enum status
VMI_SUCCESS return value indicating success
VMI_FAILURE return value indicating failure

enum vmi_init_error

VMI_INIT_ERROR_NONE	No error
VMI_INIT_ERROR_DRIVER_NOT_DETECTED	Failed to auto-detect hypervisor
VMI_INIT_ERROR_DRIVER	Failed to initialize hypervisor-driver
VMI_INIT_ERROR_VM_NOT_FOUND	Failed to find the specified VM
VMI_INIT_ERROR_PAGING	Failed to determine or initialize paging functions
VMI_INIT_ERROR_OS	Failed to determine or initialize OS functions
VMI_INIT_ERROR_EVENTS	Failed to initialize events
VMI_INIT_ERROR_NO_CONFIG	No configuration was found for OS initialization
VMI_INIT_ERROR_NO_CONFIG_ENTRY	Configuration contained no valid entry for VM

enum os
VMI_OS_UNKNOWN OS type is unknown
VMI_OS_LINUX OS type is Linux
VMI_OS_WINDOWS OS type is Windows
VMI_OS_FREEBSD OS type is FreeBSD

enum win_ver

VMI_OS_WINDOWS_NONE	Not Windows
VMI_OS_WINDOWS_UNKNOWN	Is Windows, not sure which
VMI_OS_WINDOWS_2000
VMI_OS_WINDOWS_XP
VMI_OS_WINDOWS_2003
VMI_OS_WINDOWS_VISTA
VMI_OS_WINDOWS_2008
VMI_OS_WINDOWS_7
VMI_OS_WINDOWS_8
VMI_OS_WINDOWS_10

enum page_size
VMI_PS_UNKNOWN page size unknown
VMI_PS_1KB 1KB
VMI_PS_4KB 4KB
VMI_PS_16KB 16KB
VMI_PS_64KB 64KB
VMI_PS_1MB 1MB
VMI_PS_2MB 2MB
VMI_PS_4MB 4MB
VMI_PS_16MB 16MB
VMI_PS_32MB 32MB
VMI_PS_512MB 512MB
VMI_PS_1GB 1GB

enum vmi_init_data_type_t
VMI_INIT_DATA_XEN_EVTCHN Xen file descriptor
VMI_INIT_DATA_MEMMAP
VMI_INIT_DATA_KVMI_SOCKET kvmi socket path

enum arch
VMI_ARCH_UNKNOWN Unknown architecture
VMI_ARCH_X86 x86 32-bit architecture
VMI_ARCH_X86_64 x86 64-bit architecture
VMI_ARCH_ARM32 ARM 32-bit architecture
VMI_ARCH_ARM64 ARM 64-bit architecture

Functions

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns