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
      See Also:

    • ACCESS_WRITE

      static final int ACCESS_WRITE
      See Also:

    • ACCESS_EXECUTE

      static final int ACCESS_EXECUTE
      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:

    • getPageBits

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

    • getSpaceBits

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

    • 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:

    • 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 -
      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 -
      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:

    • 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

    • 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 -
      size -
      Throws:
      MemoryException

    • allocatePage

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

    • freePage

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

    • setAddressMassagerType

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

    • getAddressMassager

      default int getAddressMassager()
      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

    • 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

    • 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 -
      size -
      dst -
      dstOffset -
      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 -
      size -
      dst -
      dstOffset -
      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 -
      size -
      src -
      srcOffset -
      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 -
      size -
      src -
      srcOffset -
      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 -
      Returns:
      Throws:
      MemoryException

    • writeByte

      void writeByte(long address, byte v) throws MemoryException
      Write a byte.
      Parameters:
      address -
      v -
      Throws:
      MemoryException

    • readLEShort

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

    • 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 -
      v -
      Throws:
      MemoryException

    • readLEInt

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

    • 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 -
      v -
      Throws:
      MemoryException

    • readLELong

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

    • 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 -
      v -
      Throws:
      MemoryException

    • readBEShort

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

    • 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 -
      v -
      Throws:
      MemoryException

    • readBEInt

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

    • 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 -
      v -
      Throws:
      MemoryException

    • readBELong

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

    • 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 -
      v -
      Throws:
      MemoryException

    • 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 -
      Returns:
      Throws:
      MemoryException

    • 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 -
      v -
      Throws:
      MemoryException

    • 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 -
      Returns:
      Throws:
      MemoryException

    • 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 -
      v -
      Throws:
      MemoryException

    • 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 -
      Returns:
      Throws:
      MemoryException

    • 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 -
      v -
      Throws:
      MemoryException

    • readShort

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

    • 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 -
      v -
      end -
      Throws:
      MemoryException

    • readInt

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

    • 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 -
      v -
      end -
      Throws:
      MemoryException

    • readLong

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

    • 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 -
      v -
      end -
      Throws:
      MemoryException

    • readPointer

      long readPointer(long address) throws MemoryException
      Parameters:
      address -
      Returns:
      Throws:
      MemoryException

    • writePointer

      void writePointer(long address, long ptr) throws MemoryException
      Parameters:
      address -
      ptr -
      Throws:
      MemoryException

    • addPropertyListener

      void addPropertyListener(IMemoryPropertyListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removePropertyListener

      void removePropertyListener(IMemoryPropertyListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addAllocListener

      void addAllocListener(IMemoryAllocListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeAllocListener

      void removeAllocListener(IMemoryAllocListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addFreeListener

      void addFreeListener(IMemoryFreeListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeFreeListener

      void removeFreeListener(IMemoryFreeListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addProtectionListener

      void addProtectionListener(IMemoryProtectionListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeProtectionListener

      void removeProtectionListener(IMemoryProtectionListener listener)
      Parameters:
      listener -
      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 -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removePreWriteListener

      void removePreWriteListener(IMemoryWriteListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • addWriteListener

      void addWriteListener(IMemoryWriteListener listener)
      Parameters:
      listener -
      Throws:
      UnsupportedOperationException - if the implementation does not support that feature

    • removeWriteListener

      void removeWriteListener(IMemoryWriteListener listener)
      Parameters:
      listener -
      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