ducky.cpu package

Subpackages

• ducky.cpu.coprocessor package
  • Submodules
    • ducky.cpu.coprocessor.control module
    • ducky.cpu.coprocessor.math_copro module
  • Module contents

Submodules

• ducky.cpu.instructions module
• ducky.cpu.registers module

Module contents

class ducky.cpu.CPU(machine, cpuid, memory_controller, cores=1)

Bases: ducky.interfaces.ISnapshotable, ducky.interfaces.IMachineWorker

boot()

die(exc)

halt()

load_state(state)

on_core_alive(core)

Triggered when one of cores goes alive.

on_core_halted(core)

Signal CPU that one of cores is no longer alive.

on_core_running(core)

Signal CPU that one of cores is now running.

on_core_suspended(core)

Signal CPU that one of cores is now suspended.

save_state(parent)

suspend()

wake_up()

class ducky.cpu.CPUCore(coreid, cpu, memory_controller)

Bases: ducky.interfaces.ISnapshotable, ducky.interfaces.IMachineWorker

This class represents the main workhorse, one of CPU cores. Reads instructions, executes them, has registers, caches, handles interrupts, ...

Parameters:

• coreid (int) – id of this core. Usually, it’s its serial number but it has no special meaning.
• cpu (ducky.cpu.CPU) – CPU that owns this core.
• memory_controller (ducky.mm.MemoryController) – use this controller to access main memory.

FP()

IP()

REG(reg)

SP()

_CPUCore__get_flags()

_CPUCore__set_flags(flags)

_enter_exception(index, *args)

Prepare CPU for handling exception routine. CPU core loads new IP and SP from proper entry of EVT. Old SP and FLAGS are saved on the exception stack, and new call frame is created. Privileged mode flag is set, hardware interrupt flag is cleared.

Then, if exception provides its routine with some arguments, these arguments are pushed on the stack.

Exception stack layout then looks like this (original stack is left untouched):

+---------+ <= EVT SP
|   SP    |
+---------+
|  FLAGS  |
+---------+
|   IP    |
+---------+
|   FP    |
+---------+ <= FP
|   arg1  |
+---------+
|   ...   |
+---------+
|   argN  |
+---------+ <= SP
|   ...   |
+---------+

Parameters:

• index (int) – exception ID - EVT index.
• args (u32_t) – if present, these values will be pushed onto the stack.

_exit_exception()

Restore CPU state after running an exception routine. Call frame is destroyed, registers are restored. Clearing routine arguments is responsibility of the routine.

_get_instruction_set()

_handle_exception(exc, index, *args)

This method provides CPU exception classes with a simple recipe on how to deal with the exception:

• tell processor to start exception dance,
• if the exception is raised again, tell processor to plan double fault routine,
• and if yet another exception is raised, halt the core.

_handle_python_exception(exc)

_raw_pop()

Pop value from stack. 4 byte number is read from address in SP, then SP is incremented by four.

Returns:popped value Return type:u32

_raw_push(val)

Push value on stack. SP is decremented by four, and value is written at this new address.

Parameters:val (u32) – value to be pushed

_set_instruction_set(instr_set)

boot()

change_runnable_state(alive=None, running=None, idle=None)

check_protected_ins()

Raise AccessViolationError if core is not running in privileged mode.

This method should be used by instruction handlers that require privileged mode, e.g. protected instructions.

Raises:ducky.errors.PrivilegedInstructionError – if the core is not in privileged mode

create_frame()

Creates new call stack frame, by performing the following operations:

• push IP
• push FP
• set FP to SP (i.e. SP before this method + 2 pushes)

Stack layout then looks like this:

+---------+
|   IPx   |
+---------+
|   FPx   |
+---------+ <= FPy
|   ...   |
+---------+ <= original SP
|   IPy   |
+---------+
|   FPy   |
+---------+ <= SP, FP
|   ...   |
+---------+

FP then points to the newly created frame, to the saved FP in particular, and this saved FP points to its predecesor, thus forming a chain.

destroy_frame()

Destroys current call stack frame by popping values from the stack, reversing the list of operations performed by ducky.cpu.CPUCore.create_frame():

• pop FP
• pop IP

After this, FP points to the frame from which the instruction that created the currently destroyed frame was executed, and restored IP points to the next instruction.

Raises:InvalidFrameError – if frame checking is enabled, current SP is compared with saved FP to see, if the stack was clean before leaving the frame. This error indicated there is some value left on stack when ret or retint were executed. Usually, this signals missing pop to complement one of previous ``push``es.

die(exc)

do_step(ip, regset)

flags

halt()

has_coprocessor(name)

init_debug_set()

instruction_set

irq(index)

This is a wrapper for _enter_exception, for device drivers to call when hardware interrupt arrives.

Parameters:index (int) – exception ID - EVT index

load_state(state)

pop(*regs)

pop_flags()

pop_frame()

push(*regs)

push_flags()

reset(new_ip=0)

Reset core’s state. All registers are set to zero, all flags are set to zero, except HWINT flag which is set to one, and IP is set to requested value.

Parameters:new_ip (u32_t) – new IP value, defaults to zero

run()

save_state(parent)

step()

Perform one “step” - fetch next instruction, increment IP, and execute instruction’s code (see inst_* methods)

