Struct LeechCore 

pub struct LeechCore { /* private fields */ }

LeechCore API Base Struct.

The LeechCore struct is the base of the low-level physical memory aqusition API used by MemProcFS / Vmm. Normally it is not required to interact with this low-level library.

One may however wish to use specialized functionality such as sending and receiving raw PCIe TLPs (if the FPGA backend is in use), or to implement a device PCIe BAR.

The LeechCore struct acts as a wrapper around the native LeechCore API.

Check out the example project for more detailed API usage and additional examples!

Created By

• LeechCore::new()
• LeechCore::new_ex()
• Vmm::get_leechcore()

Examples

// Create a new LeechCore instance:
let lc = LeechCore::new('C:\\Temp\\MemProcFS\\leechcore.dll', 'fpga://algo=0', LeechCore::LC_CONFIG_PRINTF_ENABLED)?;

// Fetch an existing LeechCore instance from a Vmm instance:
let lc = vmm.get_leechcore()?;

Implementations

impl LeechCore

pub const LC_CONFIG_VERSION: u32 = 0xc0fd0002

LeechCore configuration struct version.

pub const LC_CONFIG_PRINTF_NONE: u32 = 0x00000000

No printf verbosity.

pub const LC_CONFIG_PRINTF_ENABLED: u32 = 0x00000001

Printf verbosity: standard.

pub const LC_CONFIG_PRINTF_V: u32 = 0x00000002

Printf verbosity: verbose.

pub const LC_CONFIG_PRINTF_VV: u32 = 0x00000004

Printf verbosity: extra verbose.

pub const LC_CONFIG_PRINTF_VVV: u32 = 0x00000008

Printf verbosity: extra extra verbose (TLP).

pub const LC_OPT_CORE_PRINTF_ENABLE: u64 = 0x4000000100000000

LeechCore printf enable [RW].

pub const LC_OPT_CORE_VERBOSE: u64 = 0x4000000200000000

LeechCore verbose level [RW].

pub const LC_OPT_CORE_VERBOSE_EXTRA: u64 = 0x4000000300000000

LeechCore extra verbose level [RW].

pub const LC_OPT_CORE_VERBOSE_EXTRA_TLP: u64 = 0x4000000400000000

LeechCore extra extra verbose level (TLP) [RW].

pub const LC_OPT_CORE_VERSION_MAJOR: u64 = 0x4000000500000000

LeechCore major version [R].

pub const LC_OPT_CORE_VERSION_MINOR: u64 = 0x4000000600000000

LeechCore minor version [R].

pub const LC_OPT_CORE_VERSION_REVISION: u64 = 0x4000000700000000

LeechCore revision version [R].

pub const LC_OPT_CORE_ADDR_MAX: u64 = 0x1000000800000000

LeechCore max physical address [R].

pub const LC_OPT_CORE_STATISTICS_CALL_COUNT: u64 = 0x4000000900000000

LeechCore statistics call count [lo-dword: LC_STATISTICS_ID_*] [R].

pub const LC_OPT_CORE_STATISTICS_CALL_TIME: u64 = 0x4000000a00000000

LeechCore statistics call time [lo-dword: LC_STATISTICS_ID_*] [R].

pub const LC_OPT_CORE_VOLATILE: u64 = 0x1000000b00000000

LeechCore is memory volatile [R].

pub const LC_OPT_CORE_READONLY: u64 = 0x1000000c00000000

LeechCore is memory readonly [R].

pub const LC_OPT_MEMORYINFO_VALID: u64 = 0x0200000100000000

LeechCore memory info: is valid [R]

pub const LC_OPT_MEMORYINFO_FLAG_32BIT: u64 = 0x0200000300000000

LeechCore memory info: is 32-bit OS [R].

pub const LC_OPT_MEMORYINFO_FLAG_PAE: u64 = 0x0200000400000000

LeechCore memory info: is 32-bit PAE OS [R].

pub const LC_OPT_MEMORYINFO_ARCH: u64 = 0x0200001200000000

LeechCore memory info: architecture [R].

pub const LC_OPT_MEMORYINFO_OS_VERSION_MINOR: u64 = 0x0200000500000000

LeechCore memory info: OS minor version [R].

pub const LC_OPT_MEMORYINFO_OS_VERSION_MAJOR: u64 = 0x0200000600000000

LeechCore memory info: OS major version [R].

pub const LC_OPT_MEMORYINFO_OS_DTB: u64 = 0x0200000700000000

LeechCore memory info: OS directory table base [R].

