public interface

IVirtualMemory

com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory
Known Indirect Subclasses

Class Overview

Definition of a virtual memory space addressing bytes. Up to 2^64 bytes may addressed. The page size is variable.

Addresses are represented as long; they are always considered unsigned. Sizes are represented as int; they are also always considered unsigned.

Implementation of the eventing system (for alloc, free, protection change, and write notifications) is optional. If not implemented, the methods should throw UnsupportedOperationException. If implemented, remember that the observer objects should not be persisted with the memory object.

Some features exposed by this interface are optional. If the implementation does not provide them, it should throw UnsupportedOperationException.

Implementors may decide to provide support for concurrency.

Summary

Constants
int ACCESS_EXECUTE
int ACCESS_NONE No access.
int ACCESS_READ
int ACCESS_RW Read/Write access.
int ACCESS_RWX Read/Write/Execute access.
int ACCESS_RX Read/Execute access.
int ACCESS_WRITE
Public Methods
abstract void addAllocListener(IMemoryAllocListener listener)
abstract void addFreeListener(IMemoryFreeListener listener)
abstract void addPreWriteListener(IMemoryWriteListener listener)
Note: The callback is invoked before the write operation takes place.
abstract void addPropertyListener(IMemoryPropertyListener listener)
abstract void addProtectionListener(IMemoryProtectionListener listener)
abstract void addWriteListener(IMemoryWriteListener listener)
abstract void allocate(long address, int size, int protection)
Allocate the entire memory range or nothing (fail).
abstract void allocatePage(long address, int protection)
Allocate a single page.
abstract int check(long address, int size, int protection)
Check if a memory range has at least the given set of protection flags.
abstract IVirtualMemory duplicate()
Make a deep copy of this virtual memory.
abstract void free(long address, int size)
Free the entire memory range or fail.
abstract void freePage(long address)
Free a single page.
abstract Collection<Long> getAllocatedPageBases()
Retrieve the base addresses of the pages that are allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).
abstract int getAllocatedPageCount()
Get the number of pages allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).
abstract int getAproximateFootprint()
Determine the approximate memory footprint of this object, in kilobytes.
abstract int getPageBits()
Get the width of a memory page in bits.
abstract int getPageProtection(long address)
Get the protection flags for a page.
abstract int getPageSize()
Get the size of a page in bytes.
abstract int getSpaceBits()
Get the width of this memory space in bits.
abstract Endianness getStandardEndianess()
Get the standard endianness.
abstract boolean isAllocatedPage(long address)
Determine whether the provided address belongs to an allocated page.
abstract boolean isValidAddress(long address)
Determine if an address is valid for this memory space.
abstract int read(long address, int size, byte[] dst, int dstOffset, boolean bypassProtection)
Read a range of bytes.
abstract int read(long address, int size, byte[] dst, int dstOffset)
Read a range of bytes.
abstract int readBEInt(long address)
Read a big-endian 32-bit integer.
abstract long readBELong(long address)
Read a big-endian 64-bit integer.
abstract short readBEShort(long address)
Read a big-endian 16-bit integer.
abstract byte readByte(long address)
Convenience method.
abstract int readInt(long address, Endianness end)
Read a 32-bit integer.
abstract int readInt(long address)
Read a 32-bit integer using the standard endianness.
abstract int readLEInt(long address)
Read a little-endian 32-bit integer.
abstract long readLELong(long address)
Read a little-endian 64-bit integer.
abstract short readLEShort(long address)
Read a little-endian 16-bit integer.
abstract long readLong(long address, Endianness end)
Read a 64-bit integer.
abstract long readLong(long address)
Read a 64-bit integer using the standard endianness.
abstract long readPointer(long address)
@return
abstract short readShort(long address, Endianness end)
Read a 16-bit integer.
abstract short readShort(long address)
Read a 16-bit integer using the standard endianness.
abstract void removeAllocListener(IMemoryAllocListener listener)
abstract void removeFreeListener(IMemoryFreeListener listener)
abstract void removePreWriteListener(IMemoryWriteListener listener)
abstract void removePropertyListener(IMemoryPropertyListener listener)
abstract void removeProtectionListener(IMemoryProtectionListener listener)
abstract void removeWriteListener(IMemoryWriteListener listener)
abstract long roundToPage(long address)
Round an address to the page this address currently resides in, that is the highest page so that boundary ≤ address.
abstract long roundToSize(long address)
Round an address to the lowest page boundary so that address ≤ boundary.
abstract void setLazyMemoryProvider(ILazyMemoryProvider lazyMemoryProvider, boolean skipFailedAllocations)
Set a lazy memory provider.
abstract void setPageProtection(long address, int protection)
Set the protection flags for a page.
abstract void setStandardEndianness(Endianness endianness)
Set the standard endianness.
abstract int write(long address, int size, byte[] src, int srcOffset)
Write a range of bytes.
abstract int write(long address, int size, byte[] src, int srcOffset, boolean bypassProtection)
Write a range of bytes.
abstract void writeBEInt(long address, int v)
Write a big-endian 32-bit integer.
abstract void writeBELong(long address, long v)
Write a big-endian 64-bit integer.
abstract void writeBEShort(long address, short v)
Write a big-endian 16-bit integer.
abstract void writeByte(long address, byte v)
Write a byte.
abstract void writeInt(long address, int v, Endianness end)
Write a 32-bit integer.
abstract void writeInt(long address, int v)
Write a 32-bit integer using the standard endianness.
abstract void writeLEInt(long address, int v)
Write a little-endian 32-bit integer.
abstract void writeLELong(long address, long v)
Write a little-endian 64-bit integer.
abstract void writeLEShort(long address, short v)
Write a little-endian 16-bit integer.
abstract void writeLong(long address, long v)
Write a 64-bit integer using the standard endianness.
abstract void writeLong(long address, long v, Endianness end)
Write a 64-bit integer.
abstract void writePointer(long address, long ptr)
abstract void writeShort(long address, short v)
Write a 16-bit integer using the standard endianness.
abstract void writeShort(long address, short v, Endianness end)
Write a 16-bit integer.

