API

This section describes all the high level interface modules found in the bare68k package. The classes wrap the low-level machine interface and offer a object-oriented access with lots of convenience methods.

The Runtime

class bare68k.Runtime(cpu_cfg, mem_cfg, run_cfg, event_handler=None, log_channel=None)

The runtime controls the CPU emulation run and dispatches events.

The central entry point for every system emulation done with bare68k is the Runtime. First you configure it by passing in a CPU, memory layout and runtime configuration.

Add an optional event handler to control the processing of incoming events. Configure an optional Logger to receive all incoming traces.

Parameters:

• cpu_cfg (bare68k.CPUConfig) – the CPU configuration
• mem_cfg (bare68k.MemoryConfig) – the memory layout for the emulation
• run_cfg (bare68k.RunConfig) – runtime options
• event_handler (bare68k.EventHandler, optional) – event handler that receives all returned events from the CPU emulation. By default the bare68k.EventHandler is used.
• log_channel (logging.Logger, optional) – a logger that logs all runtime events. By default a logger with __name__ of the module is created.

get_cpu()

return cpu API ‘object’

get_cpu_cfg()

access the current CPU configuration

get_label_mgr()

Get the label manager associated with the runtime.

If labels are enabled a real LabelMgr is returned. If labels are disabled then a fake DummyLabelMgr is available. It provides the same interface but does nothing.

Returns:active label manager Return type:LabelMgr or DummyLabelMgr

get_mem()

return mem API ‘object’

get_mem_cfg()

access the current memory configuration

get_run_cfg()

access the current run configuration

get_with_labels()

Check is memory labels are enabled for the runtime.

The runtime can be either configured to enable or disable memory labels via the RunConfig. This function returns True if labels are enabled otherwise False.

Returns:True if labels are enabled, otherwise False Return type:bool

reset(init_pc, init_sp=2048)

reset the CPU

before you can run the CPU you have to reset it. This will write the initial SP and the initial PC to locations 0 and 4 in RAM and pulse a reset in the CPU emulation. After this operation you are free to overwrite these values again. Now proceed to call run().

run(reset_end_pc=None, start_pc=None, start_sp=None)

run the CPU until emulation ends

This is the main loop of your emulation. The CPU emulation is run and events are processed. The events are dispatched and the associated handlers are called. If a reset opcode is encountered then the execution is terminated.

Returns a RunInfo instance giving you timing information.

set_handler(event_type, handler)

set a custom handler for an event type and overwrite default handler

shutdown()

shutdown runtime

after using the runtime you have to shut it down. this frees the allocated resources. After that you can init() again for a new run

class bare68k.CPUConfig(cpu_type=1)

Configure the emulated CPU.

get_addr_bus_width()

get address bus width of selected CPU: either 24 or 32 bits

class bare68k.MemoryConfig(auto_align=False)

Configuration class for the memory layout of your m68k system

check(ram_at_zero=True, max_pages=256)

check if gurrent layout is valid

get_num_pages()

return the total number of pages required to handle the given layout

get_page_list_str()

return a string showing page allocation

get_range_list()

return the list of memory ranges currently allocated

class bare68k.RunConfig(catch_kb_intr=True, cycles_per_run=0, with_labels=True, pc_trace_size=8, instr_trace=False, cpu_mem_trace=False, api_mem_trace=False)

define the runtime configuration

class bare68k.EventHandler(logger=None, snap_create=None, snap_formatter=None, instr_logger=None, mem_logger=None)

define the event handling of the runtime

handle_aline_trap(event)

an unbound aline trap was encountered

handle_cb_error(event)

a callback running your code raised an exception

handle_instr_hook(event)

an instruction hook handler returned a value != None

handle_int_ack(event)

int ack handler did return a value != None

handle_mem_access(event)

default handler for invalid memory accesses

handle_mem_bounds(event)

default handler for invalid memory accesses beyond max pages

handle_mem_special(event)

a memory special handler returned a value != None

handle_mem_trace(event)

a cpu mem trace handler returned a value != None

handle_reset(event)

default handler for reset opcode