smallworld.state.memory

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

A memory region.

A memory maps integer offsets (implicitly from the base address) to Value objects.

address: int

The start address of this memory region.

size: int

The size address of this memory region.

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.

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.

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

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.

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.

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.

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.

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

classmethod from_bytes(bytes: bytes, address: int)

Load from a byte array.

Parameters:

• bytes – The bytes of the memory.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory contstructed from the given bytes.

classmethod from_file(file: BinaryIO, address: int, label: str | None = None)

Load from an open file-like object.

Parameters:

• file – The open file-like object from which to load data.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory from the given file-like object.

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

classmethod from_filepath(path: str, address: int)

Load from a file.

Parameters:

• path – The path to the file.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory parsed from the given file path.

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.ElfExecutable(file: BinaryIO, platform: Platform | None = None, ignore_platform: bool = False, user_base: int | None = None, page_size: int = 4096)

Executable loaded from an ELF

This loads a single ELF file into a SmallWorld memory object. It performs no relocation or any other initialization, just maps the file into memory as the kernel intended.

Parameters:

• file – File-like object containing the image

• platform – Optional platform; used for header verification

• ignore_platform – Do not try to ID or verify platform from headers

• user_base – Optional user-specified base address

• page_size – System page size

size: int

The size address of this memory region.

entrypoint: int | None = None

Entry point address.

Note

This is not used by Emulators - but is available for reference from file parsing, if supported.

get_symbol_value(name: str | int, dynamic: bool = False, rebase: bool = True) → int

Get the value for a symbol

The value of a symbol is usually an address or offset, although the precise meaning can vary a little.

Parameters:

• name – The name of the symbol, or its index into the symbol table

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

Returns:

The integer value of this symbol

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

