public class

VirtualMemoryUtil

extends Object
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.code.asm.memory.VirtualMemoryUtil

Class Overview

Utility methods for virtual memory classes.

Methods of this class do not raise MemoryException. Instead, they return a boolean value to notify success or failure of the operation.

Summary

Public Constructors
VirtualMemoryUtil()
Public Methods
static long allocate(IVirtualMemory mem, long start, int size, int protection)
Search an available range and allocate at least the requested amount of bytes.
static int allocateFillGaps(IVirtualMemory mem, long address, int size, int protection)
Allocate a memory range, filling gaps in between already allocated pages if needed.
static int convertSegmentFlagsToVMFlags(int segmentFlags)
static IVirtualMemory createMemory(int spaceBits, int pageBits, Endianness standardEndianness)
Facade factory method returning a concrete, private implementation of an efficient page-based virtual memory.
static byte[] dump(IVirtualMemory vm, long addr, long addrEnd)
Dump a contiguous memory range of memory to a byte array.
static void dump(IVirtualMemory vm, long addr, long addrEnd, byte[] dst, int dstOffset)
Dump a contiguous memory range of memory to a buffer.
static void dumpToImageFiles(IVirtualMemory vm, File folder, String pfx, String sfx)
Dump a virtual memory to files in a folder.
static void dumpToImageFiles(IVirtualMemory vm, File folder)
Dump a virtual memory to files in a folder.
static long findAvailableRange(IVirtualMemory mem, long start, int size)
Search for an available memory range.
static long findByte(IVirtualMemory mem, long address, long lastAddress, int val)
Search for a single byte of memory.
static long findBytes(IVirtualMemory mem, boolean bypassProtection, long address, long lastAddress, byte[] pattern, byte[] patternMask)
Search for bytes in memory, with an optional binary mask.
static IVirtualMemoryShim getCopyOnWriteShim(IVirtualMemory mem)
Create a copy-on-write shim of the provided virtual memory, if possible.
static boolean isPageAllocated(IVirtualMemory mem, long address)
Verify if a page was allocated (regardless of protection rights on the page).
static int read(IVirtualMemory mem, long address)
Read a single byte and perform a zero-extension.
static Long readAsLongSafe(IVirtualMemory mem, long address, int bitsize)
Read an integer (byte, short, int or long) and converts it to Long.
static boolean readBEIntSafe(IVirtualMemory mem, long address, int[] out)
Read a big-endian 32-bit integer.
static boolean readBELongSafe(IVirtualMemory mem, long address, long[] out)
Read a big-endian 64-bit integer.
static boolean readBEShortSafe(IVirtualMemory mem, long address, short[] out)
Read a big-endian 16-bit integer.
static boolean readBooleans(IVirtualMemory mem, long address, boolean[] array, int offset, int count)
Read an array of booleans from memory.
static boolean readByteSafe(IVirtualMemory mem, long address, byte[] out)
Read a byte safely (this method does not raise MemoryException).
static boolean readBytes(IVirtualMemory mem, long address, byte[] array, int offset, int count)
Read an array of bytes from memory.
static int readBytesSafe(IVirtualMemory mem, long address, int size, byte[] dst, int dstOffset, boolean bypassProtection)
Safely read at most the requested amount of bytes.
static int readBytesSafe(IVirtualMemory mem, long address, int size, byte[] dst, int dstOffset, int protection)
Safely read at most the requested amount of bytes.
static boolean readChars(IVirtualMemory mem, long address, char[] array, int offset, int count)
Read an array of chars from memory.
static boolean readDoubles(IVirtualMemory mem, long address, double[] array, int offset, int count)
Read an array of doubles from memory.
static boolean readFloats(IVirtualMemory mem, long address, float[] array, int offset, int count)
Read an array of floats from memory.
static boolean readIntSafe(Endianness end, IVirtualMemory mem, long address, int[] out)
Read a little-endian 32-bit integer using a specific byte ordering.
static boolean readInts(IVirtualMemory mem, long address, int[] array, int offset, int count)
Read an array of ints from memory.
static boolean readLEIntSafe(IVirtualMemory mem, long address, int[] out)
Read a little-endian 32-bit integer.
static boolean readLELongSafe(IVirtualMemory mem, long address, long[] out)
Read a little-endian 64-bit integer.
static boolean readLEShortSafe(IVirtualMemory mem, long address, short[] out)
Read a little-endian 16-bit integer.
static boolean readLongSafe(Endianness end, IVirtualMemory mem, long address, long[] out)
Read a little-endian 64-bit integer using a specific byte ordering.
static boolean readLongs(IVirtualMemory mem, long address, long[] array, int offset, int count)
Read an array of longs from memory.
static String readNullTerminatedStringSafe(IVirtualMemory mem, long address, int maxSize)
Read from memory a series of ASCII characters, terminated by a null byte, and build the corresponding String.
static boolean readSafe(IVirtualMemory mem, long address, byte[] data)
Read an array of bytes from memory (this method does not raise MemoryException).
static boolean readShortSafe(Endianness end, IVirtualMemory mem, long address, short[] out)
Read a little-endian 16-bit integer using a specific byte ordering.
static boolean readShorts(IVirtualMemory mem, long address, short[] array, int offset, int count)
Read an array of shorts from memory.
static boolean writeBooleans(IVirtualMemory mem, long address, boolean[] array, int offset, int count)
Write an array of booleans to memory.
static boolean writeByteSafe(IVirtualMemory mem, long address, byte v)
Write an 8-bit integer.
static boolean writeBytes(IVirtualMemory mem, long address, byte[] array, int offset, int count)
Write an array of bytes to memory.
static boolean writeChars(IVirtualMemory mem, long address, char[] array, int offset, int count)
Write an array of chars to memory.
static boolean writeDoubles(IVirtualMemory mem, long address, double[] array, int offset, int count)
Write an array of doubles to memory.
static boolean writeFloats(IVirtualMemory mem, long address, float[] array, int offset, int count)
Write an array of floats to memory.
static boolean writeIntSafe(Endianness end, IVirtualMemory mem, long address, int v)
Write a little-endian 32-bit integer using a specific byte ordering.
static boolean writeInts(IVirtualMemory mem, long address, int[] array, int offset, int count)
Write an array of ints to memory.
static boolean writeLEIntSafe(IVirtualMemory mem, long address, int v)
Write a little-endian 32-bit integer.
static boolean writeLELongSafe(IVirtualMemory mem, long address, long v)
Write a little-endian 64-bit integer.
static boolean writeLEShortSafe(IVirtualMemory mem, long address, short v)
Write a little-endian 16-bit integer.
static boolean writeLongSafe(Endianness end, IVirtualMemory mem, long address, long v)
Write a little-endian 64-bit integer using a specific byte ordering.
static boolean writeLongs(IVirtualMemory mem, long address, long[] array, int offset, int count)
Write an array of longs to memory.
static boolean writeSafe(IVirtualMemory mem, long address, byte[] data)
Write an array of bytes to memory (this method does not raise MemoryException).
static boolean writeShortSafe(Endianness end, IVirtualMemory mem, long address, short v)
Write a little-endian 16-bit integer using a specific byte ordering.
static boolean writeShorts(IVirtualMemory mem, long address, short[] array, int offset, int count)
Write an array of shorts to memory.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public VirtualMemoryUtil ()

