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,
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,
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,
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 viapw_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,
Pre start work, returns command to start the emulator.
The target and emulator configuration can be accessed through
pw_emu.core.Launcher._config
withpw_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,
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