smallworld.state.memory.heap

class smallworld.state.memory.heap.Heap(address: int, size: int, *args, **kwargs)

A heap-like memory region, with convenient operations like allocate and free.

abstractmethod allocate(value: Value) → int

Allocate space for and write a value to the heap.

Parameters:

value – The value to go on the heap.

Returns:

The address at which the value was allocated.

abstractmethod free(address: int) → None

Free space on the heap for previously allocated data.

Arguements:

address: The start address of the previously allocated data.

allocate_integer(integer: int, size: int, label: str, byteorder: Byteorder) → int

Allocate space for and write an integer to the heap.

Parameters:

  • integer – The integer to go on the heap.

  • size – The number of bytes to allocate to the integer.

  • label – The label to give to the allocated region containing the integer.

Returns:

The address at which the integer was allocated.

allocate_bytes(content: bytes | bytearray, label: str | None) → int

Allocate space for and write bytes to the heap.

Parameters:

  • content – The bytes to go on the heap.

  • label – The label to give to the bytes on the heap.

Returns:

The address at which the integer was allocated.

allocate_ctype(content: CTypesAny, label: str) → int

Allocate space for and write structured bytes to the heap.

Arguements:

content: The ctypes-structured data to go on the heap. label: The label to give to the data bytes on the heap.

Returns:

The address at which the structured data was allocated.

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

get_capacity() → int

Gets the total number of bytes this memory region can store. :returns: The total number of bytes this memory region can store.

get_used() → int

Gets the number of bytes written to this memory region.

Returns:

The number of bytes written to this memory region.

read_bytes(address: int, size: int) → bytes

Read part of this memory region. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The number of bytes to read.

Returns:

The bytes in the requested memory region.

read_int(address: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → int

Read and interpret as an integer. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

Returns:

The integer read from memory.

to_bytes() → bytes

Convert this memory region into a byte string.

Missing/undefined space will be filled with zeros.

Parameters:

byteorder – Byteorder for conversion to raw bytes.

Returns:

Bytes for this object with the given byteorder.

write_bytes(address: int, data: bytes) → None

Overwrite part of this memory region with specific bytes. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • data – The bytes to write.

write_int(address: int, value: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → None

Write an integer to memory. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • value – The integer value to write.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

address: int

The start address of this memory region.

size: int

The size address of this memory region.

class smallworld.state.memory.heap.BumpAllocator(address: int, size: int, *args, **kwargs)

A simple bump allocator heap.

allocate(value: Value) → int

Allocate space for and write a value to the heap.

Parameters:

value – The value to go on the heap.

Returns:

The address at which the value was allocated.

free(address: int) → None

Free space on the heap for previously allocated data.

Arguements:

address: The start address of the previously allocated data.

allocate_bytes(content: bytes | bytearray, label: str | None) → int

Allocate space for and write bytes to the heap.

Parameters:

  • content – The bytes to go on the heap.

  • label – The label to give to the bytes on the heap.

Returns:

The address at which the integer was allocated.

allocate_ctype(content: CTypesAny, label: str) → int

Allocate space for and write structured bytes to the heap.

Arguements:

content: The ctypes-structured data to go on the heap. label: The label to give to the data bytes on the heap.

Returns:

The address at which the structured data was allocated.

allocate_integer(integer: int, size: int, label: str, byteorder: Byteorder) → int

Allocate space for and write an integer to the heap.

Parameters:

  • integer – The integer to go on the heap.

  • size – The number of bytes to allocate to the integer.

  • label – The label to give to the allocated region containing the integer.

Returns:

The address at which the integer was allocated.

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

get_capacity() → int

Gets the total number of bytes this memory region can store. :returns: The total number of bytes this memory region can store.

get_used() → int

Gets the number of bytes written to this memory region.

Returns:

The number of bytes written to this memory region.

read_bytes(address: int, size: int) → bytes

Read part of this memory region. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The number of bytes to read.

Returns:

The bytes in the requested memory region.

read_int(address: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → int

Read and interpret as an integer. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

Returns:

The integer read from memory.

to_bytes() → bytes

Convert this memory region into a byte string.

Missing/undefined space will be filled with zeros.

Parameters:

byteorder – Byteorder for conversion to raw bytes.

Returns:

Bytes for this object with the given byteorder.

write_bytes(address: int, data: bytes) → None

Overwrite part of this memory region with specific bytes. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • data – The bytes to write.

write_int(address: int, value: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → None

Write an integer to memory. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • value – The integer value to write.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

address: int

The start address of this memory region.

size: int

The size address of this memory region.

class smallworld.state.memory.heap.CheckedBumpAllocator(address: int, size: int, guard_bytes: int, *args, **kwargs)

A simple bump allocator heap that uses a shadow memory to check reads and write. It will also check for UAF bugs.

get_used() → int

Gets the number of bytes written to this memory region.

Returns:

The number of bytes written to this memory region.

allocate(value: Value) → int

Allocate space for and write a value to the heap.

Parameters:

value – The value to go on the heap.

Returns:

The address at which the value was allocated.

free(address: int) → None

Free space on the heap for previously allocated data.

Arguements:

address: The start address of the previously allocated data.

apply(emulator: Any) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

allocate_bytes(content: bytes | bytearray, label: str | None) → int

Allocate space for and write bytes to the heap.

Parameters:

  • content – The bytes to go on the heap.

  • label – The label to give to the bytes on the heap.

Returns:

The address at which the integer was allocated.

allocate_ctype(content: CTypesAny, label: str) → int

Allocate space for and write structured bytes to the heap.

Arguements:

content: The ctypes-structured data to go on the heap. label: The label to give to the data bytes on the heap.

Returns:

The address at which the structured data was allocated.

allocate_integer(integer: int, size: int, label: str, byteorder: Byteorder) → int

Allocate space for and write an integer to the heap.

Parameters:

  • integer – The integer to go on the heap.

  • size – The number of bytes to allocate to the integer.

  • label – The label to give to the allocated region containing the integer.

Returns:

The address at which the integer was allocated.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

get_capacity() → int

Gets the total number of bytes this memory region can store. :returns: The total number of bytes this memory region can store.

read_bytes(address: int, size: int) → bytes

Read part of this memory region. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The number of bytes to read.

Returns:

The bytes in the requested memory region.

read_int(address: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → int

Read and interpret as an integer. This will fail if any sub-region of the memory requested is symbolic or uninitialized.

Parameters:

  • address – The address to read from.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

Returns:

The integer read from memory.

to_bytes() → bytes

Convert this memory region into a byte string.

Missing/undefined space will be filled with zeros.

Parameters:

byteorder – Byteorder for conversion to raw bytes.

Returns:

Bytes for this object with the given byteorder.

write_bytes(address: int, data: bytes) → None

Overwrite part of this memory region with specific bytes. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • data – The bytes to write.

write_int(address: int, value: int, size: Literal[1, 2, 4, 8], byteorder: Byteorder) → None

Write an integer to memory. This will fail if any sub-region of the existing memory is symbolic.

Parameters:

  • address – The address to write to.

  • value – The integer value to write.

  • size – The size of the integer in bytes.

  • endianness – The byteorder of the platform.

address: int

The start address of this memory region.

size: int

The size address of this memory region.