smallworld.state.models¶
- class smallworld.state.models.Hook(address: int, function: Callable[[Emulator], None])¶
Hook a particular instruction with a function.
Runs the function provided when the emulator reaches (but has not yet executed) the instruction at a particular address.
- Parameters:
address – The address of the instruction.
function – The function to run.
- class smallworld.state.models.Breakpoint(address: int)¶
An interactive breakpoint.
Stops execution at the specified address and opens an interactive shell, as specified in the self.interact method.
- Parameters:
address – The address of the breakpoint.
- class smallworld.state.models.PDBBreakpoint(address: int)¶
A PDB interactive breakpoint.
- class smallworld.state.models.PythonShellBreakpoint(address: int)¶
A Python shell interactive breakpoint.
- class smallworld.state.models.Model(address: int)¶
A runtime function model implemented in Python.
If execution reaches the given address, call the function assigned to self.model, instead of any code at that address in the emulator, and return. This is most often used to model an external function, e.g., libc fread. It is the responsibility of the model to read arguments and generate reasonable return values.
Some models require static scratch space to operate. The quantity is stored in the ‘static_space_required’ attribute. If true, the harness must set the ‘static_buffer_address’ property of this model object. The model will take care of mapping a buffer of the appropriate size at that address.
A harness doesn’t need to include a Memory object for a static buffer. A harness can include such an object if it wants to initialize that memory with a specific value, or if it wants to inspect the contents of that buffer via Machine.extract()
- Parameters:
address – The address to model.
- abstract property name: str¶
A name for this model, e.g., fread or ioctl.
- classmethod lookup(name: str, platform: Platform, abi: ABI, address: int)¶
Instantiate a model by name, platform, and ABI.
- Parameters:
name – The name of the model.
platform – The platform for which this model is defined.
abi – The ABI according to which this model works.
address – The instruction address which the model will hook.
- Returns:
The fully instantiated model.
- apply(emulator: Emulator) None¶
Apply state to an emulator.
- Parameters:
emulator – The emulator to which state should applied.
- abstractmethod model(emulator: Emulator) None¶
This is the implementation of the model for the named function.
Note that implementation will have to make use of knowledge of the ABI to obtain arguments and return results, as well as modeling the semantics of the modeled functions appropriately.
- class smallworld.state.models.MemoryMappedModel(address: int, size: int)¶
A model of a memory-mapped IO device dealing with concrete values
This lets you specify alternate handler routines for reads and writes within a range of memory addressess, bypassing the emulator’s normal memory model. As the name suggests, this is useful for modeling MMIO devices, where accessing a particular address actually accesses a register of a peripheral device.
The callback routines on_read() and on_write() will trigger on any access within the specified range; one MemoryMappedModel can handle multiple registers, allowing you to model an entire device, or even a set of adjacent devices in one object.
- Parameters:
address – Starting address of the MMIO region
size – Size of the MMIO region in bytes
- abstractmethod on_read(emu: Emulator, addr: int, size: int, unused: bytes) bytes | None¶
Callback handling reads from an MMIO register
NOTE: Results must be encoded in the emulator’s byte order.
NOTE: Attempting to access memory in this MMIO range inside this handler will produce undefined behavior.
- Parameters:
emu – The emulator object mediating this operation
addr – The start address of the read operation
size – The number of bytes read
- Returns:
size bytes containing the result of the modeled read
- abstractmethod on_write(emu: Emulator, addr: int, size: int, value: bytes) None¶
Callback handling writes to an MMIO register
NOTE: value will be encoded in the emulator’s byte order.
NOTE: Attempting to access memory in this MMIO range inside this handler will produce undefined behavior.
- Parameters:
emu – The emulator object mediating this operation
addr – The start address of the write operation
size – The number of bytes written
value – The bytes written