API reference#

Emulators frontend

User API

class pw_emu.frontend.Emulator(wdir: Path, config_path: Path | None = None)#

Launches, controls and interacts with an emulator instance.

__init__(wdir: Path, config_path: Path | None = None) → None#

cont() → None#: Resume the emulator’s execution.

get_channel_addr(name: str) → tuple#: Returns a pair of (host, port) for the channel. Raises InvalidChannelType if this is not a tcp channel.

get_channel_path(name: str) → str#: Returns the channel path. Raises InvalidChannelType if this is not a pty channel.

get_channel_stream(name: str, timeout: float | None = None) → RawIOBase#

Returns a file object for a given host exposed device.

If timeout is None than reads and writes are blocking. If timeout is zero the stream is operating in non-blocking mode. Otherwise read and write will timeout after the given value.

get_channel_type(name: str) → str#

Returns the channel type

Currently pty or tcp are the only supported types.

get_channels() → List[str]#: Returns the list of available channels.

get_gdb_cmd() → List[str]#: Returns the gdb command for current target.

get_gdb_remote() → str#: Return a string that can be passed to the target remote gdb command.

get_property(path: str, prop: str) → Any#: Returns the value of an emulator’s object property.

list_properties(path: str) → List[Dict]#

Returns the property list for an emulator object.

The object is identified by a full path. The path is target specific and the format of the path is backend specific.

qemu path example: /machine/unattached/device[10]

renode path example: sysbus.uart

reset() → None#: Perform a software reset.

run_gdb_cmds( commands: List[str], executable: str | None = None, pause: bool = False, ) → CompletedProcess#

Connect to the target and run the given commands silently in batch mode.

The executable is optional but it may be required by some gdb commands.

If pause is set do not continue execution after running the given commands.

running() → bool#: Check if the main emulator process is already running.

set_emu(emu: str) → None#: Set the emulator type for this instance.

set_property(path: str, prop: str, value: Any) → None#: Sets the value of an emulator’s object property.

start( target: str, file: Path | None = None, pause: bool = False, debug: bool = False, foreground: bool = False, args: str | None = None, ) → None#

Start the emulator for the given target.

If file is set the emulator will load the file before starting.

If pause is True the emulator is paused until the debugger is connected.

If debug is True the emulator is run in foreground with debug output enabled. This is useful for seeing errors, traces, etc.

If foreground is True the emulator is run in foreground otherwise it is started in daemon mode. This is useful when there is another process controlling the emulator’s life cycle (e.g. cuttlefish)

args are passed directly to the emulator

stop()#: Stop the emulator.

class pw_emu.frontend.TemporaryEmulator(config_path: Path | None = None, cleanup: bool = True)#

Temporary emulator instances.

Manages emulator instances that run in temporary working directories. The emulator instance is stopped and the working directory is cleared when the with block completes.

It also supports interoperability with the pw emu cli, i.e. starting the emulator with the CLI and controlling / interacting with it from the API.

Usage example:

# programatically start and load an executable then access it
with TemporaryEmulator() as emu:
    emu.start(target, file)
    with emu.get_channel_stream(chan) as stream:
        ...

# or start it form the command line then access it
with TemporaryEmulator() as emu:
    build.bazel(
        ctx,
        "run",
        exec_path,
        "--run_under=pw emu start <target> --file "
    )
    with emu.get_channel_stream(chan) as stream:
        ...

__init__(config_path: Path | None = None, cleanup: bool = True) → None#

Infrastructure used by the user interface or specific emulators.

exception pw_emu.core.AlreadyRunning(wdir: Path)

Exception raised if an emulator process is already running.

__init__(wdir: Path) → None

class pw_emu.core.Config(config_path: Path | None = None, target: str | None = None, emu: str | None = None)

Get and validate options from the configuration file.

__init__(config_path: Path | None = None, target: str | None = None, emu: str | None = None) → None

Load the emulator configuration.

If no configuration file path is given, the root project configuration is used.

This method set ups the generic configuration (e.g. gdb).

It loads emulator target files and gathers them under the ‘targets’ key for each emulator backend. The ‘targets’ settings in the configuration file takes precedence over the loaded target files.

get(keys: List[str], optional: bool = True, entry_type: Type | None = None) → Any

Get a config entry.

keys is a list of string that identifies the config entry, e.g. [‘targets’, ‘test-target’] is going to look in the config dicionary for [‘targets’][‘test-target’].

If the option is not found and optional is True it returns None if entry_type is none or a new (empty) object of type entry_type.

If the option is not found an optional is False it raises ConfigError.

If entry_type is not None it will check the option to be of that type. If it is not it will raise ConfigError.

get_emu(keys: List[str], optional: bool = True, entry_type: Type | None = None) → Any: Get a config option starting at [emu].

get_target(keys: List[str], optional: bool = True, entry_type: Type | None = None) → Any: Get a config option starting at [‘targets’][target].

get_target_emu(keys: List[str], optional: bool = True, entry_type: Type | None = None) → Any: Get a config option starting at [‘targets’][target][emu].

set_target(target: str) → None

Sets the current target.

The current target is used by the get_target method.

exception pw_emu.core.ConfigError(config: Path | None, err: str)

Exception raised for configuration errors.

__init__(config: Path | None, err: str) → None

class pw_emu.core.Connector(wdir: Path)

Interface between a running emulator and the user visible APIs.

__init__(wdir: Path) → None

abstract cont() → None: Resume the emulator’s execution.

static get(wdir: Path) → Any: Return a connector instace for a given emulator type.

get_channel_addr(name: str) → tuple: Returns a pair of (host, port) for the channel. Raises InvalidChannelType if this is not a tcp channel.

get_channel_path(name: str) → str: Returns the channel path. Raises InvalidChannelType if this is not a pty channel.