classmethod from_bndb(path: str, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an executable from a Binary Ninja database (.bndb) or any file that Binary Ninja can open.

Parameters:

• path – Filesystem path to a .bndb file (or raw binary / ELF / PE / Mach-O / etc.).

• address – Optional base address override. When None the base recorded in the BinaryView is used.

• platform – Optional platform; when given the detected platform is verified against it.

• ignore_platform – Skip platform identification and verification.

Returns:

An Executable parsed from the given Binary Ninja database.

classmethod from_bytes(bytes: bytes, address: int)

Load from a byte array.

Parameters:

• bytes – The bytes of the memory.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory contstructed from the given bytes.

classmethod from_elf(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False, page_size: int = 4096)

Load an ELF executable from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this executable should be loaded.

• platform – Optional platform for header verification

• ignore_platform – Skip platform ID and verification

• page_size – Page size in bytes

Returns:

An Executable parsed from the given ELF file-like object.

classmethod from_elf_core(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an ELF core dump (ET_CORE) from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this core dump should be loaded.

• platform – Optional platform for header verification

• ignore_platform – Skip platform ID and verification

Returns:

An Executable (specifically ElfCoreFile) parsed from the given core dump.

classmethod from_file(file: BinaryIO, address: int, label: str | None = None)

Load from an open file-like object.

Parameters:

• file – The open file-like object from which to load data.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory from the given file-like object.

classmethod from_filepath(path: str, address: int)

Load from a file.

Parameters:

• path – The path to the file.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory parsed from the given file path.

classmethod from_pe(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an PE executable from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this executable should be loaded.

Returns:

An Executable parsed from the given PE file-like object.

classmethod from_vxworks(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load a VXWorks executable from a firmware capture. :param file: The open file-like object from which to read. :param address: The address where this executable should be loaded.

Returns:

An Executable parsed from the given VXWorks image.

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_symbol_size(name: str | int, dynamic: bool = False)

Get the size for a symbol

If a symbol references a function or a data structure, this will hold its size in bytes

Parameters:

• name – The name of the symbol, or its index into the symbol table

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

Returns:

The size of this symbol

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.

update_symbol_value(name: str | int | ElfSymbol, value: int, dynamic: bool = False, rebase: bool = True) → None

Update the value of a symbol

This will alter the value of the symbol, and also propagate that updated value according to any associated relocations.

Parameters:

• name – The name of the symbol, its index into the symbol table, or a specific symbol object

• value – The new value for the symbol

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

link_elf(elf: ElfExecutable, dynamic: bool = True, all_syms: bool = False) → None

Link one ELF against another

This roughly mimics the ELF linker; it looks for undefined symbols in the current file, and tries to populate their values from matching defined symbols from another file.

Parameters:

• elf – The ELF from which to draw symbol values

• dynamic – Whether to link static or dynamic symbols

• all_syms – Whether to override defined symbols

class smallworld.state.memory.ElfCoreFile(file: BinaryIO, platform: Platform | None = None, ignore_platform: bool = False, user_base: int | None = None, page_size: int = 4096)

Extended loader to handle core-dump (ET_CORE) ELF files.

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

entrypoint: int | None = None

Entry point address.

Note

This is not used by Emulators - but is available for reference from file parsing, if supported.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

classmethod from_bndb(path: str, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an executable from a Binary Ninja database (.bndb) or any file that Binary Ninja can open.

Parameters:

• path – Filesystem path to a .bndb file (or raw binary / ELF / PE / Mach-O / etc.).

• address – Optional base address override. When None the base recorded in the BinaryView is used.

• platform – Optional platform; when given the detected platform is verified against it.

• ignore_platform – Skip platform identification and verification.

Returns:

An Executable parsed from the given Binary Ninja database.

classmethod from_bytes(bytes: bytes, address: int)

Load from a byte array.

Parameters:

• bytes – The bytes of the memory.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory contstructed from the given bytes.

classmethod from_elf(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False, page_size: int = 4096)

Load an ELF executable from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this executable should be loaded.

• platform – Optional platform for header verification

• ignore_platform – Skip platform ID and verification

• page_size – Page size in bytes

Returns:

An Executable parsed from the given ELF file-like object.

classmethod from_elf_core(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an ELF core dump (ET_CORE) from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this core dump should be loaded.

• platform – Optional platform for header verification

• ignore_platform – Skip platform ID and verification

Returns:

An Executable (specifically ElfCoreFile) parsed from the given core dump.

classmethod from_file(file: BinaryIO, address: int, label: str | None = None)

Load from an open file-like object.

Parameters:

• file – The open file-like object from which to load data.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory from the given file-like object.

classmethod from_filepath(path: str, address: int)

Load from a file.

Parameters:

• path – The path to the file.

• address – The address where this memory should be loaded into an emulator’s memory.

Returns:

A RawMemory parsed from the given file path.

classmethod from_pe(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load an PE executable from an open file-like object.

Parameters:

• file – The open file-like object from which to read.

• address – The address where this executable should be loaded.

Returns:

An Executable parsed from the given PE file-like object.

classmethod from_vxworks(file: BinaryIO, address: int | None = None, platform: Platform | None = None, ignore_platform: bool = False)

Load a VXWorks executable from a firmware capture. :param file: The open file-like object from which to read. :param address: The address where this executable should be loaded.

Returns:

An Executable parsed from the given VXWorks image.

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_symbol_size(name: str | int, dynamic: bool = False)

Get the size for a symbol

If a symbol references a function or a data structure, this will hold its size in bytes

Parameters:

• name – The name of the symbol, or its index into the symbol table

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

Returns:

The size of this symbol

get_symbol_value(name: str | int, dynamic: bool = False, rebase: bool = True) → int

Get the value for a symbol

The value of a symbol is usually an address or offset, although the precise meaning can vary a little.

Parameters:

• name – The name of the symbol, or its index into the symbol table

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

Returns:

The integer value of this symbol

get_used() → int

Gets the number of bytes written to this memory region.

Returns:

The number of bytes written to this memory region.

link_elf(elf: ElfExecutable, dynamic: bool = True, all_syms: bool = False) → None

Link one ELF against another

This roughly mimics the ELF linker; it looks for undefined symbols in the current file, and tries to populate their values from matching defined symbols from another file.

Parameters:

• elf – The ELF from which to draw symbol values

• dynamic – Whether to link static or dynamic symbols

• all_syms – Whether to override defined symbols

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.

update_symbol_value(name: str | int | ElfSymbol, value: int, dynamic: bool = False, rebase: bool = True) → None

Update the value of a symbol

This will alter the value of the symbol, and also propagate that updated value according to any associated relocations.

Parameters:

• name – The name of the symbol, its index into the symbol table, or a specific symbol object

• value – The new value for the symbol

• dynamic – If specified by index, whether to look in the static or dynamic symbol table

• rebase – Whether the recorded value is relative to the base address of this ELF.

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.