pub const LC_OPT_MEMORYINFO_OS_PFN: u64 = 0x0200000800000000

LeechCore memory info: OS PFN database [R].

pub const LC_OPT_MEMORYINFO_OS_PSLOADEDMODULELIST: u64 = 0x0200000900000000

LeechCore memory info: OS PsLoadedModuleList [R].

pub const LC_OPT_MEMORYINFO_OS_PSACTIVEPROCESSHEAD: u64 = 0x0200000a00000000

LeechCore memory info: OS PsActiveProcessHead [R].

pub const LC_OPT_MEMORYINFO_OS_MACHINE_IMAGE_TP: u64 = 0x0200000b00000000

LeechCore memory info: OS machine image type [R].

pub const LC_OPT_MEMORYINFO_OS_NUM_PROCESSORS: u64 = 0x0200000c00000000

LeechCore memory info: OS number of processors [R].

pub const LC_OPT_MEMORYINFO_OS_SYSTEMTIME: u64 = 0x0200000d00000000

LeechCore memory info: OS system time [R].

pub const LC_OPT_MEMORYINFO_OS_UPTIME: u64 = 0x0200000e00000000

LeechCore memory info: OS uptime [R].

pub const LC_OPT_MEMORYINFO_OS_KERNELBASE: u64 = 0x0200000f00000000

LeechCore memory info: OS kernel base [R].

pub const LC_OPT_MEMORYINFO_OS_KERNELHINT: u64 = 0x0200001000000000

LeechCore memory info: OS kernel hint [R].

pub const LC_OPT_MEMORYINFO_OS_KDDEBUGGERDATABLOCK: u64 = 0x0200001100000000

LeechCore memory info: OS KdDebuggerDataBlock [R].

pub const LC_OPT_FPGA_PROBE_MAXPAGES: u64 = 0x0300000100000000

LeechCore fpga: probe maximum number of pages [RW].

pub const LC_OPT_FPGA_MAX_SIZE_RX: u64 = 0x0300000300000000

LeechCore fpga: max rx size [RW].

pub const LC_OPT_FPGA_MAX_SIZE_TX: u64 = 0x0300000400000000

LeechCore fpga: max tx size [RW].

pub const LC_OPT_FPGA_DELAY_PROBE_READ: u64 = 0x0300000500000000

LeechCore fpga: time delay probe read in uS (algo: 2,3) [RW].

pub const LC_OPT_FPGA_DELAY_PROBE_WRITE: u64 = 0x0300000600000000

LeechCore fpga: time delay probe write in uS (algo: 2,3) [RW].

pub const LC_OPT_FPGA_DELAY_WRITE: u64 = 0x0300000700000000

LeechCore fpga: time delay write in uS (algo: 2,3) [RW].

pub const LC_OPT_FPGA_DELAY_READ: u64 = 0x0300000800000000

LeechCore fpga: time delay read in uS (algo: 2,3) [RW].

pub const LC_OPT_FPGA_RETRY_ON_ERROR: u64 = 0x0300000900000000

LeechCore fpga: retry on error [RW].

pub const LC_OPT_FPGA_DEVICE_ID: u64 = 0x0300008000000000

LeechCore fpga: PCIe device id - bus:dev:fn (ex: 04:00.0 == : u64 = 0x0400) [RW].

pub const LC_OPT_FPGA_FPGA_ID: u64 = 0x0300008100000000

LeechCore fpga: FPGA bistream id [R].

pub const LC_OPT_FPGA_VERSION_MAJOR: u64 = 0x0300008200000000

LeechCore fpga: version major [R].

pub const LC_OPT_FPGA_VERSION_MINOR: u64 = 0x0300008300000000

LeechCore fpga: version minor [R].

pub const LC_OPT_FPGA_ALGO_TINY: u64 = 0x0300008400000000

LeechCore fpga: 1/0 use tiny 128-byte/tlp read algorithm. [RW].

pub const LC_OPT_FPGA_ALGO_SYNCHRONOUS: u64 = 0x0300008500000000

LeechCore fpga: 1/0 use synchronous (old) read algorithm. [RW].

pub const LC_OPT_FPGA_CFGSPACE_XILINX: u64 = 0x0300008600000000

LeechCore fpga: [lo-dword: register address in bytes] [bytes: 0-3: data, 4-7: byte_enable(if wr/set); top bit = cfg_mgmt_wr_rw1c_as_rw] [RW].

pub const LC_OPT_FPGA_TLP_READ_CB_WITHINFO: u64 = 0x0300009000000000