suspend()

wake_up()

class ducky.cpu.CPUCoreState

Bases: ducky.snapshot.SnapshotNode

class ducky.cpu.CPUState(*fields)

Bases: ducky.snapshot.SnapshotNode

get_core_state_by_id(coreid)

get_core_states()

class ducky.cpu.CoreFlags

Bases: ducky.util.Flags

_flags = ['privileged', 'hwint_allowed', 'equal', 'zero', 'overflow', 'sign']

_labels = 'PHEZOS'

ducky.cpu.DEFAULT_CORE_INST_CACHE_SIZE = 256

Default size of core instruction cache, in instructions.

ducky.cpu.DEFAULT_EVT_ADDRESS = 0

Default EVT address

ducky.cpu.DEFAULT_PT_ADDRESS = 65536

Default PT address

class ducky.cpu.InstructionCache_Base(mmu, *args, **kwargs)

Bases: ducky.util.LoggingCapable, dict

Simple instruction cache class, based on a dictionary, with a limited size.

Parameters:core (ducky.cpu.CPUCore) – CPU core that owns this cache.

class ducky.cpu.InstructionCache_Full(mmu, *args, **kwargs)

Bases: ducky.util.LoggingCapable, list

Simple instruction cache class, based on a list, with unlimited size.

Parameters:core (ducky.cpu.CPUCore) – CPU core that owns this cache.

clear()

class ducky.cpu.InterruptVector(ip=0, sp=0)

Bases: object

Interrupt vector table entry.

SIZE = 8

static load(core, addr)

class ducky.cpu.MMU(core, memory_controller)

Bases: ducky.interfaces.ISnapshotable

Memory management unit (aka MMU) provides a single point handling all core’s memory operations. All memory reads and writes must go through this unit, which is then responsible for all translations, access control, and caching.

Parameters:

• core (ducky.cpu.CPUCore) – parent core.
• memory_controller (ducky.mm.MemoryController) – memory controller that provides access to the main memory.
• memory.force-aligned-access (bool) – if set, MMU will disallow unaligned reads and writes. False by default.
• cpu.pt-address (int) – base address of page table. ducky.cpu.DEFAULT_PT_ADDRESS by default.
• cpu.pt-enabled (bool) – if set, CPU core will start with page table enabled. False by default.

_check_access(access, addr, align=None)

Check attempted access against several criteria:

• PT is enabled - disabled PT implies different set of read/write methods that don’t use this method to check access
• access alignment if correct alignment is required
• privileged access implies granted access
• corresponding PTE settings

Parameters:

• access – read, write or execute.
• addr (int) – memory address.
• align (int) – if set, operation is expected to be aligned to this boundary.

Raises:

• ducky.errors.UnalignedAccessError – when unaligned access is not allowed, but requested.
• ducky.errors.MemoryAccessError – when access is denied.

_debug_wrapper_read(reader, *args, **kwargs)

_debug_wrapper_write(writer, *args, **kwargs)

_fetch_instr(addr)

Read instruction from memory. This method is responsible for the real job of fetching instructions and filling the cache.

Parameters:addr (u24) – absolute address to read from Returns:instruction Return type:InstBinaryFormat_Master

_fetch_instr_jit(addr)

Read instruction from memory. This method is responsible for the real job of fetching instructions and filling the cache.

Parameters:addr (u24) – absolute address to read from Returns:instruction Return type:InstBinaryFormat_Master

_get_pg_ops_dict(address)

_get_pg_ops_list(address)

_get_pt_enabled()

_get_pte(addr)

Find out PTE for particular physical address. If PTE is not in internal PTE cache, it is fetched from PTE table.

Parameters:addr (int) – memory address.

_nopt_read_u16(addr)

_nopt_read_u32(addr, not_execute=True)

_nopt_read_u8(addr)

_nopt_write_u16(addr, value)

_nopt_write_u32(addr, value)

_nopt_write_u8(addr, value)

_pt_read_u16(addr)

_pt_read_u32(addr, not_execute=True)

_pt_read_u8(addr)

_pt_write_u16(addr, value)

_pt_write_u32(addr, value)

_pt_write_u8(addr, value)

_set_access_methods()

Set parent core’s memory-access methods to proper shortcuts. Methods named MEM_{IN,OUT}{8,16,32} will be set to corresponding MMU methods.

_set_pt_enabled(value)

halt()

pt_enabled

release_ptes()

Clear internal PTE cache.

reset()

Reset MMU. PT will be disabled, and all internal caches will be flushed.

class ducky.cpu.StackFrame(sp, ip)

Bases: object

ducky.cpu.do_log_cpu_core_state(core, logger=None, disassemble=True, inst_set=None)

Log state of a CPU core. Content of its registers, and other interesting or useful internal variables are logged.

Parameters:

• core (ducky.cpu.CPUCore) – core whose state should be logged.
• logger – called for each line of output to actualy log it. By default, core’s ducky.cpu.CPUCore.DEBUG() method is used.

ducky.cpu.log_cpu_core_state(*args, **kwargs)

This is a wrapper for ducky.cpu.do_log_cpu_core_state function. Its main purpose is to be removed when debug mode is not set, therefore all debug calls of ducky.cpu.do_log_cpu_core_state will disappear from code, making such code effectively “quiet”.