# Interface: com.pnfsoftware.jeb.core.units.code.asm.memory.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](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](UnsupportedOperationException). 

 Implementors may decide to provide support for concurrency.

## Static Field: ACCESS_EXECUTE
Type: `int`

Constant value: `4`
Description: Execute access.

## Static Field: ACCESS_NONE
Type: `int`

Constant value: `0`
Description: No access. The page exists but any attempt to write, read, or execute from/to it will raise.

## Static Field: ACCESS_READ
Type: `int`

Constant value: `1`
Description: Read access.

## Static Field: ACCESS_RW
Type: `int`

Constant value: `3`
Description: Read/Write access.

## Static Field: ACCESS_RWX
Type: `int`

Constant value: `7`
Description: Read/Write/Execute access.

## Static Field: ACCESS_RX
Type: `int`

Constant value: `5`
Description: Read/Execute access.

## Static Field: ACCESS_WRITE
Type: `int`

Constant value: `2`
Description: Write access.

## Static Field: AM_ARM64_48BIT
Type: `int`

Constant value: `1`
Description: Address massager type to specify an Arm64 MMU address regime that ignores the top 2 bytes.

## Method: addAllocListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryAllocListener`

Description: Add a memory allocation listener.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: addFreeListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryFreeListener`

Description: Add a memory free listener.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: addPreWriteListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryWriteListener`

Description: Note: The callback is invoked before the write operation takes place.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: addPropertyListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryPropertyListener`

Description: Add a memory property listener.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: addProtectionListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryProtectionListener`

Description: Add a memory protection listener.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: addWriteListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryWriteListener`

Description: Add a memory write listener.
parameter: listener: listener to add
throws: if the implementation does not support that feature

## Method: allocate
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `protection`, type: `int`

Description: Allocate the entire memory range or nothing \(fail\). On error, this method should throw a [MemoryException](MemoryException), and no page should have been allocated. If successful, all pages within the range should have been been allocated.
parameter: address: address \(unsigned\)
parameter: size: size to be allocated \(unsigned\)
parameter: protection: protection flag \(see [#ACCESS_READ](#ACCESS_READ), [#ACCESS_WRITE](#ACCESS_WRITE) ...\)
throws: if allocation fails

## Method: allocatePage
- parameter: `address`, type: `long`
- parameter: `protection`, type: `int`

Description: Allocate a single page. See [#allocate(long, int, int)](#allocate(long, int, int)).
parameter: address: page address
parameter: protection: protection flags
throws: if allocation fails

## Method: check
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `protection`, type: `int`
- return type: `int`

Description: Check if a memory range has at least the given set of protection flags.
parameter: address: start address \(unsigned\)
parameter: size: range size \(unsigned\)
parameter: protection: protection to check
return: 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`

## Method: duplicate
- return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory`

Description: 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.
return: a new memory object
throws: if the implementation does not support that feature

## Method: free
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`

Description: Free the entire memory range or fail. On error, this method should throw a [MemoryException](MemoryException), and no page should have been freed. If successful, all pages within the range should have been been freed.
parameter: address: start address
parameter: size: size to free
throws: if freeing fails

## Method: freePage
- parameter: `address`, type: `long`

