Package com.pnfsoftware.jeb.core.units.code.asm.memory

Interface IVirtualMemory

All Known Subinterfaces:
IDebuggerVirtualMemory, IVirtualMemoryShim
All Known Implementing Classes:
AbstractVirtualMemory
@Ser public interface IVirtualMemory
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.

  • Field Details

    • ACCESS_NONE

      static final int ACCESS_NONE
      No access. The page exists but any attempt to write, read, or execute from/to it will raise.
      See Also:

    • ACCESS_READ

      static final int ACCESS_READ
      Read access.
      See Also:

    • ACCESS_WRITE

      static final int ACCESS_WRITE
      Write access.
      See Also:

    • ACCESS_EXECUTE

      static final int ACCESS_EXECUTE
      Execute access.
      See Also:

    • ACCESS_RW

      static final int ACCESS_RW
      Read/Write access.
      See Also:

    • ACCESS_RX

      static final int ACCESS_RX
      Read/Execute access.
      See Also:

    • ACCESS_RWX

      static final int ACCESS_RWX
      Read/Write/Execute access.
      See Also:

    • AM_ARM64_48BIT

      static final int AM_ARM64_48BIT
      Address massager type to specify an Arm64 MMU address regime that ignores the top 2 bytes.
      See Also:

  • Method Details

    • getPageSize

      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.

      Returns:
      page size in bytes

    • getPageBits

      default int getPageBits()
      Get the width of a memory page in bits. Example: a 4Kb page has a 12-bit width.
      Returns:
      page width in bits

    • getSpaceBits

      int getSpaceBits()
      Get the width of this memory space in bits. Example: 32 for a 32-bit address space.
      Returns:
      address-space width in bits

    • getStandardEndianess

      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.
      Returns:
      standard endianness

    • setStandardEndianness

      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.
      Parameters:
      endianness - standard endianness
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • duplicate

      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

    • isValidAddress

      boolean isValidAddress(long address)
      Determine if an address is valid for this memory space.
      Parameters:
      address - address to test
      Returns:
      true if the address is not larger than what this memory space allows, that is, 0 ≤ address < spaceSize

    • roundToPage

      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

    • roundToSize

      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
      Returns:
      rounded address

    • getAllocatedPageCount

      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

    • getAllocatedPageBases

      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

    • allocate

      void allocate(long address, int size, int protection) throws MemoryException
      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 ...)
      Throws:
      MemoryException - if allocation fails

    • free

      void free(long address, int size) throws MemoryException
      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.
      Parameters:
      address - start address
      size - size to free
      Throws:
      MemoryException - if freeing fails

    • allocatePage

      void allocatePage(long address, int protection) throws MemoryException
      Allocate a single page. See allocate(long, int, int).
      Parameters:
      address - page address
      protection - protection flags
      Throws:
      MemoryException - if allocation fails

    • freePage

      void freePage(long address) throws MemoryException
      Free a single page. See free(long, int).
      Parameters:
      address - page address
      Throws:
      MemoryException - if freeing fails

    • setAddressMassagerType

      default void setAddressMassagerType(int type)
      Set the address massager type.
      Parameters:
      type - one of the AM_xxx constants
      Throws:
      UnsupportedOperationException - not all memory objects support this operation

    • getAddressMassager

      default int getAddressMassager()
      Retrieve the address massager type.
      Returns:
      one of the AM_xxx constants

    • setPageProtection

      void setPageProtection(long address, int protection) throws MemoryException
      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
      Throws:
      MemoryException - if protection cannot be updated

    • getPageProtection

      int getPageProtection(long address) throws MemoryException
      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
      Throws:
      MemoryException - if protection cannot be retrieved

    • isAllocatedPage

      default 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

    • check

      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

    • read

      int read(long address, int size, byte[] dst, int dstOffset, boolean bypassProtection) throws MemoryException
      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:
      address - start address
      size - number of bytes to read
      dst - destination buffer
      dstOffset - destination offset
      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

    • read

      default int read(long address, int size, byte[] dst, int dstOffset) throws MemoryException
      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.
      Parameters:
      address - start address
      size - number of bytes to read
      dst - destination buffer
      dstOffset - destination offset
      Returns:
      the amount of bytes read (potentially less than requested if the method does not transact)
      Throws:
      MemoryException - if the method failed

    • write

      int write(long address, int size, byte[] src, int srcOffset, boolean bypassProtection) throws MemoryException
      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:
      address - start address
      size - number of bytes to write
      src - source buffer
      srcOffset - source offset
      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

    • write

      default int write(long address, int size, byte[] src, int srcOffset) throws MemoryException
      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.
      Parameters:
      address - start address
      size - number of bytes to write
      src - source buffer
      srcOffset - source offset
      Returns:
      the amount of bytes written (potentially less than requested if the method does not transact)
      Throws:
      MemoryException - if the method failed

    • readByte

      byte readByte(long address) throws MemoryException
      Convenience method. Read a byte.
      Parameters:
      address - address to read
      Returns:
      byte value
      Throws:
      MemoryException - if reading fails

    • writeByte

      void writeByte(long address, byte v) throws MemoryException
      Write a byte.
      Parameters:
      address - address to write
      v - byte value
      Throws:
      MemoryException - if writing fails

    • readLEShort

      short readLEShort(long address) throws MemoryException
      Read a little-endian 16-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      16-bit value
      Throws:
      MemoryException - if reading fails

    • writeLEShort

      void writeLEShort(long address, short v) throws MemoryException
      Write a little-endian 16-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 16-bit value
      Throws:
      MemoryException - if writing fails

    • readLEInt

      int readLEInt(long address) throws MemoryException
      Read a little-endian 32-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      32-bit value
      Throws:
      MemoryException - if reading fails

    • writeLEInt

      void writeLEInt(long address, int v) throws MemoryException
      Write a little-endian 32-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 32-bit value
      Throws:
      MemoryException - if writing fails

    • readLELong

      long readLELong(long address) throws MemoryException
      Read a little-endian 64-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      64-bit value
      Throws:
      MemoryException - if reading fails

    • writeLELong

      void writeLELong(long address, long v) throws MemoryException
      Write a little-endian 64-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 64-bit value
      Throws:
      MemoryException - if writing fails

    • readBEShort

      short readBEShort(long address) throws MemoryException
      Read a big-endian 16-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      16-bit value
      Throws:
      MemoryException - if reading fails

    • writeBEShort

      void writeBEShort(long address, short v) throws MemoryException
      Write a big-endian 16-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 16-bit value
      Throws:
      MemoryException - if writing fails

    • readBEInt

      int readBEInt(long address) throws MemoryException
      Read a big-endian 32-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      32-bit value
      Throws:
      MemoryException - if reading fails

    • writeBEInt

      void writeBEInt(long address, int v) throws MemoryException
      Write a big-endian 32-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 32-bit value
      Throws:
      MemoryException - if writing fails

    • readBELong

      long readBELong(long address) throws MemoryException
      Read a big-endian 64-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      64-bit value
      Throws:
      MemoryException - if reading fails

    • writeBELong

      void writeBELong(long address, long v) throws MemoryException
      Write a big-endian 64-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 64-bit value
      Throws:
      MemoryException - if writing fails

    • readShort

      short readShort(long address) throws MemoryException
      Read a 16-bit integer using the standard endianness. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      16-bit value
      Throws:
      MemoryException - if reading fails

    • writeShort

      void writeShort(long address, short v) throws MemoryException
      Write a 16-bit integer using the standard endianness. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 16-bit value
      Throws:
      MemoryException - if writing fails

    • readInt

      int readInt(long address) throws MemoryException
      Read a 32-bit integer using the standard endianness. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      32-bit value
      Throws:
      MemoryException - if reading fails

    • writeInt

      void writeInt(long address, int v) throws MemoryException
      Write a 32-bit integer using the standard endianness. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 32-bit value
      Throws:
      MemoryException - if writing fails

    • readLong

      long readLong(long address) throws MemoryException
      Read a 64-bit integer using the standard endianness. This method does not do partial reads.
      Parameters:
      address - address to read
      Returns:
      64-bit value
      Throws:
      MemoryException - if reading fails

    • writeLong

      void writeLong(long address, long v) throws MemoryException
      Write a 64-bit integer using the standard endianness. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 64-bit value
      Throws:
      MemoryException - if writing fails

    • readShort

      short readShort(long address, Endianness end) throws MemoryException
      Read a 16-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      end - endianness
      Returns:
      16-bit value
      Throws:
      MemoryException - if reading fails

    • writeShort

      void writeShort(long address, short v, Endianness end) throws MemoryException
      Write a 16-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 16-bit value
      end - endianness
      Throws:
      MemoryException - if writing fails

    • readInt

      int readInt(long address, Endianness end) throws MemoryException
      Read a 32-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      end - endianness
      Returns:
      32-bit value
      Throws:
      MemoryException - if reading fails

    • writeInt

      void writeInt(long address, int v, Endianness end) throws MemoryException
      Write a 32-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 32-bit value
      end - endianness
      Throws:
      MemoryException - if writing fails

    • readLong

      long readLong(long address, Endianness end) throws MemoryException
      Read a 64-bit integer. This method does not do partial reads.
      Parameters:
      address - address to read
      end - endianness
      Returns:
      64-bit value
      Throws:
      MemoryException - if reading fails

    • writeLong

      void writeLong(long address, long v, Endianness end) throws MemoryException
      Write a 64-bit integer. This method does not do partial writes.
      Parameters:
      address - address to write
      v - 64-bit value
      end - endianness
      Throws:
      MemoryException - if writing fails

    • readPointer

      long readPointer(long address) throws MemoryException
      Read a pointer-sized integer.
      Parameters:
      address - address to read
      Returns:
      pointer value
      Throws:
      MemoryException - if reading fails

    • writePointer

      void writePointer(long address, long ptr) throws MemoryException
      Write a pointer-sized integer.
      Parameters:
      address - address to write
      ptr - pointer value
      Throws:
      MemoryException - if writing fails

    • addPropertyListener

      void addPropertyListener(IMemoryPropertyListener listener)
      Add a memory property listener.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removePropertyListener

      void removePropertyListener(IMemoryPropertyListener listener)
      Remove a memory property listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addAllocListener

      void addAllocListener(IMemoryAllocListener listener)
      Add a memory allocation listener.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeAllocListener

      void removeAllocListener(IMemoryAllocListener listener)
      Remove a memory allocation listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addFreeListener

      void addFreeListener(IMemoryFreeListener listener)
      Add a memory free listener.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeFreeListener

      void removeFreeListener(IMemoryFreeListener listener)
      Remove a memory free listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addProtectionListener

      void addProtectionListener(IMemoryProtectionListener listener)
      Add a memory protection listener.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeProtectionListener

      void removeProtectionListener(IMemoryProtectionListener listener)
      Remove a memory protection listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addPreWriteListener

      void addPreWriteListener(IMemoryWriteListener listener)
      Note: The callback is invoked before the write operation takes place.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removePreWriteListener

      void removePreWriteListener(IMemoryWriteListener listener)
      Remove a pre-write listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addWriteListener

      void addWriteListener(IMemoryWriteListener listener)
      Add a memory write listener.
      Parameters:
      listener - listener to add
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeWriteListener

      void removeWriteListener(IMemoryWriteListener listener)
      Remove a memory write listener.
      Parameters:
      listener - listener to remove
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • setLazyMemoryProvider

      void setLazyMemoryProvider(ILazyMemoryProvider lazyMemoryProvider, boolean skipFailedAllocations) throws MemoryException, UnsupportedOperationException
      Set a lazy memory provider. This operation is optional. If the memory object supports it, the ILazyMemoryProvider.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

    • getAproximateFootprint

      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