Constants

public static final int ACCESS_EXECUTE

Constant Value: 4 (0x00000004)

public static final int ACCESS_NONE

No access. The page exists but any attempt to write, read, or execute from/to it will raise.

Constant Value: 0 (0x00000000)

public static final int ACCESS_READ

Constant Value: 1 (0x00000001)

public static final int ACCESS_RW

Read/Write access.

Constant Value: 3 (0x00000003)

public static final int ACCESS_RWX

Read/Write/Execute access.

Constant Value: 7 (0x00000007)

public static final int ACCESS_RX

Read/Execute access.

Constant Value: 5 (0x00000005)

public static final int ACCESS_WRITE

Constant Value: 2 (0x00000002)

Public Methods

public abstract void addAllocListener (IMemoryAllocListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void addFreeListener (IMemoryFreeListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void addPreWriteListener (IMemoryWriteListener listener)

Note: The callback is invoked before the write operation takes place.

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void addPropertyListener (IMemoryPropertyListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void addProtectionListener (IMemoryProtectionListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void addWriteListener (IMemoryWriteListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void allocate (long address, int size, int protection)

Allocate the entire memory range or nothing (fail). On error, this method should throw a MemoryException, and no page should have been allocated. If successful, all pages within the range should have been been allocated.

Parameters
address address (unsigned)
size size to be allocated (unsigned)
protection protection flag (see ACCESS_READ, ACCESS_WRITE ...)

public abstract void allocatePage (long address, int protection)

Allocate a single page. See allocate(long, int, int).

public abstract int check (long address, int size, int protection)

Check if a memory range has at least the given set of protection flags.

Parameters
address start address (unsigned)
size range size (unsigned)
protection protection to check
Returns
  • the number of contiguous bytes, starting from `address`, that have the given protection flags. The amount may be less than `size`. If the check is successful, the returned value should be equal to `size`

public abstract IVirtualMemory duplicate ()

Make a deep copy of this virtual memory.

Implementation note: the resulting object may not be of the same type as the source (this) object.

Returns
  • a new memory object
Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void free (long address, int size)

Free the entire memory range or fail. On error, this method should throw a MemoryException, and no page should have been freed. If successful, all pages within the range should have been been freed.

public abstract void freePage (long address)

Free a single page. See free(long, int).

public abstract Collection<Long> getAllocatedPageBases ()

Retrieve the base addresses of the pages that are allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).

Returns
  • a sorted (ascending) collection of unique page addresses
Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract int getAllocatedPageCount ()

Get the number of pages allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).

Returns
  • the number of allocated pages (limited to 2B)
Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract int getAproximateFootprint ()

Determine the approximate memory footprint of this object, in kilobytes.

Returns
  • a size in Kb
Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract int getPageBits ()

Get the width of a memory page in bits. Example: a 4Kb page has a 12-bit width.

public abstract int getPageProtection (long address)

Get the protection flags for a page. This method raises on error (invalid address, no page, etc.)

Parameters
address address within the page
Returns
  • the protection bits

public abstract int getPageSize ()

Get the size of a page in bytes. A page size should always be a multiple of 2.

This method is mostly applicable to page-based virtual memories, but can also be used for other types of memories to indicate the optimal (in terms of performance) unit size of access.

public abstract int getSpaceBits ()

Get the width of this memory space in bits. Example: 32 for a 32-bit address space.

public abstract Endianness getStandardEndianess ()

Get the standard endianness. It is used by the readShort(long), writeShort(long, short), readInt(long), writeInt(long, int), readLong(long), and writeLong(long, long) methods.

public abstract boolean isAllocatedPage (long address)

Determine whether the provided address belongs to an allocated page.

This method is applicable to page-based virtual memories only.

Parameters
address a page address or address in the page
Returns
  • true if the page is allocated

public abstract boolean isValidAddress (long address)

Determine if an address is valid for this memory space.

Returns
  • true if the address is not larger than what this memory space allows, that is, 0 ≤ address < spaceSize

public abstract int read (long address, int size, byte[] dst, int dstOffset, boolean bypassProtection)

Read a range of bytes. This method should do its best to transact: the entire range is read, or nothing is and an error is thrown. If the implementor cannot support transaction, this method simply returns the amount of bytes read.

Parameters
bypassProtection if true, memory page protection is disregarded and non-readable bytes may be read
Returns
  • the amount of bytes read (potentially less than requested if the method does not transact)
Throws
MemoryException if the method failed

public abstract int read (long address, int size, byte[] dst, int dstOffset)

Read a range of bytes. This method should do its best to transact: the entire range is read, or nothing is and an error is thrown. If the implementor cannot support transaction, this method simply returns the amount of bytes read. The address range must be readable, else the method will throw.

Returns
  • the amount of bytes read (potentially less than requested if the method does not transact)
Throws
MemoryException if the method failed

public abstract int readBEInt (long address)

Read a big-endian 32-bit integer. This method does not do partial reads.@return

public abstract long readBELong (long address)

Read a big-endian 64-bit integer. This method does not do partial reads.@return

public abstract short readBEShort (long address)

Read a big-endian 16-bit integer. This method does not do partial reads.@return

public abstract byte readByte (long address)

Convenience method. Read a byte.@return

public abstract int readInt (long address, Endianness end)

Read a 32-bit integer. This method does not do partial reads.@return

public abstract int readInt (long address)

Read a 32-bit integer using the standard endianness. This method does not do partial reads.@return

public abstract int readLEInt (long address)

Read a little-endian 32-bit integer. This method does not do partial reads.@return

public abstract long readLELong (long address)

Read a little-endian 64-bit integer. This method does not do partial reads.@return

public abstract short readLEShort (long address)

Read a little-endian 16-bit integer. This method does not do partial reads.@return

public abstract long readLong (long address, Endianness end)

Read a 64-bit integer. This method does not do partial reads.@return

public abstract long readLong (long address)

Read a 64-bit integer using the standard endianness. This method does not do partial reads.@return

public abstract long readPointer (long address)

@return

public abstract short readShort (long address, Endianness end)

Read a 16-bit integer. This method does not do partial reads.@return

public abstract short readShort (long address)

Read a 16-bit integer using the standard endianness. This method does not do partial reads.@return

public abstract void removeAllocListener (IMemoryAllocListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void removeFreeListener (IMemoryFreeListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void removePreWriteListener (IMemoryWriteListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void removePropertyListener (IMemoryPropertyListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void removeProtectionListener (IMemoryProtectionListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract void removeWriteListener (IMemoryWriteListener listener)

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract long roundToPage (long address)

Round an address to the page this address currently resides in, that is the highest page so that boundary ≤ address. This method does not raise, even if the address is invalid for this memory space.

Parameters
address an address
Returns
  • the containing page address

public abstract long roundToSize (long address)

Round an address to the lowest page boundary so that address ≤ boundary. This method does not raise, even if the address is invalid for this memory space.

Parameters
address an address or a size

public abstract void setLazyMemoryProvider (ILazyMemoryProvider lazyMemoryProvider, boolean skipFailedAllocations)

Set a lazy memory provider. This operation is optional. If the memory object supports it, the getRanges() method will be called to reserve the ranges of memory that the provider can provide. A lazy provider provides memory data on demand, i.e. when the data bytes are accessed (read or write).

Parameters
lazyMemoryProvider a non-null lazy memory provider
skipFailedAllocations if true, the provider will not hard-fail if it provides data for a range for which data already exists in the virtual memory; else, the method will throw
Throws
MemoryException if a page reservation failed and skipFailedAllocations is false (example: the memory provider requests to allocate an already allocated range)
UnsupportedOperationException if the implementation does not support that feature

public abstract void setPageProtection (long address, int protection)

Set the protection flags for a page. This method raises on error (invalid address, no page, etc.)

Parameters
address address within the page
protection the new protection for the page

public abstract void setStandardEndianness (Endianness endianness)

Set the standard endianness. It is used by the readShort(long), writeShort(long, short), readInt(long), writeInt(long, int), readLong(long), and writeLong(long, long) methods.

Throws
UnsupportedOperationException if the implementation does not support that feature

public abstract int write (long address, int size, byte[] src, int srcOffset)

Write a range of bytes. This method should do its best to transact: the entire range is written, or nothing is and an error is thrown. If the implementor cannot support transaction, this method returns the amount of bytes written, or throws on error. The address range must be writable, else the method will throw.

Returns
  • the amount of bytes written (potentially less than requested if the method does not transact)
Throws
MemoryException if the method failed

public abstract int write (long address, int size, byte[] src, int srcOffset, boolean bypassProtection)

Write a range of bytes. This method should do its best to transact: the entire range is written, or nothing is and an error is thrown. If the implementor cannot support transaction, this method returns the amount of bytes written, or throws on error.

Parameters
bypassProtection if true, memory page protection is disregarded and non-writable bytes may be written
Returns
  • the amount of bytes written (potentially less than requested if the method does not transact)
Throws
MemoryException if the method failed

public abstract void writeBEInt (long address, int v)

Write a big-endian 32-bit integer. This method does not do partial writes.

public abstract void writeBELong (long address, long v)

Write a big-endian 64-bit integer. This method does not do partial writes.

public abstract void writeBEShort (long address, short v)

Write a big-endian 16-bit integer. This method does not do partial writes.

public abstract void writeByte (long address, byte v)

Write a byte.

public abstract void writeInt (long address, int v, Endianness end)

Write a 32-bit integer. This method does not do partial writes.

public abstract void writeInt (long address, int v)

Write a 32-bit integer using the standard endianness. This method does not do partial writes.

public abstract void writeLEInt (long address, int v)

Write a little-endian 32-bit integer. This method does not do partial writes.

public abstract void writeLELong (long address, long v)

Write a little-endian 64-bit integer. This method does not do partial writes.

public abstract void writeLEShort (long address, short v)

Write a little-endian 16-bit integer. This method does not do partial writes.

public abstract void writeLong (long address, long v)

Write a 64-bit integer using the standard endianness. This method does not do partial writes.

public abstract void writeLong (long address, long v, Endianness end)

Write a 64-bit integer. This method does not do partial writes.

public abstract void writePointer (long address, long ptr)

public abstract void writeShort (long address, short v)

Write a 16-bit integer using the standard endianness. This method does not do partial writes.

public abstract void writeShort (long address, short v, Endianness end)

Write a 16-bit integer. This method does not do partial writes.