Description: Free a single page. See [#free(long, int)](#free(long, int)).
parameter: address: page address
throws: if freeing fails

## Method: getAddressMassager
- return type: `int`

Description: Retrieve the address massager type.
return: one of the `AM_xxx` constants

## Method: getAllocatedPageBases
- return type: `java.util.Collection<java.lang.Long>`

Description: Retrieve the base addresses of the pages that are allocated \(in the most general sense: that includes pages "reserved", depending on VM implementation\).
return: a sorted \(ascending\) collection of unique page addresses
throws: if the implementation does not support that feature

## Method: getAllocatedPageCount
- return type: `int`

Description: Get the number of pages allocated \(in the most general sense: that includes pages "reserved", depending on VM implementation\).
return: the number of allocated pages \(limited to 2B\)
throws: if the implementation does not support that feature

## Method: getAproximateFootprint
- return type: `int`

Description: Determine the approximate memory footprint of this object, in kilobytes.
return: a size in Kb
throws: if the implementation does not support that feature

## Method: getPageBits
- return type: `int`

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

## Method: getPageProtection
- parameter: `address`, type: `long`
- return type: `int`

Description: Get the protection flags for a page. This method raises on error \(invalid address, no page, etc.\)
parameter: address: address within the page
return: the protection bits
throws: if protection cannot be retrieved

## Method: getPageSize
- return type: `int`

Description: 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.
return: page size in bytes

## Method: getSpaceBits
- return type: `int`

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

## Method: getStandardEndianess
- return type: `com.pnfsoftware.jeb.util.io.Endianness`

Description: Get the standard endianness. It is used by the [#readShort(long)](#readShort(long)), [#writeShort(long, short)](#writeShort(long, short)), [#readInt(long)](#readInt(long)), [#writeInt(long, int)](#writeInt(long, int)), [#readLong(long)](#readLong(long)), and [#writeLong(long, long)](#writeLong(long, long)) methods.
return: standard endianness

## Method: isAllocatedPage
- parameter: `address`, type: `long`
- return type: `boolean`

Description: Determine whether the provided address belongs to an allocated page. 

 This method is applicable to page\-based virtual memories only.
parameter: address: a page address or address in the page
return: true if the page is allocated

## Method: isValidAddress
- parameter: `address`, type: `long`
- return type: `boolean`

Description: Determine if an address is valid for this memory space.
parameter: address: address to test
return: true if the address is not larger than what this memory space allows, that is, 0 ≤         address < spaceSize

## Method: read
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `dst`, type: `byte[]`
- parameter: `dstOffset`, type: `int`
- parameter: `bypassProtection`, type: `boolean`
- return type: `int`

Description: 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.
parameter: address: start address
parameter: size: number of bytes to read
parameter: dst: destination buffer
parameter: dstOffset: destination offset
parameter: bypassProtection: if true, memory page protection is disregarded and non\-readable bytes            may be read
return: the amount of bytes read \(potentially less than requested if the method does not         transact\)
throws: if the method failed

## Method: read
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `dst`, type: `byte[]`
- parameter: `dstOffset`, type: `int`
- return type: `int`

Description: 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.
parameter: address: start address
parameter: size: number of bytes to read
parameter: dst: destination buffer
parameter: dstOffset: destination offset
return: the amount of bytes read \(potentially less than requested if the method does not         transact\)
throws: if the method failed

## Method: readBEInt
- parameter: `address`, type: `long`
- return type: `int`

Description: Read a big\-endian 32\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 32\-bit value
throws: if reading fails

## Method: readBELong
- parameter: `address`, type: `long`
- return type: `long`

Description: Read a big\-endian 64\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 64\-bit value
throws: if reading fails

## Method: readBEShort
- parameter: `address`, type: `long`
- return type: `short`

Description: Read a big\-endian 16\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 16\-bit value
throws: if reading fails

## Method: readByte
- parameter: `address`, type: `long`
- return type: `byte`

Description: Convenience method. Read a byte.
parameter: address: address to read
return: byte value
throws: if reading fails

## Method: readInt
- parameter: `address`, type: `long`
- return type: `int`

Description: Read a 32\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial reads.
parameter: address: address to read
return: 32\-bit value
throws: if reading fails

## Method: readInt
- parameter: `address`, type: `long`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`
- return type: `int`

Description: Read a 32\-bit integer. This method does not do partial reads.
parameter: address: address to read
parameter: end: endianness
return: 32\-bit value
throws: if reading fails

## Method: readLEInt
- parameter: `address`, type: `long`
- return type: `int`

Description: Read a little\-endian 32\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 32\-bit value
throws: if reading fails

## Method: readLELong
- parameter: `address`, type: `long`
- return type: `long`

Description: Read a little\-endian 64\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 64\-bit value
throws: if reading fails

## Method: readLEShort
- parameter: `address`, type: `long`
- return type: `short`

Description: Read a little\-endian 16\-bit integer. This method does not do partial reads.
parameter: address: address to read
return: 16\-bit value
throws: if reading fails

## Method: readLong
- parameter: `address`, type: `long`
- return type: `long`

Description: Read a 64\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial reads.
parameter: address: address to read
return: 64\-bit value
throws: if reading fails

## Method: readLong
- parameter: `address`, type: `long`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`
- return type: `long`

Description: Read a 64\-bit integer. This method does not do partial reads.
parameter: address: address to read
parameter: end: endianness
return: 64\-bit value
throws: if reading fails

## Method: readPointer
- parameter: `address`, type: `long`
- return type: `long`

Description: Read a pointer\-sized integer.
parameter: address: address to read
return: pointer value
throws: if reading fails

## Method: readShort
- parameter: `address`, type: `long`
- return type: `short`

Description: Read a 16\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial reads.
parameter: address: address to read
return: 16\-bit value
throws: if reading fails

## Method: readShort
- parameter: `address`, type: `long`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`
- return type: `short`

Description: Read a 16\-bit integer. This method does not do partial reads.
parameter: address: address to read
parameter: end: endianness
return: 16\-bit value
throws: if reading fails

## Method: removeAllocListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryAllocListener`

Description: Remove a memory allocation listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: removeFreeListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryFreeListener`

Description: Remove a memory free listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: removePreWriteListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryWriteListener`

Description: Remove a pre\-write listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: removePropertyListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryPropertyListener`

Description: Remove a memory property listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: removeProtectionListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryProtectionListener`

Description: Remove a memory protection listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: removeWriteListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IMemoryWriteListener`

Description: Remove a memory write listener.
parameter: listener: listener to remove
throws: if the implementation does not support that feature

## Method: roundToPage
- parameter: `address`, type: `long`
- return type: `long`

Description: 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.
parameter: address: an address
return: the containing page address

## Method: roundToSize
- parameter: `address`, type: `long`
- return type: `long`

Description: 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.
parameter: address: an address or a size
return: rounded address

## Method: setAddressMassagerType
- parameter: `type`, type: `int`

Description: Set the address massager type.
parameter: type: one of the `AM_xxx` constants
throws: not all memory objects support this operation

## Method: setLazyMemoryProvider
- parameter: `lazyMemoryProvider`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.ILazyMemoryProvider`
- parameter: `skipFailedAllocations`, type: `boolean`

Description: Set a lazy memory provider. This operation is optional. If the memory object supports it, the [ILazyMemoryProvider#getRanges()](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\).
parameter: lazyMemoryProvider: a non\-null lazy memory provider
parameter: 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: if a page reservation failed and skipFailedAllocations is             `false` \(example: the memory provider requests to allocate an already             allocated range\)
throws: if the implementation does not support that feature

## Method: setPageProtection
- parameter: `address`, type: `long`
- parameter: `protection`, type: `int`

Description: Set the protection flags for a page. This method raises on error \(invalid address, no page, etc.\)
parameter: address: address within the page
parameter: protection: the new protection for the page
throws: if protection cannot be updated

## Method: setStandardEndianness
- parameter: `endianness`, type: `com.pnfsoftware.jeb.util.io.Endianness`

Description: Set the standard endianness. It is used by the [#readShort(long)](#readShort(long)), [#writeShort(long, short)](#writeShort(long, short)), [#readInt(long)](#readInt(long)), [#writeInt(long, int)](#writeInt(long, int)), [#readLong(long)](#readLong(long)), and [#writeLong(long, long)](#writeLong(long, long)) methods.
parameter: endianness: standard endianness
throws: if the implementation does not support that feature

## Method: write
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `src`, type: `byte[]`
- parameter: `srcOffset`, type: `int`
- parameter: `bypassProtection`, type: `boolean`
- return type: `int`

Description: 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.
parameter: address: start address
parameter: size: number of bytes to write
parameter: src: source buffer
parameter: srcOffset: source offset
parameter: bypassProtection: if true, memory page protection is disregarded and non\-writable bytes            may be written
return: the amount of bytes written \(potentially less than requested if the method does not         transact\)
throws: if the method failed

## Method: write
- parameter: `address`, type: `long`
- parameter: `size`, type: `int`
- parameter: `src`, type: `byte[]`
- parameter: `srcOffset`, type: `int`
- return type: `int`

Description: 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.
parameter: address: start address
parameter: size: number of bytes to write
parameter: src: source buffer
parameter: srcOffset: source offset
return: the amount of bytes written \(potentially less than requested if the method does not         transact\)
throws: if the method failed

## Method: writeBEInt
- parameter: `address`, type: `long`
- parameter: `v`, type: `int`

Description: Write a big\-endian 32\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 32\-bit value
throws: if writing fails

## Method: writeBELong
- parameter: `address`, type: `long`
- parameter: `v`, type: `long`

Description: Write a big\-endian 64\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 64\-bit value
throws: if writing fails

## Method: writeBEShort
- parameter: `address`, type: `long`
- parameter: `v`, type: `short`

Description: Write a big\-endian 16\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 16\-bit value
throws: if writing fails

## Method: writeByte
- parameter: `address`, type: `long`
- parameter: `v`, type: `byte`

Description: Write a byte.
parameter: address: address to write
parameter: v: byte value
throws: if writing fails

## Method: writeInt
- parameter: `address`, type: `long`
- parameter: `v`, type: `int`

Description: Write a 32\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial writes.
parameter: address: address to write
parameter: v: 32\-bit value
throws: if writing fails

## Method: writeInt
- parameter: `address`, type: `long`
- parameter: `v`, type: `int`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`

Description: Write a 32\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 32\-bit value
parameter: end: endianness
throws: if writing fails

## Method: writeLEInt
- parameter: `address`, type: `long`
- parameter: `v`, type: `int`

Description: Write a little\-endian 32\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 32\-bit value
throws: if writing fails

## Method: writeLELong
- parameter: `address`, type: `long`
- parameter: `v`, type: `long`

Description: Write a little\-endian 64\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 64\-bit value
throws: if writing fails

## Method: writeLEShort
- parameter: `address`, type: `long`
- parameter: `v`, type: `short`

Description: Write a little\-endian 16\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 16\-bit value
throws: if writing fails

## Method: writeLong
- parameter: `address`, type: `long`
- parameter: `v`, type: `long`

Description: Write a 64\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial writes.
parameter: address: address to write
parameter: v: 64\-bit value
throws: if writing fails

## Method: writeLong
- parameter: `address`, type: `long`
- parameter: `v`, type: `long`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`

Description: Write a 64\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 64\-bit value
parameter: end: endianness
throws: if writing fails

## Method: writePointer
- parameter: `address`, type: `long`
- parameter: `ptr`, type: `long`

Description: Write a pointer\-sized integer.
parameter: address: address to write
parameter: ptr: pointer value
throws: if writing fails

## Method: writeShort
- parameter: `address`, type: `long`
- parameter: `v`, type: `short`

Description: Write a 16\-bit integer using the [standard endianness](#getStandardEndianess()). This method does not do partial writes.
parameter: address: address to write
parameter: v: 16\-bit value
throws: if writing fails

## Method: writeShort
- parameter: `address`, type: `long`
- parameter: `v`, type: `short`
- parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness`

Description: Write a 16\-bit integer. This method does not do partial writes.
parameter: address: address to write
parameter: v: 16\-bit value
parameter: end: endianness
throws: if writing fails