com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory |
Known Indirect Subclasses |
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.
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.
|
No access. The page exists but any attempt to write, read, or execute from/to it will raise.
Read/Write access.
Read/Write/Execute access.
Read/Execute access.
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
Note: The callback is invoked before the write operation takes place.
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
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.
address | address (unsigned) |
---|---|
size | size to be allocated (unsigned) |
protection | protection flag (see ACCESS_READ , ACCESS_WRITE ...) |
MemoryException |
---|
Allocate a single page. See allocate(long, int, int)
.
MemoryException |
---|
Check if a memory range has at least the given set of protection flags.
address | start address (unsigned) |
---|---|
size | range size (unsigned) |
protection | protection to check |
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.
UnsupportedOperationException | if the implementation does not support that feature |
---|
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.
MemoryException |
---|
Free a single page. See free(long, int)
.
MemoryException |
---|
Retrieve the base addresses of the pages that are allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).
UnsupportedOperationException | if the implementation does not support that feature |
---|
Get the number of pages allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).
UnsupportedOperationException | if the implementation does not support that feature |
---|
Determine the approximate memory footprint of this object, in kilobytes.
UnsupportedOperationException | if the implementation does not support that feature |
---|
Get the width of a memory page in bits. Example: a 4Kb page has a 12-bit width.
Get the protection flags for a page. This method raises on error (invalid address, no page, etc.)
address | address within the page |
---|
MemoryException |
---|
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.
Get the width of this memory space in bits. Example: 32 for a 32-bit address space.
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.
Determine whether the provided address belongs to an allocated page.
This method is applicable to page-based virtual memories only.
address | a page address or address in the page |
---|
Determine if an address is valid for this memory space.
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.
bypassProtection | if true, memory page protection is disregarded and non-readable bytes may be read |
---|
MemoryException | if the method failed |
---|
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.
MemoryException | if the method failed |
---|
Read a big-endian 32-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a big-endian 64-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a big-endian 16-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Convenience method. Read a byte.@return
MemoryException |
---|
Read a 32-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a 32-bit integer using the standard endianness
. This
method does not do partial reads.@return
MemoryException |
---|
Read a little-endian 32-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a little-endian 64-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a little-endian 16-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a 64-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a 64-bit integer using the standard endianness
. This
method does not do partial reads.@return
MemoryException |
---|
Read a 16-bit integer. This method does not do partial reads.@return
MemoryException |
---|
Read a 16-bit integer using the standard endianness
. This
method does not do partial reads.@return
MemoryException |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
UnsupportedOperationException | if the implementation does not support that feature |
---|
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.
address | an 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.
address | an address or a size |
---|
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).
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 |
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 |
Set the protection flags for a page. This method raises on error (invalid address, no page, etc.)
address | address within the page |
---|---|
protection | the new protection for the page |
MemoryException |
---|
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.
UnsupportedOperationException | if the implementation does not support that feature |
---|
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.
MemoryException | if the method failed |
---|
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.
bypassProtection | if true, memory page protection is disregarded and non-writable bytes may be written |
---|
MemoryException | if the method failed |
---|
Write a big-endian 32-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a big-endian 64-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a big-endian 16-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a 32-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a 32-bit integer using the standard endianness
. This
method does not do partial writes.
MemoryException |
---|
Write a little-endian 32-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a little-endian 64-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a little-endian 16-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a 64-bit integer using the standard endianness
. This
method does not do partial writes.
MemoryException |
---|
Write a 64-bit integer. This method does not do partial writes.
MemoryException |
---|
Write a 16-bit integer using the standard endianness
. This
method does not do partial writes.
MemoryException |
---|
Write a 16-bit integer. This method does not do partial writes.
MemoryException |
---|