Public Methods

public static long allocate (IVirtualMemory mem, long start, int size, int protection)

Search an available range and allocate at least the requested amount of bytes. Do not confuse this method with allocate(long, int, int).

Parameters
start soft start address, considered a hint by this allocator routine; if you wish to allocate at a fixed, given address, use allocate(long, int, int)
size range size
Returns
  • the base address of the allocated memory range; -1 on error

public static int allocateFillGaps (IVirtualMemory mem, long address, int size, int protection)

Allocate a memory range, filling gaps in between already allocated pages if needed. (The given range [address, address + size) may have already allocated pages. Those pages will not be re-allocated.) When the method returns, the range [address, address + size) is guaranteed to be allocated.

Returns
  • the number of pages that were actually allocated

public static int convertSegmentFlagsToVMFlags (int segmentFlags)

public static IVirtualMemory createMemory (int spaceBits, int pageBits, Endianness standardEndianness)

Facade factory method returning a concrete, private implementation of an efficient page-based virtual memory.

public static byte[] dump (IVirtualMemory vm, long addr, long addrEnd)

Dump a contiguous memory range of memory to a byte array. Illegal pages (non-allocated) are dumped as empty pages (all bytes are zero).

Parameters
vm virtual memory
addr start address
addrEnd end address
Returns
  • the byte buffer holding the dumped data

public static void dump (IVirtualMemory vm, long addr, long addrEnd, byte[] dst, int dstOffset)

Dump a contiguous memory range of memory to a buffer. Illegal pages (non-allocated) are dumped as empty pages (all bytes are zero).

Parameters
vm virtual memory
addr start address
addrEnd end address
dst destination buffer
dstOffset offset in the destination

public static void dumpToImageFiles (IVirtualMemory vm, File folder, String pfx, String sfx)

Dump a virtual memory to files in a folder. The files will be named [PREFIX][MEMORY_RANGE_START][SUFFIX].

