Boneless Simulator Documentation¶

class boneless_sim.BonelessSimulator(start_pc=16, memsize=1024, io_callback=None)¶

The Boneless CPU instruction-level simulator object.

Instantiating this object will create a simulator context in which Boneless CPU code runs, one instruction at a time. A sample simulation session looks similar to the following:

from boneless_sim import *
from glasgow.arch.boneless.instr import *

cpu = BonelessSimulator(start_pc=0x10, memsize=65536)
program = assemble([MOVL(R0, 0xFF)])
cpu.load_program(program)

with cpu:
    cpu.stepi()

print(cpu.regs())

Parameters:

start_pc (int, optional) – The Program Counter register is set to this value when instantiating an object of this class.
memsize (int, optional) – Number of 16-bit words that the simulated CPU can access, starting from address zero. Accessing out-of-bounds memory will cause an exception.
io_callback (function) – Initial I/O callback to use. See register_io() for usage.

sim_active¶: bool – True if a simulation is in progress, False otherwise.

window¶: int – Offset of the register window into memory (Boneless CPU registers are just memory locations.)

pc¶: int – Current program counter pointer.

flags¶

dict – Current value of the flags register. Each dictionary entry is either 1 for True, or 0 for False. Valid keys are:

“Z” : Zero bit
“S” : Sign bit
“C” : Carry bit
“V” : OVerflow bit

mem¶: array – Contents of the primary address space seen by the simulated CPU. On object construction this is initialized to all zeroes.

io_callback¶: function – Reference to the current I/O callback function.

load_program(contents, start=16)¶

Inject program code into the memory space of the simulated CPU.

This function does not distinguish between loading program code and raw data. Program code can only be loaded using this function when a simulation is inactive.

Parameters:	contents (list of ints) – Integer representation of opcodes to load into the memory space of the simulated CPU. The `assemble` function from the `glasgow` package produces a list compatible with this input parameter. start (int) – 16-bit int offset representing the starting location in memory in which to load `contents`.

read_reg(reg)¶

Read the value of a single 16-bit register.

Parameters:	reg (int) – Register number to read. `R[0-8]` from the glasgow package is also acceptable.
Returns:	Current value of the queried register.
Return type:	int

reg_loc(offs)¶

Convenience function to return the address of a register in memory.

A register’s location changes when the CPU’s window is updated.

Parameters:	offs (int) – Register number to read. `R[0-8]` from the glasgow package is also acceptable.
Returns:	16-bit memory address of the queried register.
Return type:	int

register_io(callback)¶

Replace the currently-defined I/O callback with a new one.

The Simulated Boneless CPU needs a way to contact the outside world. The architecture itself defines a secondary address space for I/O, similar in idea to x86 port-mapped I/O. When the STX and LDX instructions are encountered, the provided callback will execute to simulate I/O. It is up to the user to decode the I/O address passed into the callback accordingly.

The I/O callback can only be replaced when a simulation is inactive.

Parameters:

callback (function) –

The callback function, using the following signature: fn(addr, data=None)

addr: 16-bit int

Virtual I/O address to read/write
data: 16-bit int` or None

If this I/O access is a read, data is None. Otherwise, data contains a value to write to a virtual I/O device.

The callback should return a 16-bit int if the I/O access was a read and None if the I/O access was a write (ignored by the simulator).

regs()¶

Return the 8 registers within the current register window.

Returns:	Array of 16-bit ints representing registers.
Return type:	array

set_pc(new_pc)¶

Set the program counter to a new value.

The program counter can only be updated using this function when a simulation is inactive.

Parameters:	new_pc (int) – 16-bit (treated as unsigned) to write to the PC register. If the value is out of range, a read to `mem` will throw an exception.

stepi()¶

Run a single instruction of the simulated CPU.

The state of the CPU will be available through the attributes of BonelessSimulator.

write_reg(reg, val)¶

Write the value of a single 16-bit register.

Registers can only be updated using this function when a simulation is inactive.

Parameters:	reg (int) – Register number to write. `R[0-8]` from the `glasgow` package is also acceptable. val (int) – 16-bit (treated as unsigned) to write to a register. If the value is out of range, the write to `mem` will throw an exception.

class boneless_sim.BonelessError(reason)¶

Exception raised when the CPU simulator doesn’t know what to do.

reason¶: str – Short message indicating why the simulator was unable to continue.