Miscellanous Utilities

The utils.py module contains utility classes and functions that are used by all of the other modules such as e.g, logging.

class utils.Singleton

Bases: type

Singleton design pattern. To be used as a metaclass: class A(metaclass = Singleton)

class utils.Timer

Bases: object

Context manager style timer. To be used as: with Timer():

format_time(seconds)

utils.addr2line(elf_file: Path, pc_address: str) → tuple[str, int] | None

Mimics the functionality of the addr2line binutil using pyelftools. Takes an ELF file and an address, and returns the corresponding file name and line number using the .debug_line section.

Parameters:

• elf_file (pathlib.Path) – The elf file.

• pc_address (str) – The address of the program counter to look for within the elf in hexadecimal format as str.

Returns:

A file-line pair. The file (index-0) is the source which contains the line number that corresponds to the pc_address and the lien (index-1) is the 1-based indexing of the line number within the source file.

Return type:

tuple

utils.compile_assembly(*instructions, exit_on_error: bool = False) → bool

Executes a sequence of bash instructions to compile the self.asm_file. Uses subprocess for each instruction and optionally exits on error.

Parameters:

• exit_on_error (bool) – If an error is encountered during compilation and this is True, then the program terminates. Otherwise it continues.

• *instructions (str) – A sequence of bash commands required in order to (cross) compile the assembly files.

Returns:

True if no message was written to stderr from any of the executed instructions (subprocesses). False otherwise.

Return type:

bool

Raises:

SystemExit – if stderr contains text and exit_on_error is True.

utils.get_logger() → Logger

Return the pre-configured logger.

utils.reap_process_tree(pid: int, timeout: float = 5.0) → None

Gracefully terminate and reap the process tree for a given PID.

Parameters:

• pid (int) – The process ID of the root process.

• timeout (float) – Time in seconds to wait for processes to be reaped.

utils.setup_logger(stream_logging_level: int, log_file: str | None = None) → None

Set up a logger with stream and file handlers.

utils.to_snake_case(name: str) → str

Parameters:

name (str) – A camelCase-like string

Returns:

The name in snake_case format.

Return type:

str

utils.trace(self, message, *args, **kws)

utils.zip_archive(archive_name: str, *files) → str

Generates a .zip archive of arbitrary files.

Parameters:

archive_name (str) – The filename (stem) of the zip archive.

Returns:

The generated archive path string.

Return type:

str