depthcharge

The “top-level” of the Depthcharge’s target interaction API is implemented by the Depthcharge class. This encapsulates all underlying state and exposes wrappers to functionality implemented by the various submodules. An instance of Depthcharge effectively represents a “context handle”. One will perform most, if not all, actions on a target using this handle and should prefer its use over direct instantiation and interaction with the lower-level classes. (There will be exceptions; this is just best practice guidance offered to encourage portability and compatibility over any API updates.)

In the simplest case, creating a handle consists of two steps:

Attaching to the target console by creating a Console instance.
Creating a Depthcharge context, passing the Console instance as an argument.

The creation of the Depthcharge context results in an initial inspection of the target device so that Depthcharge can determine what functionality is available. If any inspection operations require deployment of executable payloads (and any necessary memory write operations are detected) these payload will be deployed to memory at this time. Otherwise, payloads will be deployed on an as-needed basis when Depthcharge methods are invoked.

A boilerplate example is shown below:

#!/usr/bin/env python3
import traceback
from depthcharge import Console, Depthcharge, log

ctx = None

try:
    console = Console('/dev/ttyUSB0', baudrate=115200)
    ctx = Depthcharge(console, arch='arm')

    # Comment out the above ctx creation and uncomment the following one in
    # order to possibly make more operations available to Depthcharge by allowing
    # it to deploy executable payloads to RAM and reboot/crash the platform.
    #ctx = Depthcharge(console, allow_deploy=True, allow_reboot=True)

    # Perform actions here via API calls on ctx handle

except Exception as error:
    log.error(str(error))

    # Shown if DEPTHCHARGE_LOG_LEVEL=debug in environment
    log.debug(traceback.format_exc())

finally:
    # Save gathered information to a device configuration file
    if ctx:
        ctx.save('my_device.cfg')

Observe that the Depthcharge.save() method is used to save information collected in the context object to a “device configuration file”. This is a JSON-formatted file that can be used to later create a Depthcharge object using the static Depthcharge.load() method. This results in a much quicker object creation, given that device inspection is not needed to initialize the context state. Below is an example usage of Depthcharge.load().

console = Console('/dev/ttyUSB0', baudrate=115200)
ctx = Depthcharge.load('my_device.cfg', console)

With a context object in hand, one can being interacting with a target device using the API methods documented here. Refer to both the scripts present in Depthcharge’s python/examples directory, as well as the implementation of its various utility scripts for some additional examples.

Context creation involving the use of a Companion device or a console monitor (via depthcharge.monitor) is discussed in their respective modules and classes.

As a final note, the Depthcharge API makes a fairly heavy usage of keyword arguments (**kwargs). These are propagated downward these from top-level calls to lower level implementations. While this isn’t a great design practice for most software projects, this decision was made to better facilitate the use of Depthcharge as “a tool for quickly building your own tools.” The intent is to allow API users to pass parameters (whether programmatically or as obtained from command-line arguments) to underlying operations in order to tweak behavior without much effort.

This is exemplified by the depthcharge-stratagem script providing the -X, --extra command-line parameter, which allows the user to tweak the values of the revlut_maxlen parameter of the ReverseCRC32Hunter constructor and the max_iterations parameter of ReverseCRC32Hunter.build_stratagem(). Thus, familiarity with other parts of the Depthcharge API documentation is still very helpful, even if you’re only using provided scripts.

Console

class depthcharge.Console(device='/dev/ttyUSB0:115200', prompt=None, monitor=None, **kwargs)

This class encapsulates a serial console interface and provides higher level functionality for interacting with a U-Boot console.

The device argument are required to configure the serial console connection. Default, but not necessarily correct, values will be used if these are not provided. Note that the baudrate can either be specified as part of the device string or as an additional baudrate=<value> keyword argument.

The prompt parameter specifies the U-Boot prompt string that should be used to detect when the interactive console is ready to accept input. If left as None, Depthcharge will attempt to later determine this using the discover_prompt() method.

If you wish to view or capture data sent and received using this console, provide a Monitor instance as the monitor parameter.

By default, the underlying serial console is initialized with a 150 ms timeout. Lowering this will speed up some operations (e.g. dumping memory via console operations), but setting it too low might cause Depthcharge to time out before a device has had a chance to finish responding with output from an operation.

The timeout be changed by providing a float value (in seconds) as a timeout keyword argument or by setting a DEPTHCHARGE_CONSOLE_TIMEOUT environment variable. The latter takes precedence.

On some systems, you may find that sending too much data at a U-Boot console will cause the target device’s UART FIFO to fill, dropping characters. You can find an example of this here: <https://twitter.com/sz_jynik/status/1414989128245067780>

If you wish to introduce intra-character delay to console input, provide an intrachar keyword argument or DEPTHCHARGE_CONSOLE_INTRACHAR environment variable. (The latter takes presence.) This floating point value, in seconds, is the minimum amount of time that shall be inserted between successive bytes. Realistically, the value will be larger because this mode of operation will send each byte with a single write() + flush(), incurring non-negligible overhead. You may set a value of 0 to incur only this implicit overhead, with no additional sleep()-based delay.

property device: Device or interface used to communicate with console on target device.

property baudrate: Serial console’s baud rate configuration.

send_command(cmd: str, read_response=True) → str

Send the provided command (cmd) to the attached U-Boot console.

If read_response is True, the response is returned. Otherwise, None is returned and no attempt to read the response data is made.

If one does not plan to use the response, keep read_response set to True and simply ignore the return value; this will ensure response data is removed from underlying buffers.

interrupt(interrupt_str='\x03', timeout=30.0)

Attempt to interrupt U-Boot and retrieve a console prompt.

By default, the character associated traditionally with Ctrl-C is sent to interrupt U-Boot.

If trying to do this at boot-time (within the autoboot grace period), note that a specific “Stop String” may be required.

Refer to U-Boot’s doc/README.autoboot regarding the CONFIG_AUTOBOOT_KEYED and CONFIG_AUTOBOOT_STOP_STR configuration options for more information.

discover_prompt(interrupt_str='\x03', timeout=30.0, count=10): Attempt to deduce the U-Boot prompt string by repeatedly attempting to interrupt its execution by sending interrupt_str until count consecutive prompt strings are observed.

readline(update_monitor=True) → str

Read and return one line from the serial console.