Parameters
vm virtual memory
folder destination folder; if it does not exist, a new folder will be created
pfx optional prefix for the filenames
sfx optional suffix for the filenames
Throws
IOException

public static void dumpToImageFiles (IVirtualMemory vm, File folder)

Dump a virtual memory to files in a folder. The files will be named as the start of the memory range (in hex) they contain.

Parameters
vm virtual memory
folder destination folder; if it does not exist, a new folder will be created
Throws
IOException

public static long findAvailableRange (IVirtualMemory mem, long start, int size)

Search for an available memory range.

Parameters
start soft start address, a hint
size range size
Returns
  • the range start address, -1 on error

public static long findByte (IVirtualMemory mem, long address, long lastAddress, int val)

Search for a single byte of memory. Similar as memchr or memrchr (if `lastAddress` is less than `address`).

public static long findBytes (IVirtualMemory mem, boolean bypassProtection, long address, long lastAddress, byte[] pattern, byte[] patternMask)

Search for bytes in memory, with an optional binary mask. The search can either be forward (default), in which case the resulting found address will be either -1 or ≥ the start address, or backward, in which case the resulting found address will be either -1 or ≤ the start address.

Parameters
mem memory to be searched
bypassProtection if true, memory page protection is disregarded, in which case all pages, including non-readable ones, will be searched
address start address for the search (this value is treated as unsigned)
lastAddress end address (the value is treated as unsigned); may be less than the start address, in which case a reverse search will be performed
pattern bytes to search for; the maximum allowed length is the memory's page size
patternMask optional binary mask for a wildcard search; if non-null, must be the same length as the pattern's
Returns
  • -1 if not found, else, the resulting address

public static IVirtualMemoryShim getCopyOnWriteShim (IVirtualMemory mem)

Create a copy-on-write shim of the provided virtual memory, if possible. The shim can be used to perform safe memory writes, that will not impact the underlying memory. Using a shim yields better performance than copying the entire source VM and working on the full copy.

Parameters
mem a VM
Returns
  • the shim VM
Throws
IllegalArgumentException if the provided VM object does not support the creation of a shim

public static boolean isPageAllocated (IVirtualMemory mem, long address)

Verify if a page was allocated (regardless of protection rights on the page).

public static int read (IVirtualMemory mem, long address)

Read a single byte and perform a zero-extension. This method does not raise MemoryException; on error, -1 is returned.

Returns
  • the byte, zero-extended over 32-bit; in other words, an integer in [0, 255]. On error, -1 is returned.

public static Long readAsLongSafe (IVirtualMemory mem, long address, int bitsize)

Read an integer (byte, short, int or long) and converts it to Long. Standard memory byte ordering is used for decoding.

Parameters
mem the virtual memory
address memory address of the data
bitsize any of 8, 16, 32, or 64
Returns
  • the long value or null on error

public static boolean readBEIntSafe (IVirtualMemory mem, long address, int[] out)

Read a big-endian 32-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readBELongSafe (IVirtualMemory mem, long address, long[] out)

Read a big-endian 64-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readBEShortSafe (IVirtualMemory mem, long address, short[] out)

Read a big-endian 16-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readBooleans (IVirtualMemory mem, long address, boolean[] array, int offset, int count)

Read an array of booleans from memory. Each entry occupies 1 byte of memory, the lower-significant bit of the byte indicates false(0) or true(1).

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean readByteSafe (IVirtualMemory mem, long address, byte[] out)

Read a byte safely (this method does not raise MemoryException).

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readBytes (IVirtualMemory mem, long address, byte[] array, int offset, int count)

Read an array of bytes from memory.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static int readBytesSafe (IVirtualMemory mem, long address, int size, byte[] dst, int dstOffset, boolean bypassProtection)

Safely read at most the requested amount of bytes.

Parameters
mem the memory
address target address
size requested read size
dst destination buffer
dstOffset position within the destination buffer
bypassProtection if true, all pages will be read, including non-resable pages; else, only readable pages will be read
Returns
  • the number of bytes read; may be less than requested. -1 if an unknown error occurs

public static int readBytesSafe (IVirtualMemory mem, long address, int size, byte[] dst, int dstOffset, int protection)

Safely read at most the requested amount of bytes.

Parameters
mem the memory
address target address
size requested read size
dst destination buffer
dstOffset position within the destination buffer
protection the requested protection level, must contain at least ACCESS_READ
Returns
  • the number of bytes read; may be less than requested. -1 if an unknown error occurs

public static boolean readChars (IVirtualMemory mem, long address, char[] array, int offset, int count)