LeechCore fpga: 1/0 call TLP read callback with additional string info in szInfo [RW].

pub const LC_OPT_FPGA_TLP_READ_CB_FILTERCPL: u64 = 0x0300009100000000

LeechCore fpga: 1/0 call TLP read callback with memory read completions from read calls filtered [RW].

pub const LC_CMD_FPGA_PCIECFGSPACE: u64 = 0x0000010300000000

LeechCore command: FPGA PCIe Config Space [R].

pub const LC_CMD_FPGA_CFGREGPCIE: u64 = 0x0000010400000000

LeechCore command: FPGA PCIe register value [lo-dword: register address] [RW].

pub const LC_CMD_FPGA_CFGREGCFG: u64 = 0x0000010500000000

LeechCore command: FPGA register cfg [RW].

pub const LC_CMD_FPGA_CFGREGDRP: u64 = 0x0000010600000000

LeechCore command: FPGA read/write DRP register space [lo-dword: register address] [RW].

pub const LC_CMD_FPGA_CFGREGCFG_MARKWR: u64 = 0x0000010700000000

LeechCore command: FPGA write with mask [lo-dword: register address] [bytes: 0-1: data, 2-3: mask] [W].

pub const LC_CMD_FPGA_CFGREGPCIE_MARKWR: u64 = 0x0000010800000000

LeechCore command: FPGA write with mask [lo-dword: register address] [bytes: 0-1: data, 2-3: mask] [W].

pub const LC_CMD_FPGA_PROBE: u64 = 0x0000010b00000000

LeechCore command: FPGA probe [RW].

pub const LC_CMD_FPGA_CFGSPACE_SHADOW_RD: u64 = 0x0000010c00000000

LeechCore command: FPGA read shadow config space[R].

pub const LC_CMD_FPGA_CFGSPACE_SHADOW_WR: u64 = 0x0000010d00000000

LeechCore command: FPGA [lo-dword: config space write base address] [W].

pub const LC_CMD_FPGA_TLP_WRITE_SINGLE: u64 = 0x0000011000000000

LeechCore command: FPGA write single tlp BYTE:s [W].

pub const LC_CMD_FPGA_TLP_WRITE_MULTIPLE: u64 = 0x0000011100000000

LeechCore command: FPGA write multiple LC_TLP:s [W].

pub const LC_CMD_FPGA_TLP_TOSTRING: u64 = 0x0000011200000000

LeechCore command: FPGA convert single TLP to LPSTR; *pcbDataOut includes NULL terminator [RW].

pub const LC_CMD_FPGA_TLP_CONTEXT: u64 = 0x2000011400000000

LeechCore command: FPGA set/unset TLP user-defined context to be passed to callback function. [not remote] [W].

pub const LC_CMD_FPGA_TLP_CONTEXT_RD: u64 = 0x2000011b00000000

LeechCore command: FPGA get TLP user-defined context to be passed to callback function. [not remote] [R].

pub const LC_CMD_FPGA_TLP_FUNCTION_CALLBACK: u64 = 0x2000011500000000

LeechCore command: FPGA set/unset TLP callback function [not remote] [W].

pub const LC_CMD_FPGA_TLP_FUNCTION_CALLBACK_RD: u64 = 0x2000011c00000000

LeechCore command: FPGA get TLP callback function [not remote] [R].

pub const LC_CMD_FPGA_BAR_CONTEXT: u64 = 0x2000012000000000

LeechCore command: FPGA set/unset BAR user-defined context to be passed to callback function. [not remote] [W].

pub const LC_CMD_FPGA_BAR_CONTEXT_RD: u64 = 0x2000012100000000

LeechCore command: FPGA get BAR user-defined context to be passed to callback function [not remote] [R].

pub const LC_CMD_FPGA_BAR_FUNCTION_CALLBACK: u64 = 0x2000012200000000

LeechCore command: FPGA set/unset BAR callback function [not remote] [W].

pub const LC_CMD_FPGA_BAR_FUNCTION_CALLBACK_RD: u64 = 0x2000012300000000

LeechCore command: FPGA get BAR callback function [not remote] [R].

pub const LC_CMD_FPGA_BAR_INFO: u64 = 0x0000012400000000

LeechCore command: FPGA BAR info. (pbDataOut == LC_BAR_INFO[6]) [R].

pub const LC_CMD_FILE_DUMPHEADER_GET: u64 = 0x0000020100000000

LeechCore command: Get the dump file header [R].

