Macros

  • #define _GNU_SOURCE
  • #define ENABLE_ADDRESS_CACHE 1
  • #define ENABLE_PAGE_CACHE 1
  • #define MAX_PAGE_CACHE_SIZE 512
  • #define VMI_AUTO (1 << 0)
  • libvmi should detect what to monitor or view

  • #define VMI_XEN (1 << 1)
  • libvmi is monitoring a Xen VM

  • #define VMI_KVM (1 << 2)
  • libvmi is monitoring a KVM VM

  • #define VMI_FILE (1 << 3)
  • libvmi is viewing a file on disk

  • #define VMI_INIT_PARTIAL (1 << 16)
  • init enough to view physical addresses

  • #define VMI_INIT_COMPLETE (1 << 17)
  • full initialization

  • #define VMI_INIT_EVENTS (1 << 18)
  • init support for memory events

  • #define VMI_INIT_SHM_SNAPSHOT (1 << 19)
  • setup shm-snapshot in vmi_init() if the feature is activated

  • #define VMI_CONFIG_NONE (1 << 24)
  • no config provided

  • #define VMI_CONFIG_GLOBAL_FILE_ENTRY (1 << 25)
  • config in file provided

  • #define VMI_CONFIG_STRING (1 << 26)
  • config string provided

  • #define VMI_CONFIG_GHASHTABLE (1 << 27)
  • config GHashTable provided

  • #define VMI_INVALID_DOMID ~0
  • invalid domain id

  • #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))

  • #define MAX_SINGLESTEP_VCPUS 32
  • #define SET_VCPU_SINGLESTEP (ss_event, x)
  • Value

    ss_event.vcpus |= (1 << x)

  • #define UNSET_VCPU_SINGLESTEP (ss_event, x)
  • Value

    ss_event.vcpus &= ~(1 << x)

  • #define CHECK_VCPU_SINGLESTEP (ss_event, x)
  • Value

    (ss_event.vcpus) & (1 << x)

  • #define SETUP_SINGLESTEP_EVENT (_event, _vcpu_mask, _callback)
  • Value

    do { \
    (_event)->type = VMI_EVENT_SINGLESTEP; \
    (_event)->ss_event.vcpus = _vcpu_mask; \
    (_event)->callback = _callback; \
    } while(0)

  • #define SETUP_MEM_EVENT (_event, _addr, _granularity, _access, _callback)
  • Value

    do { \
    (_event)->type = VMI_EVENT_MEMORY; \
    (_event)->mem_event.physical_address = _addr; \
    (_event)->mem_event.granularity = _granularity; \
    (_event)->mem_event.in_access = _access; \
    (_event)->mem_event.npages = 1; \
    (_event)->callback = _callback; \
    } while(0)

  • #define SETUP_REG_EVENT (_event, _reg, _access, _equal, _callback)
  • Value

    do { \
    (_event)->type = VMI_EVENT_REGISTER; \
    (_event)->reg_event.reg = _reg; \
    (_event)->reg_event.in_access = _access; \
    (_event)->reg_event.equal = _equal; \
    (_event)->callback = _callback; \
    } while(0)

  • #define SETUP_INTERRUPT_EVENT (_event, _reinject, _callback)
  • Value

    do { \
    (_event)->type = VMI_EVENT_INTERRUPT; \
    (_event)->interrupt_event.reinject = _reinject; \
    (_event)->callback = _callback; \
    } while(0)

Typedefs

  • typedef uint32_t vmi_mode_t
  • typedef enum status status_t
  • typedef enum os os_t
  • typedef enum win_ver win_ver_t
  • typedef enum page_mode page_mode_t
  • typedef enum page_size page_size_t
  • typedef uint64_t reg_t
  • typedef enum registers registers_t
  • typedef uint64_t addr_t
  • typedef int32_t vmi_pid_t
  • typedef struct page_info page_info_t
  • typedef enum translation_mechanism translation_mechanism_t
  • typedef struct _ustring unicode_string_t
  • Generic representation of Unicode string to be used within libvmi

  • typedef void* vmi_config_t
  • 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.

  • typedef struct vmi_event vmi_event_t
  • typedef void(* event_callback_t) (vmi_instance_t vmi, vmi_event_t *event)

