Interface IVirtualMemory
- All Known Subinterfaces:
IDebuggerVirtualMemory
,IVirtualMemoryShim
- All Known Implementing Classes:
AbstractVirtualMemory
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final int
static final int
No access.static final int
static final int
Read/Write access.static final int
Read/Write/Execute access.static final int
Read/Execute access.static final int
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addAllocListener
(IMemoryAllocListener listener) void
addFreeListener
(IMemoryFreeListener listener) void
addPreWriteListener
(IMemoryWriteListener listener) Note: The callback is invoked before the write operation takes place.void
addPropertyListener
(IMemoryPropertyListener listener) void
void
addWriteListener
(IMemoryWriteListener listener) void
allocate
(long address, int size, int protection) Allocate the entire memory range or nothing (fail).void
allocatePage
(long address, int protection) Allocate a single page.int
check
(long address, int size, int protection) Check if a memory range has at least the given set of protection flags.Make a deep copy of this virtual memory.void
free
(long address, int size) Free the entire memory range or fail.void
freePage
(long address) Free a single page.Retrieve the base addresses of the pages that are allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).int
Get the number of pages allocated (in the most general sense: that includes pages "reserved", depending on VM implementation).int
Determine the approximate memory footprint of this object, in kilobytes.default int
Get the width of a memory page in bits.int
getPageProtection
(long address) Get the protection flags for a page.int
Get the size of a page in bytes.int
Get the width of this memory space in bits.Get the standard endianness.default boolean
isAllocatedPage
(long address) Determine whether the provided address belongs to an allocated page.boolean
isValidAddress
(long address) Determine if an address is valid for this memory space.default int
read
(long address, int size, byte[] dst, int dstOffset) Read a range of bytes.int
read
(long address, int size, byte[] dst, int dstOffset, boolean bypassProtection) Read a range of bytes.int
readBEInt
(long address) Read a big-endian 32-bit integer.long
readBELong
(long address) Read a big-endian 64-bit integer.short
readBEShort
(long address) Read a big-endian 16-bit integer.byte
readByte
(long address) Convenience method.int
readInt
(long address) Read a 32-bit integer using thestandard endianness
.int
readInt
(long address, Endianness end) Read a 32-bit integer.int
readLEInt
(long address) Read a little-endian 32-bit integer.long
readLELong
(long address) Read a little-endian 64-bit integer.short
readLEShort
(long address) Read a little-endian 16-bit integer.long
readLong
(long address) Read a 64-bit integer using thestandard endianness
.long
readLong
(long address, Endianness end) Read a 64-bit integer.long
readPointer
(long address) short
readShort
(long address) Read a 16-bit integer using thestandard endianness
.short
readShort
(long address, Endianness end) Read a 16-bit integer.void
removeAllocListener
(IMemoryAllocListener listener) void
removeFreeListener
(IMemoryFreeListener listener) void
removePreWriteListener
(IMemoryWriteListener listener) void
void
void
removeWriteListener
(IMemoryWriteListener listener) long
roundToPage
(long address) Round an address to the page this address currently resides in, that is the highest page so that boundary ≤ address.long
roundToSize
(long address) Round an address to the lowest page boundary so that address ≤ boundary.void
setLazyMemoryProvider
(ILazyMemoryProvider lazyMemoryProvider, boolean skipFailedAllocations) Set a lazy memory provider.void
setPageProtection
(long address, int protection) Set the protection flags for a page.void
setStandardEndianness
(Endianness endianness) Set the standard endianness.default int
write
(long address, int size, byte[] src, int srcOffset) Write a range of bytes.int
write
(long address, int size, byte[] src, int srcOffset, boolean bypassProtection) Write a range of bytes.void
writeBEInt
(long address, int v) Write a big-endian 32-bit integer.void
writeBELong
(long address, long v) Write a big-endian 64-bit integer.void
writeBEShort
(long address, short v) Write a big-endian 16-bit integer.void
writeByte
(long address, byte v) Write a byte.void
writeInt
(long address, int v) Write a 32-bit integer using thestandard endianness
.void
writeInt
(long address, int v, Endianness end) Write a 32-bit integer.void
writeLEInt
(long address, int v) Write a little-endian 32-bit integer.void
writeLELong
(long address, long v) Write a little-endian 64-bit integer.void
writeLEShort
(long address, short v) Write a little-endian 16-bit integer.void
writeLong
(long address, long v) Write a 64-bit integer using thestandard endianness
.void
writeLong
(long address, long v, Endianness end) Write a 64-bit integer.void
writePointer
(long address, long ptr) void
writeShort
(long address, short v) Write a 16-bit integer using thestandard endianness
.void
writeShort
(long address, short v, Endianness end) Write a 16-bit integer.
-
Field Details
-
ACCESS_NONE
static final int ACCESS_NONENo 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_RWRead/Write access.- See Also:
-
ACCESS_RX
static final int ACCESS_RXRead/Execute access.- See Also:
-
ACCESS_RWX
static final int ACCESS_RWXRead/Write/Execute access.- 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 thereadShort(long)
,writeShort(long, short)
,readInt(long)
,writeInt(long, int)
,readLong(long)
, andwriteLong(long, long)
methods.- Returns:
-
setStandardEndianness
Set the standard endianness. It is used by thereadShort(long)
,writeShort(long, short)
,readInt(long)
,writeInt(long, int)
,readLong(long)
, andwriteLong(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
Allocate the entire memory range or nothing (fail). On error, this method should throw aMemoryException
, 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 (seeACCESS_READ
,ACCESS_WRITE
...)- Throws:
MemoryException
-
free
Free the entire memory range or fail. On error, this method should throw aMemoryException
, 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
Allocate a single page. Seeallocate(long, int, int)
.- Parameters:
address
-protection
-- Throws:
MemoryException
-
freePage
Free a single page. Seefree(long, int)
.- Parameters:
address
-- Throws:
MemoryException
-
setPageProtection
Set the protection flags for a page. This method raises on error (invalid address, no page, etc.)- Parameters:
address
- address within the pageprotection
- the new protection for the page- Throws:
MemoryException
-
getPageProtection
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
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
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
Convenience method. Read a byte.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeByte
Write a byte.- Parameters:
address
-v
-- Throws:
MemoryException
-
readLEShort
Read a little-endian 16-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeLEShort
Write a little-endian 16-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readLEInt
Read a little-endian 32-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeLEInt
Write a little-endian 32-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readLELong
Read a little-endian 64-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeLELong
Write a little-endian 64-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readBEShort
Read a big-endian 16-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeBEShort
Write a big-endian 16-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readBEInt
Read a big-endian 32-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeBEInt
Write a big-endian 32-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readBELong
Read a big-endian 64-bit integer. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeBELong
Write a big-endian 64-bit integer. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readShort
Read a 16-bit integer using thestandard endianness
. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeShort
Write a 16-bit integer using thestandard endianness
. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readInt
Read a 32-bit integer using thestandard endianness
. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeInt
Write a 32-bit integer using thestandard endianness
. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readLong
Read a 64-bit integer using thestandard endianness
. This method does not do partial reads.- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writeLong
Write a 64-bit integer using thestandard endianness
. This method does not do partial writes.- Parameters:
address
-v
-- Throws:
MemoryException
-
readShort
Read a 16-bit integer. This method does not do partial reads.- Parameters:
address
-end
-- Returns:
- Throws:
MemoryException
-
writeShort
Write a 16-bit integer. This method does not do partial writes.- Parameters:
address
-v
-end
-- Throws:
MemoryException
-
readInt
Read a 32-bit integer. This method does not do partial reads.- Parameters:
address
-end
-- Returns:
- Throws:
MemoryException
-
writeInt
Write a 32-bit integer. This method does not do partial writes.- Parameters:
address
-v
-end
-- Throws:
MemoryException
-
readLong
Read a 64-bit integer. This method does not do partial reads.- Parameters:
address
-end
-- Returns:
- Throws:
MemoryException
-
writeLong
Write a 64-bit integer. This method does not do partial writes.- Parameters:
address
-v
-end
-- Throws:
MemoryException
-
readPointer
- Parameters:
address
-- Returns:
- Throws:
MemoryException
-
writePointer
- Parameters:
address
-ptr
-- Throws:
MemoryException
-
addPropertyListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removePropertyListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
addAllocListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removeAllocListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
addFreeListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removeFreeListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
addProtectionListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removeProtectionListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
addPreWriteListener
Note: The callback is invoked before the write operation takes place.- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removePreWriteListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
addWriteListener
- Parameters:
listener
-- Throws:
UnsupportedOperationException
- if the implementation does not support that feature
-
removeWriteListener
- 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, theILazyMemoryProvider.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 providerskipFailedAllocations
- 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 isfalse
(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
-