depthcharge.uboot

U-Boot centric parsing, conversion, and data processing functionality

depthcharge.uboot.board

Parsing and conversion of “board” or platform-specific data

depthcharge.uboot.board.bdinfo_dict(output: str) → dict

Convert output of U-Boot’s bdinfo command to a dictionary.

Technically, each item may come from a variety of locations, whether it be gd, gd->bd, or another structure.

However, we’ll just return everything in a single dict out of laziness.

depthcharge.uboot.board.bdinfo_str(bdinfo: dict) → str

Return a user-facing, printable string from a dictionary returned by bdinfo_dict().

depthcharge.uboot.cmd_table

U-Boot command table (“linker list”) parsing and analysis functionality

depthcharge.uboot.cmd_table.entry_to_bytes(arch, entry: dict) → bytes

Pack a U-Boot command table entry (struct cmd_tbl_s), as defined by the following dictionary keys and return it’s representation in bytes.

Key	Value Type	Description
name	int	Pointer to command name string
maxargs	int	Maximum number of arguments the command takes
cmd_rep	int	Depending upon the U-Boot version, either a flag or function pointer used for command autorepeat behavior
cmd	int	Function pointer for do_<command>
usage	int	Pointer to short usage text string
longhelp	int	Pointer to longer command description and help text. Only present if U-Boot was built with CONFIG_SYS_LONGHELP
autocomplete	int	Function pointer to autocomplete handler. Only present if U-Boot was built with CONFIG_AUTOCOMPLETE.

The arch parameter is required in order to pack the pointer values according to the target’s endianness.

depthcharge.uboot.env

U-Boot environment variable parsing and handling functionality

depthcharge.uboot.env.raw_regex(min_entries: int = 5, max_entries: Optional[int] = None)

Return a compiled regular expression for locating a U-Boot environment in a binary. This does not include env_t metadata, such as the environment’s CRC32 word and optional flags byte.

The min_entries and max_entries parameters can be used to bound the size (in number of entries) of the environment to be matched.

If you haven’t already, consider using EnvironmentHunter instead, as this may already do everything you’re looking to implement.

depthcharge.uboot.env.raw_var_regex()

Return a compiled regular expression that can be used to match an environment variable definition in a binary.

If you haven’t already, consider using EnvironmentHunter instead, as this may already do everything you’re looking to implement.

depthcharge.uboot.env.parse(text: str) → dict

Parse the contents of the environment contained in the provided text (e.g. obtained through the console interface) and return the environment as a dictionary.

A ValueError is raised if no environment variables are found.

depthcharge.uboot.env.expand_variable(env: dict, to_expand: str, **kwargs) → str

Return the environment variable named to_expand with all variable definitions contained within it fully expanded.

A KeyError is raised if to_expand is not present in the provided env dictionary.

Optional Keyword Arguments:

limit - Maximum expansion iterations to peform. Default: 100

warn_only - Print a warning, but do not raise an exception, if the variable definition cannot be fully expended due to an undefined environment variable. This situtaion is possibly indicative of an issue with the U-Boot environment itself, rather than Depthcharge or anything the user has done incorrectly; it may be the case that some incomplete development cruft or reference design vestiges are present in the environment. If this occurs and this setting is set to False, a ValueError will be raised. Default: True

quiet - Suppress the above warning. (Requires warn_only=True.)

depthcharge.uboot.env.expand(env: dict, **kwargs) → dict

Return a copy of the provided U-Boot environment variable dictionary with all variable definitions fully resolved.

This function supports the same keyword arguments as expand_variable().

depthcharge.uboot.env.parse_raw(data: bytes) → dict

Parse the contents of an environment retrieved from flash or memory and provide an equivalent dictionary.

The provided data should being at the start of the variable definitions. It must not contain the env_t metadata, such as the CRC32 word and the flags value (only present when compiled with “CONFIG_SYS_REDUNDAND_ENVIRONMENT”.

A ValueError is raised if no environment variables are found.

depthcharge.uboot.env.load(filename: str) → dict

Load a U-Boot environment from a text file and return it as a dictionary.

The text file is expected to be in the same format as that used by U-Boot’s printenv command output.

A ValueError is raised if no environment variables are found.

depthcharge.uboot.env.load_raw(filename: str, arch: str, has_crc=True, has_flags=False) → tuple

Load an environment previously carved from a binary or saved with save_raw(). It is returned as a tuple: (env: dict, metadata: dict)

This function expects the environment (metadata) to begin at offset 0 in the opened file. The name of the target architecture (arch) must be provided.

The has_crc and has_flags boolean parameters should be used to specify whether the file contains a U-Boot env_t header.

depthcharge.uboot.env.save(filename: str, env: dict)

Write the contents of an environment to a text file that can later be loaded via :py:func:load()`.

depthcharge.uboot.env.save_raw(filename: str, env: dict, size: int, arch: str, flags: Optional[int] = None, no_header=False)

Convert the environment information stored in env and save it to filename.

Refer to create_raw_environment() for more information about this function’s arguments.

depthcharge.uboot.env.create_raw(env: dict, size: int, arch: str, flags: Optional[int] = None, no_header=False) → bytes

Convert the environment contained the env dictionary to the binary format that can be used to replace an environment in non-volatile storage.

The size parameter must match the target’s compile-time CONFIG_ENV_SIZE definition. The environment is zero-padded to this length prior to the computation of its CRC32 checksum. If you don’t know this value and can extract flash contents, you can use EnvironmentHunter to locate environment instances. The src_size entry in the results for of find() and finditer() correspond to this size.

The arch parameter must name the target architecture that will be processing the environment.

Finally, an optional flags value can be provided. This is an env_t structure field present only when U-Boot is compiled with the CONFIG_SYS_REDUNDAND_ENV (sic) option. This option enables the use of two environment copies, should one become corrupted during the programming operation (e.g. via unexpected power-loss). Although called “flags”, it’s basically a monotonic modulo-256 counter that’s incremented by one at each write to denote the freshest copy. (See env/common.c)

If you are replacing an environment that uses this feature, be sure to provide either the same flags value or a greater value.

Setting no_header=True will create the environment contents without any header metadata (i.e., no CRC word, no flags).

depthcharge.uboot.jump_table

Definitions corresponding to U-Boot’s exported Jump Table

depthcharge.uboot.jump_table.exports(sys_malloc_simple=False) → list

Return a list of functions exported in U-Boot’s “jump table”. These are provided in the order they appear in the jump table.

Each entry is a tuple laid out as follows:

Index	Type	Description
0	str	Function name
1	str	Return type
2	list	Argument types (each a str)

Not all functions are necessarily implemented. In most cases, a dummy function is used as a placeholder if it is not included by the build configuration. Bear in mind, this This is not always true. For example, CONFIG_PHY_AQUANTIA results in additional items, for which there are typically no dummies; these are not included.

If sys_malloc_simple=True, the free() function is omitted, per U-Boot’s build-time CONFIG_SYS_MALLOC_SIMPLE setting. This is typically only used when building a U-Boot SPL, which usually do not have interactive consoles.

depthcharge.uboot.jump_table.find(gd_address, memory_reader, arch, **kwargs) → dict

Search for U-Boot’s exported jump table, given the address of the global data structure (gd), an instance of MemoryReader, and the architecture of the target.

Upon success, the returned dictionary will contain the following keys:

• address - Address of the jump table

• entries - List of jump table entries. Each entry is a dict with name, value, suffix keys.

• extras - Other global data structure information picked up in the process of

  searching for the jumptable.

If you already have a Depthcharge handle, consider instead invoking its uboot_global_data() method, which will take care of finding the location of gd and calling this function.