Enums

  • enum status
  • VMI_SUCCESSreturn value indicating success
    VMI_FAILUREreturn value indicating failure
  • enum os
  • VMI_OS_UNKNOWNOS type is unknown
    VMI_OS_LINUXOS type is Linux
    VMI_OS_WINDOWSOS type is Windows
  • 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
  • enum page_mode
  • VMI_PM_UNKNOWNpage mode unknown
    VMI_PM_LEGACYx86 32-bit paging
    VMI_PM_PAEx86 PAE paging
    VMI_PM_IA32Ex86 IA-32e paging
    VMI_PM_AARCH32ARM 32-bit paging
  • enum page_size
  • VMI_PS_UNKNOWNpage size unknown
    VMI_PS_1KB1Kb
    VMI_PS_4KB4Kb
    VMI_PS_64KB64Kb
    VMI_PS_1MB1Mb
    VMI_PS_2MB2Mb
    VMI_PS_4MB4Mb
    VMI_PS_16MB16Mb
    VMI_PS_1GB1GGb
  • enum registers
  • RAX
    RBX
    RCX
    RDX
    RBP
    RSI
    RDI
    RSP
    R8
    R9
    R10
    R11
    R12
    R13
    R14
    R15
    RIP
    RFLAGS
    CR0
    CR2
    CR3
    CR4
    DR0
    DR1
    DR2
    DR3
    DR6
    DR7
    CS_SEL
    DS_SEL
    ES_SEL
    FS_SEL
    GS_SEL
    SS_SEL
    TR_SEL
    LDTR_SEL
    CS_LIMIT
    DS_LIMIT
    ES_LIMIT
    FS_LIMIT
    GS_LIMIT
    SS_LIMIT
    TR_LIMIT
    LDTR_LIMIT
    IDTR_LIMIT
    GDTR_LIMIT
    CS_BASE
    DS_BASE
    ES_BASE
    FS_BASE
    GS_BASE
    SS_BASE
    TR_BASE
    LDTR_BASE
    IDTR_BASE
    GDTR_BASE
    CS_ARBYTES
    DS_ARBYTES
    ES_ARBYTES
    FS_ARBYTES
    GS_ARBYTES
    SS_ARBYTES
    TR_ARBYTES
    LDTR_ARBYTES
    SYSENTER_CS
    SYSENTER_ESP
    SYSENTER_EIP
    SHADOW_GS
    MSR_FLAGS
    MSR_LSTAR
    MSR_CSTAR
    MSR_SYSCALL_MASK
    MSR_EFER
    MSR_TSC_AUX
    MSR_ALL
    TSC
    SCTLR
    TTBCR
    TTBR0
    TTBR1
    R0_USR
    R1_USR
    R2_USR
    R3_USR
    R4_USR
    R5_USR
    R6_USR
    R7_USR
    R8_USR
    R9_USR
    R10_USR
    R11_USR
    R12_USR
    SP_USR
    LR_USR
    LR_IRQ
    SP_IRQ
    LR_SVC
    SP_SVC
    LR_ABT
    SP_ABT
    LR_UND
    SP_UND
    R8_FIQ
    R9_FIQ
    R10_FIQ
    R11_FIQ
    R12_FIQ
    SP_FIQ
    LR_FIQ
    PC32
    SPSR_SVC
    SPSR_FIQ
    SPSR_IRQ
    SPSR_UND
    SPSR_ABT
  • enum translation_mechanism
  • VMI_TM_INVALID
    VMI_TM_NONE
    VMI_TM_PROCESS_DTB
    VMI_TM_PROCESS_PID
    VMI_TM_KERNEL_SYMBOL
  • enum vmi_event_type_t
  • VMI_EVENT_INVALID
    VMI_EVENT_MEMORY
    VMI_EVENT_REGISTER
    VMI_EVENT_SINGLESTEP
    VMI_EVENT_INTERRUPT
    __VMI_EVENT_MAX
  • enum vmi_reg_access_t
  • VMI_REGACCESS_INVALID
    VMI_REGACCESS_N
    VMI_REGACCESS_R
    VMI_REGACCESS_W
    VMI_REGACCESS_RW
    __VMI_REGACCESS_MAX
  • enum vmi_mem_access_t
  • VMI_MEMACCESS_INVALID
    VMI_MEMACCESS_N
    VMI_MEMACCESS_R
    VMI_MEMACCESS_W
    VMI_MEMACCESS_X
    VMI_MEMACCESS_RW
    VMI_MEMACCESS_RX
    VMI_MEMACCESS_WX
    VMI_MEMACCESS_RWX
    VMI_MEMACCESS_W2X
    VMI_MEMACCESS_RWX2N
    __VMI_MEMACCESS_MAX
  • enum vmi_memevent_granularity_t
  • VMI_MEMEVENT_INVALID
    VMI_MEMEVENT_BYTE
    VMI_MEMEVENT_PAGE
    __VMI_MEMEVENT_MAX
  • enum interrupts_t
  • INT_INVALID
    INT3