get_channel_stream(name: str, timeout: float | None = None) → RawIOBase

Returns a file object for a given host exposed device.

If timeout is None than reads and writes are blocking. If timeout is zero the stream is operating in non-blocking mode. Otherwise read and write will timeout after the given value.

get_channel_type(name: str) → str: Returns the channel type.

get_config_path() → Path: Returns the configuration path.

get_emu() → str: Returns the emulator type.

get_gdb_cmd() → List[str]: Returns the configured gdb command.

get_procs() → Dict[str, Proc]: Returns the running processes indexed by the process name.

abstract get_property(path: str, prop: str) → Any: Returns the value of an emulator’s object property.

abstract list_properties(path: str) → List[Any]: Returns the property list for an emulator object.

abstract reset() → None: Perform a software reset.

running() → bool: Check if the main emulator process is already running.

abstract set_property(path: str, prop: str, value: str) → None: Sets the value of an emulator’s object property.

stop() → None: Stop the emulator.

exception pw_emu.core.Error: Generic pw_emu exception.

class pw_emu.core.Handles(emu: str, config: str)

Running emulator handles.

__init__(emu: str, config: str) → None

add_channel_pty(name: str, path: str) → None: Add a pty channel.

add_channel_tcp(name: str, host: str, port: int) → None: Add a TCP channel.

add_proc(name: str, pid: int) → None: Add a pid.

save(wdir: Path) → None: Saves handles to the given working directory.

set_gdb_cmd(cmd: List[str]) → None: Set the gdb command.

set_target(target: str) → None: Set the target.

exception pw_emu.core.HandlesError(msg: str)

Exception raised while trying to load emulator handles.

__init__(msg: str) → None

exception pw_emu.core.InvalidChannelName(name: str, target: str, valid: str)

Exception raised if a channel name is invalid.

__init__(name: str, target: str, valid: str) → None

exception pw_emu.core.InvalidChannelType(name: str)

Exception raised if a channel type is invalid.

__init__(name: str) → None

exception pw_emu.core.InvalidEmulator(emu: str)

Exception raised if an different backend is running.

__init__(emu: str) → None

exception pw_emu.core.InvalidProperty(path: str, name: str)

Exception raised for an invalid property path.

__init__(path: str, name: str) → None

exception pw_emu.core.InvalidPropertyPath(path: str)

Exception raised for an invalid property path.

__init__(path: str) → None

exception pw_emu.core.InvalidTarget(config: Path, emu: str | None, target: str)

Exception raised if the target is invalid.

__init__(config: Path, emu: str | None, target: str) → None

class pw_emu.core.Launcher(emu: str, config_path: Path | None = None)

Starts an emulator based on the target and configuration file.

__init__(emu: str, config_path: Path | None = None) → None: Initializes a Launcher instance.

static get(emu: str, config_path: Path | None = None) → Any: Returns a launcher for a given emulator type.

start( wdir: Path, target: str, file: Path | None = None, pause: bool = False, debug: bool = False, foreground: bool = False, args: str | None = None, ) → Connector

Start the emulator for the given target.

If file is set that the emulator will load the file before starting.

If pause is True the emulator is paused.

If debug is True the emulator is run in foreground with debug output enabled. This is useful for seeing errors, traces, etc.

If foreground is True the emulator is run in foreground otherwise it is started in daemon mode. This is useful when there is another process controlling the emulator’s life cycle (e.g. cuttlefish)

args are passed directly to the emulator

exception pw_emu.core.NotRunning(wdir: Path)

Exception raised if an emulator process is not running.

__init__(wdir: Path) → None

exception pw_emu.core.RunError(proc: str, msg: str)

Exception raised when a command failed to run.

__init__(proc: str, msg: str) → None

exception pw_emu.core.WrongEmulator(exp: str, found: str)

Exception raised if an different backend is running.

__init__(exp: str, found: str) → None

class pw_emu.core.Launcher(emu: str, config_path: Path | None = None)#

Starts an emulator based on the target and configuration file.

__init__(emu: str, config_path: Path | None = None) → None#: Initializes a Launcher instance.

_config#: Global, emulator and target configuration.

abstract _get_connector(wdir: Path) → Connector#: Get a connector for this emulator type.

_handles#: Handles for processes, channels, etc.

abstract _post_start() → None#

Post start work, finalize emulator handles.

Perform any post start emulator initialization and finalize the emulator handles information.

Typically an internal monitor channel is used to inquire information about the the configured channels (e.g. TCP ports, pty paths) and pw_emu.core.Launcher._handles is updated via pw_emu.core.Handles.add_channel_tcp(), pw_emu.core.Handles.add_channel_pty(), etc.

abstract _pre_start( target: str, file: Path | None = None, pause: bool = False, debug: bool = False, args: str | None = None, ) → List[str]#

Pre start work, returns command to start the emulator.

The target and emulator configuration can be accessed through pw_emu.core.Launcher._config with pw_emu.core.Config.get(), pw_emu.core.Config.get_target(), pw_emu.core.Config.get_emu(), pw_emu.core.Config.get_target_emu().

static get(emu: str, config_path: Path | None = None) → Any#: Returns a launcher for a given emulator type.

start( wdir: Path, target: str, file: Path | None = None, pause: bool = False, debug: bool = False, foreground: bool = False, args: str | None = None, ) → Connector#

Start the emulator for the given target.

If file is set that the emulator will load the file before starting.

If pause is True the emulator is paused.

If debug is True the emulator is run in foreground with debug output enabled. This is useful for seeing errors, traces, etc.

If foreground is True the emulator is run in foreground otherwise it is started in daemon mode. This is useful when there is another process controlling the emulator’s life cycle (e.g. cuttlefish)

args are passed directly to the emulator