Read an array of chars from memory. Each entry occupies 2 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean readDoubles (IVirtualMemory mem, long address, double[] array, int offset, int count)

Read an array of doubles from memory. Each entry occupies 8 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean readFloats (IVirtualMemory mem, long address, float[] array, int offset, int count)

Read an array of floats from memory. Each entry occupies 4 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean readIntSafe (Endianness end, IVirtualMemory mem, long address, int[] out)

Read a little-endian 32-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readInts (IVirtualMemory mem, long address, int[] array, int offset, int count)

Read an array of ints from memory. Each entry occupies 4 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean readLEIntSafe (IVirtualMemory mem, long address, int[] out)

Read a little-endian 32-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readLELongSafe (IVirtualMemory mem, long address, long[] out)

Read a little-endian 64-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readLEShortSafe (IVirtualMemory mem, long address, short[] out)

Read a little-endian 16-bit integer.

Parameters
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readLongSafe (Endianness end, IVirtualMemory mem, long address, long[] out)

Read a little-endian 64-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readLongs (IVirtualMemory mem, long address, long[] array, int offset, int count)

Read an array of longs from memory. Each entry occupies 8 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static String readNullTerminatedStringSafe (IVirtualMemory mem, long address, int maxSize)

Read from memory a series of ASCII characters, terminated by a null byte, and build the corresponding String. If no null-byte is found, the search stops at the provided maxSize.

This method does not raise MemoryException.

Parameters
mem a VM
address memory address
maxSize maximum string length in ascii characters
Returns
  • the string or null if a failure happened (e.g. string is too long, memory error occurred, etc.)

public static boolean readSafe (IVirtualMemory mem, long address, byte[] data)

Read an array of bytes from memory (this method does not raise MemoryException).

Returns
  • success indicator

public static boolean readShortSafe (Endianness end, IVirtualMemory mem, long address, short[] out)

Read a little-endian 16-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
out single-element array that will receive the result of the read operation
Returns
  • success indicator

public static boolean readShorts (IVirtualMemory mem, long address, short[] array, int offset, int count)

Read an array of shorts from memory. Each entry occupies 2 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeBooleans (IVirtualMemory mem, long address, boolean[] array, int offset, int count)

Write an array of booleans to memory. Each entry occupies 1 byte whose value will be set to 0(false) or 1(true).

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeByteSafe (IVirtualMemory mem, long address, byte v)

Write an 8-bit integer.

Parameters
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeBytes (IVirtualMemory mem, long address, byte[] array, int offset, int count)

Write an array of bytes to memory.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeChars (IVirtualMemory mem, long address, char[] array, int offset, int count)

Write an array of chars to memory. Each entry occupies 2 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeDoubles (IVirtualMemory mem, long address, double[] array, int offset, int count)

Write an array of doubles to memory. Each entry occupies 8 bytes of memory. The encoding used is IEEE754. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeFloats (IVirtualMemory mem, long address, float[] array, int offset, int count)

Write an array of floats to memory. Each entry occupies 4 bytes of memory. The encoding used is IEEE754. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeIntSafe (Endianness end, IVirtualMemory mem, long address, int v)

Write a little-endian 32-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeInts (IVirtualMemory mem, long address, int[] array, int offset, int count)

Write an array of ints to memory. Each entry occupies 4 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeLEIntSafe (IVirtualMemory mem, long address, int v)

Write a little-endian 32-bit integer.

Parameters
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeLELongSafe (IVirtualMemory mem, long address, long v)

Write a little-endian 64-bit integer.

Parameters
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeLEShortSafe (IVirtualMemory mem, long address, short v)

Write a little-endian 16-bit integer.

Parameters
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeLongSafe (Endianness end, IVirtualMemory mem, long address, long v)

Write a little-endian 64-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeLongs (IVirtualMemory mem, long address, long[] array, int offset, int count)

Write an array of longs to memory. Each entry occupies 8 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator

public static boolean writeSafe (IVirtualMemory mem, long address, byte[] data)

Write an array of bytes to memory (this method does not raise MemoryException).

Returns
  • success indicator

public static boolean writeShortSafe (Endianness end, IVirtualMemory mem, long address, short v)

Write a little-endian 16-bit integer using a specific byte ordering.

Parameters
end wanted endianness (little or big)
mem virtual memory
address memory address
v value to be written
Returns
  • success indicator

public static boolean writeShorts (IVirtualMemory mem, long address, short[] array, int offset, int count)

Write an array of shorts to memory. Each entry occupies 2 bytes of memory. Byte ordering is determined from the virtual memory endianness setting.

Parameters
mem virtual memory
address memory address
array array
offset start offset in the array
count count of elements to write
Returns
  • success indicator