pub const LC_CMD_STATISTICS_GET: u64 = 0x4000010000000000

LeechCore command: Get statistics [R].

pub const LC_CMD_MEMMAP_GET: u64 = 0x4000020000000000

LeechCore command: Get memmap as string [R].

pub const LC_CMD_MEMMAP_SET: u64 = 0x4000030000000000

LeechCore command: Set memmap as string [W].

pub const LC_CMD_MEMMAP_GET_STRUCT: u64 = 0x4000040000000000

LeechCore command: Get memmap as C-struct [R].

pub const LC_CMD_MEMMAP_SET_STRUCT: u64 = 0x4000050000000000

LeechCore command: Set memmap as C-struct [W].

pub fn new( lc_lib_path: &str, device_config: &str, lc_config_printf_verbosity: u32, ) -> ResultEx<LeechCore>

LeechCore initialization function.

The LeechCore is the base of the low-level physical memory aqusition API used by MemProcFS / Vmm. Normally it is not required to interact with this low-level library.

One may however wish to use specialized functionality such as sending and receiving raw PCIe TLPs (if the FPGA backend is in use), or to implement a device PCIe BAR.

Arguments

• lc_lib_path - Full path to the native leechcore library - i.e. leechcore.dll, leechcore.dylib or leechcore.so.
• device_config - Leechcore device connection string, i.e. fpga://algo=0.
• lc_config_printf_verbosity - Leechcore printf verbosity level as a combination of LeechCore::LC_CONFIG_PRINTF_* values.

Information about supported memory acqusition methods may be found on the LeechCore wiki.

Examples

// Initialize a new LeechCore instance using the FPGA memory acqusition method.
let lc = LeechCore::new('C:\\Temp\\MemProcFS\\leechcore.dll', 'fpga://algo=0', LeechCore::LC_CONFIG_PRINTF_ENABLED)?;

pub fn new_ex( lc_lib_path: &str, device_config: &str, lc_config_printf_verbosity: u32, remote_config: &str, pa_max: u64, ) -> ResultEx<LeechCore>

LeechCore initialization function.

The LeechCore is the base of the low-level physical memory aqusition API used by MemProcFS / Vmm. Normally it is not required to interact with this low-level library.

One may however wish to use specialized functionality such as sending and receiving raw PCIe TLPs (if the FPGA backend is in use), or to implement a device PCIe BAR.

Arguments

• lc_lib_path - Full path to the native leechcore library - i.e. leechcore.dll, leechcore.dylib or leechcore.so.
• device_config - Leechcore device connection string, i.e. fpga://algo=0.
• lc_config_printf_verbosity - Leechcore printf verbosity level as a combination of LeechCore::LC_CONFIG_PRINTF_* values.
• remote_config - Leechcore remote connection string, i.e. blank or ``rpc://…` (Windows only).
• pa_max - Max physical address to use for memory acquisition.

Information about supported memory acqusition methods may be found on the LeechCore wiki.

Examples

// Initialize a new LeechCore instance using the FPGA memory acqusition method.
let lc = LeechCore::new('C:\\Temp\\MemProcFS\\leechcore.dll', 'fpga://algo=0', LeechCore::LC_CONFIG_PRINTF_ENABLED, '', 0x23fffffff)?;

pub fn get_option(&self, config_id: u64) -> ResultEx<u64>

Get a numeric configuration value.

Arguments

• config_id - As specified by a LeechCore::LC_OPT_* constant marked as Read [R] or Read/Write [RW]. (Optionally or’ed with other data on select options).

Examples

println!("max addr: {:#x}", lc.get_option(LeechCore::LC_OPT_CORE_ADDR_MAX).unwrap_or(0));

pub fn set_option(&self, config_id: u64, config_value: u64) -> ResultEx<()>

Set a numeric configuration value.

Arguments

• config_id - As specified by a LeechCore::LC_OPT_* constant marked as Write [W] or Read/Write [RW]. (Optionally or’ed with other data on select options).
• config_value - The config value to set.

Examples

// The below enables printf outputs from within the LeechCore library.
let _r = lc.set_option(LeechCore::LC_OPT_CORE_PRINTF_ENABLE, 1);

pub fn command( &self, command_id: u64, data: Option<&Vec<u8>>, ) -> ResultEx<Option<Vec<u8>>>

Execute a command using the LcCommand interface.

Arguments

• command_id - The command id to execute.
• data - Optional data to send with the command.

Examples

