iotile.core.hw.debug

A suite of common debug routines.

Package Contents

class SparseMemory

A sparse memory map for debugging purposes

You can add memory segments into the memory map a little bit at a time and decode any section into a python object using registered decoder functions.

add_segment(self, address, data, overwrite=False)

Add a contiguous segment of data to this memory map

If the segment overlaps with a segment already added , an ArgumentError is raised unless the overwrite flag is True.

Params:

address (int): The starting address for this segment data (bytearray): The data to add overwrite (bool): Overwrite data if this segment overlaps

with one previously added.
_create_slice(self, key)

Create a slice in a memory segment corresponding to a key.

__getitem__(self, key)
__setitem__(self, key, item)
classmethod _in_segment(cls, address, segment)
_find_address(self, address)
_classify_segment(self, address, length)

Determine how a new data segment fits into our existing world

Params:
address (int): The address we wish to classify length (int): The length of the segment
Returns:
int: One of SparseMemoryMap.prepended
classmethod _iter_groups(cls, data, chunk_length)
classmethod _format_line(cls, start_address, data)
__str__(self)

Convert to string as a 64 byte wide hex dump

class DebugManager(stream)

Low level debug operations for development and recovery.

Args:
stream (CMDStream): A CMDStream subclass that supports
debug operations on which enable_debug() has already been called.
dump_ram(self, out_path, pause=False)

Dump all RAM to a binary file.

Args:
out_path (path): The output path at which to save
the binary core dump. This core dump consists of the current contents of RAM for the device.
pause (bool): Optional parameter to halt chip operation
while performing the core dump. Defaults to False, which could cause rapidly changing RAM values to be in an inconsistent state, but it noninvasive and will not interrupt any device activity.
save_snapshot(self, out_path)

Save the current state of an emulated device.

This debug routine is only supported for emulated devices that have a concept of taking a snapshot of their internal state.

For those devices this will produce a snapshot file that can be used in a later call to load_snapshot() in order to reload the exact same state.

Args:
out_path (path): The output path at which to save
the binary core dump. This core dump consists of the current contents of RAM for the device.
load_snapshot(self, in_path)

Load the current state of an emulated device.

This debug routine is only supported for emulated devices that have a concept of restoring a snapshot of their internal state.

For those devices this method takes a path to a previously produced snapshot file from a call to save_snapshot() and will load that snapshot into the currently emulated device.

Args:
in_path (path): The output path at which to save
the binary core dump. This core dump consists of the current contents of RAM for the device.
dump_snapshot(self)

Get the current state of the emulated device.

This debug routine is only supported for emulated devices that have a concept of taking a snapshot of their internal state.

For those devices this will return a snapshot dictionary with the entire internal state of the device.

Returns:
dict: The internal snapshot of the device’s current state.
restore_snapshot(self, snapshot)

Restore a previous state snapshot from an emulated device.

Args:
snapshot (dict): A snapshot of the internal state of this
device previously obtained by calling dump_snapshot()
open_scenario(self, scenario_path)

Load a test scenario from a file into an emulated device.

This debug routine is only supported for emulated devices and will cause the connected device to load one of its preconfigured test scenarios. If the scenario has arguments, the args dict may be passed to configure it.

Args:
scenario_path (str): The path to a file containing the test
scenario details.
load_scenario(self, scenario_data)

Load the given test scenario onto an emulated device.

This debug routine is only supported for emulated devices and will cause the connected device to load one of its preconfigured test scenarios. If the scenario has arguments, the args dict may be passed to configure it.

Args:
scenario_data (list or dict): Either a dict describing the scenario
to be loaded or a list of such dicts that will all be loaded.
track_changes(self, enabled=True)

Start or stop tracking all internal state changes made to an emulated device.

This debug routine is only supported for emulated devices and will causes the device to create an internal log of all state changes.

This log can be dumped to a file by calling save_change(output_path).

Args:
enabled (bool): Whether we should enable (default) or disable tracking
changes.
save_changes(self, out_path)

Save all tracked changes made to an emulated device.

This debug routine is only supported for emulated devices and will causes the device to save all internal state changes since track_changes was called.

Args:
out_path (str): The output path where the change log should be saved.
flash(self, in_path, file_format=None)

Flash a new firmware image to the attached chip.

This flashing takes place over a debug interface and does not require a working bootloader. In particular, this routine is suitable for initial board bring-up of a blank MCU.

If an explicit format is not passed the following rules are used to infer the format based on its file extension.

elf: ELF file hex: intel hex file bin: raw binary file assumed to start at address 0

Args:
in_path (path): The path to the input firmware image that we wish
to flash.
file_format (str): Optional explicit format to use to parse the
input file. If this is None, the format is automatically inferred from the file suffix. If given explicitly, you should pass ‘elf’, ‘hex’ or ‘bin’.
classmethod _process_hex(cls, in_path)

This function returns a list of base addresses and a list of the binary data for each segment.

classmethod _process_elf(cls, in_path)