Functions

  • status_t vmi_init (vmi_instance_t *vmi, uint32_t flags, const char *name)
  • Initializes access to a specific VM or file given a name. 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.

    Parameters
    • [out] vmi Struct that holds instance information
    • [in] flags VMI_AUTO, VMI_XEN, VMI_KVM, or VMI_FILE plus VMI_INIT_PARTIAL or VMI_INIT_COMPLETE
    • [in] name Unique name specifying the VM or file to view
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_init_custom (vmi_instance_t *vmi, uint32_t flags, vmi_config_t config)
  • Initializes access to a specific VM with a custom configuration source. All calls to vmi_init_custom 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.

    Parameters
    • [out] vmi Struct that holds instance information
    • [in] flags VMI_AUTO, VMI_XEN, VMI_KVM, or VMI_FILE plus VMI_INIT_PARTIAL or VMI_INIT_COMPLETE plus VMI_CONFIG_FILE/STRING/GHASHTABLE
    • [in] config Pointer to the specified configuration structure
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_init_complete (vmi_instance_t *vmi, const char *config)
  • Completes initialization. Call this after calling vmi_init with VMI_INIT_PARTIAL. Calling this at any other time results in undefined behavior. The partial init provides physical memory access only. So the purpose of this function is to allow for a staged init of LibVMI. You can gain physical memory access, run some heuristics to obtain the necessary offsets, and then complete the init.

    Parameters
    • [inout] vmi Struct that holds the instance information and was passed to vmi_init with a VMI_INIT_PARTIAL flag
    • [in] config Pointer to a string containing the config entries for this domain. Entries should be specified as in the config file (e.g., '{ostype = "Windows"; win_tasks = 0x88; win_pdbase = 0x18; ...}'). If this is NULL, then the config is pulled from /etc/libvmi.conf.
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_init_complete_custom (vmi_instance_t *vmi, uint32_t flags, vmi_config_t config)
  • Completes initialization. Call this after calling vmi_init or vmi_init_custom with VMI_INIT_PARTIAL. Calling this at any other time results in undefined behavior. The partial init provides physical memory access only. So the purpose of this function is to allow for a staged init of LibVMI. You can gain physical memory access, run some heuristics to obtain the necessary offsets, and then complete the init.

    Parameters
    • [inout] vmi Struct that holds the instance information and was passed to vmi_init with a VMI_INIT_PARTIAL flag
    • [in] flags VMI_CONFIG_FILE/STRING/GHASHTABLE
    • [in] config Pointer to a structure containing the config entries for this domain.
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • page_mode_t vmi_init_paging (vmi_instance_t vmi, uint8_t force_reinit)
  • Initialize or reinitialize the paging specific functionality of LibVMI. This function is most useful when dynamically monitoring the booting of an OS in VMI_INIT_PARTIAL mode.

    Parameters
    • [in] vmi LibVMI instance
    • [in] force_reinit Force the reinitialization of the paging mode even if one was already setup previously.
    Returns
    • The current page mode of the architecture or VMI_PM_UNKNOWN.
  • status_t vmi_destroy (vmi_instance_t vmi)
  • Destroys an instance by freeing memory and closing any open handles.

    Parameters
    • [in] vmi Instance to destroy
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • addr_t vmi_translate_kv2p (vmi_instance_t vmi, addr_t vaddr)
  • 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
    Returns
    • Physical address, or zero on error
  • addr_t vmi_translate_uv2p (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid)
  • 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
    Returns
    • Physical address, or zero on error
  • addr_t vmi_translate_ksym2v (vmi_instance_t vmi, const char *symbol)
  • Performs the translation from a kernel symbol to a virtual address.

    Parameters
    • [in] vmi LibVMI instance
    • [in] symbol Desired kernel symbol to translate
    Returns
    • Virtual address, or zero on error
  • addr_t vmi_translate_sym2v (vmi_instance_t vmi, addr_t base_vaddr, vmi_pid_t pid, char *symbol)
  • 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] base_vaddr Base virtual address (beginning of PE header in Windows)
    • [in] pid PID
    • [in] symbol Desired symbol to translate
    Returns
    • Virtual address, or zero on error
  • const char* vmi_translate_v2sym (vmi_instance_t vmi, addr_t base_vaddr, vmi_pid_t pid, addr_t rva)
  • Performs the translation from an RVA to a symbol On Windows this function walks the PE export table. Linux is unimplemented at this time.

    Parameters
    • [in] vmi LibVMI instance
    • [in] base_vaddr Base virtual address (beginning of PE header in Windows)
    • [in] pid PID
    • [in] rva RVA to translate
    Returns
    • Symbol, or NULL on error
  • addr_t vmi_pid_to_dtb (vmi_instance_t vmi, vmi_pid_t pid)
  • 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.

    Parameters
    • [in] vmi LibVMI instance
    • [in] pid Desired process id to lookup
    Returns
    • OrderedDict([(u'emphasis', u'pid'), ('#text', u'The directory table base virtual address for')])
  • vmi_pid_t vmi_dtb_to_pid (vmi_instance_t vmi, addr_t dtb)
  • 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.

    Parameters
    • [in] vmi LibVMI instance
    • [in] dtb Desired dtb to lookup
    Returns
    • The PID corresponding to the dtb
  • addr_t vmi_pagetable_lookup (vmi_instance_t vmi, addr_t dtb, addr_t vaddr)
  • Translates a virtual address to a physical address.

    Parameters
    • [in] vmi LibVMI instance
    • [in] dtb address of the relevant page directory base
    • [in] vaddr virtual address to translate via dtb
    Returns
    • Physical address, or zero on error
  • status_t vmi_pagetable_lookup_extended (vmi_instance_t vmi, addr_t dtb, addr_t vaddr, page_info_t *info)
  • 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] dtb address of the relevant page directory base
    • [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
  • size_t vmi_read (vmi_instance_t vmi, access_context_t *ctx, void *buf, size_t count)
  • Reads count bytes from memory and stores the output in buf.

    Parameters
    • [in] vmi LibVMI instance
    • [in] ctx Access context
    • [out] buf The data read from memory
    • [in] count The number of bytes to read
    Returns
    • The number of bytes read.
  • status_t vmi_read_8 (vmi_instance_t vmi, access_context_t *ctx, uint8_t *value)
  • 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, access_context_t *ctx, uint16_t *value)
  • 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, access_context_t *ctx, uint32_t *value)
  • 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, access_context_t *ctx, uint64_t *value)
  • 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, access_context_t *ctx, addr_t *value)
  • 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, access_context_t *ctx)
  • 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
  • size_t vmi_read_ksym (vmi_instance_t vmi, char *sym, void *buf, size_t count)
  • Reads count bytes from memory located at the kernel symbol sym and stores the output in buf.

    Parameters
    • [in] vmi LibVMI instance
    • [in] sym Kernel symbol to read from
    • [out] buf The data read from memory
    • [in] count The number of bytes to read
    Returns
    • The number of bytes read.
  • size_t vmi_read_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, void *buf, size_t count)
  • 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)
    • [out] buf The data read from memory
    • [in] count The number of bytes to read
    Returns
    • The number of bytes read.
  • size_t vmi_read_pa (vmi_instance_t vmi, addr_t paddr, void *buf, size_t count)
  • Reads count bytes from memory located at the physical address paddr and stores the output in buf.

    Parameters
    • [in] vmi LibVMI instance
    • [in] paddr Physical address to read from
    • [out] buf The data read from memory
    • [in] count The number of bytes to read
    Returns
    • The number of bytes read.
  • status_t vmi_read_8_ksym (vmi_instance_t vmi, char *sym, uint8_t *value)
  • 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, char *sym, uint16_t *value)
  • 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, char *sym, uint32_t *value)
  • 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, char *sym, uint64_t *value)
  • 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, char *sym, addr_t *value)
  • 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, char *sym)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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"); (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)
  • Convenience function to free a unicode_string_t struct.

    Parameters
    • [in] p_us Pointer to a unicode_string_t struct
  • status_t vmi_read_8_pa (vmi_instance_t vmi, addr_t paddr, uint8_t *value)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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
  • size_t vmi_write (vmi_instance_t vmi, access_context_t *ctx, void *buf, size_t count)
  • Writes count bytes to memory

    Parameters
    • [in] vmi LibVMI instance
    • [in] ctx Access context
    • [in] buf The data written to memory
    • [in] count The number of bytes to write
    Returns
    • The number of bytes written.
  • size_t vmi_write_ksym (vmi_instance_t vmi, char *sym, void *buf, size_t count)
  • Writes count bytes to memory located at the kernel symbol sym from buf.

    Parameters
    • [in] vmi LibVMI instance
    • [in] sym Kernel symbol to write to
    • [in] buf The data written to memory
    • [in] count The number of bytes to write
    Returns
    • The number of bytes written.
  • size_t vmi_write_va (vmi_instance_t vmi, addr_t vaddr, vmi_pid_t pid, void *buf, size_t count)
  • 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] buf The data written to memory
    • [in] count The number of bytes to write
    Returns
    • The number of bytes written.
  • size_t vmi_write_pa (vmi_instance_t vmi, addr_t paddr, void *buf, size_t count)
  • 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
    Returns
    • The number of bytes written.
  • status_t vmi_write_8 (vmi_instance_t vmi, access_context_t *ctx, uint8_t *value)
  • 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, access_context_t *ctx, uint16_t *value)
  • 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, access_context_t *ctx, uint32_t *value)
  • 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, access_context_t *ctx, uint64_t *value)
  • 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, access_context_t *ctx, addr_t *value)
  • 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, char *sym, uint8_t *value)
  • 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, char *sym, uint16_t *value)
  • 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, char *sym, uint32_t *value)
  • 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, char *sym, uint64_t *value)
  • 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, char *sym, addr_t *value)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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 (unsigned char *data, unsigned long length)
  • 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, char *sym, size_t length)
  • 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)
  • 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)
  • 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)
  • 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
  • unsigned long vmi_get_vmid (vmi_instance_t vmi)
  • Gets the id of the VM that LibVMI is accessing.

    Parameters
    • [in] vmi LibVMI instance
    Returns
    • VM id, or zero on error
  • uint32_t vmi_get_access_mode (vmi_instance_t vmi)
  • 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).

    Parameters
    • [in] vmi LibVMI instance
    Returns
    • Access mode
  • page_mode_t vmi_get_page_mode (vmi_instance_t vmi)
  • 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).

    If paging mode is altered after vmi_init, the information preserved in vmi_instance_t will have become stale and require re-initialization.

    Parameters
    • [in] vmi LibVMI instance
    Returns
    • Page mode
  • uint8_t vmi_get_address_width (vmi_instance_t vmi)
  • 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)
  • 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
  • win_ver_t vmi_get_winver (vmi_instance_t vmi)
  • 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
  • const char* vmi_get_winver_str (vmi_instance_t vmi)
  • 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)
  • 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
  • uint64_t vmi_get_offset (vmi_instance_t vmi, char *offset_name)
  • 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
    Returns
    • The offset value
  • uint64_t vmi_get_memsize (vmi_instance_t vmi)
  • Gets the memory size of the guest or file that LibVMI is currently accessing. This is effectively the max physical address that you can access in the system.

    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
  • unsigned int vmi_get_num_vcpus (vmi_instance_t vmi)
  • 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_get_vcpureg (vmi_instance_t vmi, reg_t *value, registers_t reg, unsigned long vcpu)
  • 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_set_vcpureg (vmi_instance_t vmi, reg_t value, registers_t reg, unsigned long vcpu)
  • 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. Operating upon an unpaused VM with this function is likely to have unexpected results.

    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_pause_vm (vmi_instance_t vmi)
  • 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)
  • 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)
  • 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
  • void vmi_v2pcache_add (vmi_instance_t vmi, addr_t va, addr_t dtb, addr_t pa)
  • Adds one entry to LibVMI's internal virtual to physical address cache.

    Parameters
    • [in] vmi LibVMI instance
    • [in] va Virtual address
    • [in] dtb OrderedDict([(u'emphasis', u'va'), ('#text', u'Directory table base for')])
    • [in] pa Physical address
  • void vmi_symcache_flush (vmi_instance_t vmi)
  • 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
  • void vmi_symcache_add (vmi_instance_t vmi, addr_t base_addr, vmi_pid_t pid, char *sym, addr_t va)
  • 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
  • void vmi_rvacache_flush (vmi_instance_t vmi)
  • 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
  • void vmi_rvacache_add (vmi_instance_t vmi, addr_t base_addr, vmi_pid_t pid, addr_t rva, char *sym)
  • 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
  • void vmi_pidcache_flush (vmi_instance_t vmi)
  • 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
  • void vmi_pidcache_add (vmi_instance_t vmi, vmi_pid_t pid, addr_t dtb)
  • 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
  • status_t vmi_register_event (vmi_instance_t vmi, vmi_event_t *event)
  • Callback receives one event as input. Callback is invoked while within the event listener loop, so actions taken by the callback must take into account that other events may have been delivered and not yet processed. This is especially important when events have been configured in an asyncronous manner (i.e., events delivered are not necessarily in lockstep with the VM state).

    Memory management of the vmi_event_t being registered remains the responsibility of the caller.

    Parameters
    • [in] vmi LibVMI instance
    • [in] event Definition of event to monitor
    • [in] callback Function to call when the event occurs
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_clear_event (vmi_instance_t vmi, vmi_event_t *event)
  • Clear the event specified by the vmi_event_t object.

    For memory events, this operation resets page permissions so that execution relative to related page or pages can continue without further interaction. For register and single-step events, this action disables monitoring of the given event type via the hypervisor driver. In all cases, the event is removed from hashtables internal to LibVMI, but the memory related to the vmi_event_t is not freed. Memory management remains the responsibility of the caller.

    Parameters
    • [in] vmi LibVMI instance
    • [in] event Definition of event to clear
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • vmi_event_t* vmi_get_reg_event (vmi_instance_t vmi, registers_t reg)
  • Return the pointer to the vmi_event_t if one is set on the given register.

    Parameters
    • [in] vmi LibVMI instance
    • [in] reg Register to check
    Returns
    • vmi_event_t* or NULL if none found
  • vmi_event_t* vmi_get_mem_event (vmi_instance_t vmi, addr_t physical_address, vmi_memevent_granularity_t granularity)
  • Return the pointer to the vmi_event_t if one is set on the given page.

    Parameters
    • [in] vmi LibVMI instance
    • [in] physical_address Physical address of byte/page to check
    • [in] granularity VMI_MEMEVENT_BYTE or VMI_MEMEVENT_PAGE
    Returns
    • vmi_event_t* or NULL if none found
  • status_t vmi_step_event (vmi_instance_t vmi, vmi_event_t *event, uint32_t vcpu_id, uint64_t steps, event_callback_t cb)
  • Setup single-stepping to register the given event after the specified number of steps.

    Parameters
    • [in] vmi LibVMI instance
    • [in] event The event to register
    • [in] vcpu_id The vCPU ID to step the event on.
    • [in] steps The number of steps to take before registering the event
    • [in] cb Optional: A callback function to call after the specified number of steps. If no callback is provided, the event will be re-registered automatically. If a callback is provided, event re-registration is not automatic, but can be done in the callback.
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_events_listen (vmi_instance_t vmi, uint32_t timeout)
  • Listen for events until one occurs or a timeout. If the timeout is given as 0, it will process leftover events in the ring-buffer (if there are any).

    Parameters
    • [in] vmi LibVMI instance
    • [in] timeout Number of ms.
    Returns
    • VMI_FAILURE or VMI_SUCCESS (timeout w/ 0 events returns VMI_SUCCESS)
  • status_t vmi_event_listener_required (vmi_instance_t vmi, int required)
  • Set wether to pause the domain if the event listener is no longer present.

    Parameters
    • [in] vmi LibVMI instance
    • [in] required Set to 0 if not required, 1 if required.
    Returns
    • VMI_FAILURE or VMI_SUCCESS
  • int vmi_are_events_pending (vmi_instance_t vmi)
  • Check if there are events pending to be processed.

    Parameters
    • [in] vmi LibVMI instance
    Returns
    • The number of pending events, or 0 if there are non, -1 on error.
  • vmi_event_t* vmi_get_singlestep_event (vmi_instance_t vmi, uint32_t vcpu)
  • Return the pointer to the vmi_event_t if one is set on the given vcpu.

    Parameters
    • [in] vmi LibVMI instance
    • [in] vcpu the vcpu to check
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_stop_single_step_vcpu (vmi_instance_t vmi, vmi_event_t *event, uint32_t vcpu)
  • Disables the MTF single step flag from a vcpu as well as the libvmi event object's bitfield position. This does not disable single step for the whole domain.

    Parameters
    • [in] vmi LibVMI instance
    • [in] event the event to disable the vcpu on
    • [in] vcpu the vcpu to stop single stepping on
    Returns
    • VMI_SUCCESS or VMI_FAILURE
  • status_t vmi_shutdown_single_step (vmi_instance_t)
  • Cleans up any domain wide single step settings. This should be called when the caller is completely finished with single step, as it implicitly disables single-step on all VM VCPUs.

    Parameters
    • [in] vmi LibVMI instance
    Returns
    • VMI_SUCCESS or VMI_FAILURE