// Get the LeechCore memory map:
let memmap = lc.command(LeechCore::LC_CMD_MEMMAP_GET, None)?.to_string();

pub fn mem_read(&self, pa: u64, size: usize) -> ResultEx<Vec<u8>>

Read a contigious physical memory chunk.

The whole chunk must be read successfully for the method to succeed.

Arguments

• pa - Physical address to start reading from.
• size - Number of bytes to read.

Examples

// Read 0x100 bytes of data starting at address 0x1000.
// Example assumes: use pretty_hex::*;
let data_read = lc.mem_read(0x1000, 0x100)?;
println!("{:?}", data_read.hex_dump());

pub fn mem_read_as<T>(&self, pa: u64) -> ResultEx<T>

Read a contigious physical memory chunk with flags as a type/struct.

Arguments

• pa - Physical address to start reading from.

Examples

// Read the C-struct IMAGE_DOS_HEADER from memory.
#[repr(C)]
struct IMAGE_DOS_HEADER {
    e_magic : u16,
	...
    e_lfanew : u32,
}
if let Ok(doshdr) = lc.mem_read_as::<IMAGE_DOS_HEADER>(pa_module) {
    println!("e_magic:  {:x}", doshdr.e_magic);
    println!("e_lfanew: {:x}", doshdr.e_lfanew);
}

pub fn mem_write(&self, pa: u64, data: &Vec<u8>) -> ResultEx<()>

Write physical memory.

The write is a best effort. Even of the write should fail it’s not certain that an error will be returned. To be absolutely certain that a write has taken place follow up with a read.

Arguments

• pa - Physical address to start writing from.
• data - Byte data to write.

Examples

let data_to_write = [0x56u8, 0x4d, 0x4d, 0x52, 0x55, 0x53, 0x54].to_vec();
let _r = lc.mem_write(0x1000, &data_to_write);

pub fn mem_write_as<T>(&self, pa: u64, data: &T) -> ResultEx<()>

Write a type/struct to physical memory.

The write is a best effort. Even of the write should fail it’s not certain that an error will be returned. To be absolutely certain that a write has taken place follow up with a read.

Arguments

• pa - Physical address to start writing from.
• data - Data to write. In case of a struct repr(C) is recommended.

Examples

let data_to_write = [0x56, 0x4d, 0x4d, 0x52, 0x55, 0x53, 0x54];
let _r = lc.mem_write_as(0x1000, &data_to_write);

pub fn get_memmap(&self) -> ResultEx<String>

Retrieve the memory map currently in-use.

For more information about memory maps see the LeechCore wiki.

Examples

let memmap = lc.get_memmap()?;
println!("{}", memmap);

pub fn set_memmap(&self, str_memmap: &str) -> ResultEx<()>

Set/Update the memory map currently in-use.

For more information about memory maps see the LeechCore wiki.

Arguments

• str_memmap - The str containing the new memory map to use.

Examples

let _r = lc.set_memmap(memmap.as_str())?;

pub fn pcie_bar_info(&self) -> ResultEx<[LcBar; 6]>

PCIe only function: Get the BARs of the PCIe device.

Examples

let bars = lc.pcie_bar_info()?;

pub fn pcie_bar_callback<T>( &self, ctx: T, fn_bar_callback: fn(ctx: &LcBarContext<'_, T>, req: &LcBarRequest) -> ResultEx<()>, ) -> ResultEx<LcBarContextWrap<'_, T>>

PCIe only function: Start a PCIe BAR callback.

Arguments

• ctx - User defined context to be passed to the callback function.
• fn_bar_callback - The callback function to call when a BAR is accessed.

See LcBarContext for more information.

Only one PCIe BAR callback may be active at a time.

pub fn pcie_tlp_callback<T>( &self, ctx: T, fn_tlp_callback: fn(ctx: &LcTlpContext<'_, T>, tlp: &[u8], tlp_str: &str) -> ResultEx<()>, ) -> ResultEx<LcTlpContextWrap<'_, T>>

PCIe only function: Start a PCIe TLP callback.

Arguments

• ctx - User defined context to be passed to the callback function.
• fn_tlp_callback - The callback function to call when a TLP is received.

See LcTlpContext for more information.

Only one PCIe TLP callback may be active at a time.

pub fn pcie_tlp_write(&self, tlp: &[u8]) -> ResultEx<()>

PCIe only function: Write a PCIe TLP.

Arguments

• tlp - The TLP to write.

Trait Implementations

impl Clone for LeechCore

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LeechCore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for LeechCore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for LeechCore

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.