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_XENlibvmi is monitoring a Xen VM
    VMI_KVMlibvmi is monitoring a KVM VM
    VMI_FILElibvmi is viewing a file on disk
    VMI_BAREFLANK
  • enum vmi_config
  • VMI_CONFIG_GLOBAL_FILE_ENTRYconfig in file provided
    VMI_CONFIG_STRINGconfig string provided
    VMI_CONFIG_GHASHTABLEconfig GHashTable provided
    VMI_CONFIG_JSON_PATHconfig in json file at the location provided
  • enum status
  • VMI_SUCCESSreturn value indicating success
    VMI_FAILUREreturn value indicating failure
  • enum vmi_init_error
  • VMI_INIT_ERROR_NONENo error
    VMI_INIT_ERROR_DRIVER_NOT_DETECTEDFailed to auto-detect hypervisor
    VMI_INIT_ERROR_DRIVERFailed to initialize hypervisor-driver
    VMI_INIT_ERROR_VM_NOT_FOUNDFailed to find the specified VM
    VMI_INIT_ERROR_PAGINGFailed to determine or initialize paging functions
    VMI_INIT_ERROR_OSFailed to determine or initialize OS functions
    VMI_INIT_ERROR_EVENTSFailed to initialize events
    VMI_INIT_ERROR_NO_CONFIGNo configuration was found for OS initialization
    VMI_INIT_ERROR_NO_CONFIG_ENTRYConfiguration contained no valid entry for VM
  • enum os
  • VMI_OS_UNKNOWNOS type is unknown
    VMI_OS_LINUXOS type is Linux
    VMI_OS_WINDOWSOS type is Windows
    VMI_OS_FREEBSDOS type is FreeBSD
  • enum win_ver
  • VMI_OS_WINDOWS_NONENot Windows
    VMI_OS_WINDOWS_UNKNOWNIs 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_UNKNOWNpage size unknown
    VMI_PS_1KB1KB
    VMI_PS_4KB4KB
    VMI_PS_16KB16KB
    VMI_PS_64KB64KB
    VMI_PS_1MB1MB
    VMI_PS_2MB2MB
    VMI_PS_4MB4MB
    VMI_PS_16MB16MB
    VMI_PS_32MB32MB
    VMI_PS_512MB512MB
    VMI_PS_1GB1GB
  • enum vmi_init_data_type_t
  • VMI_INIT_DATA_XEN_EVTCHNXen file descriptor
    VMI_INIT_DATA_MEMMAP
    VMI_INIT_DATA_KVMI_SOCKETkvmi socket path
  • enum arch
  • VMI_ARCH_UNKNOWNUnknown architecture
    VMI_ARCH_X86x86 32-bit architecture
    VMI_ARCH_X86_64x86 64-bit architecture
    VMI_ARCH_ARM32ARM 32-bit architecture
    VMI_ARCH_ARM64ARM 64-bit architecture