# 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`

## 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`

## 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`

## 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: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
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: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
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: 

## 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: 
parameter: protection: 
throws: 

## 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: 
parameter: size: 
throws: 

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

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

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

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

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

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

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

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

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

## 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: 
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: 
parameter: size: 
parameter: dst: 
parameter: dstOffset: 
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: 
parameter: size: 
parameter: dst: 
parameter: dstOffset: 
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: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
return: 
throws: 

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

Description: Convenience method. Read a byte.
parameter: address: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
parameter: end: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
parameter: end: 
return: 
throws: 

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

Description: 
parameter: address: 
return: 
throws: 

## 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: 
return: 
throws: 

## 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: 
parameter: end: 
return: 
throws: 

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
throws: if the implementation does not support that feature

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

Description: 
parameter: listener: 
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: 

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

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

## 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: 
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: 
parameter: size: 
parameter: src: 
parameter: srcOffset: 
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: 
parameter: size: 
parameter: src: 
parameter: srcOffset: 
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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

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

Description: Write a byte.
parameter: address: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
parameter: end: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
parameter: end: 
throws: 

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

Description: 
parameter: address: 
parameter: ptr: 
throws: 

## 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: 
parameter: v: 
throws: 

## 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: 
parameter: v: 
parameter: end: 
throws: 

