Configuration#
pw_emu: Flexible emulators frontend
pw_emu configuration is done in the pw.pw_emu namespace of
pigweed.json.
The target configuration allows users to start other programs before or after starting the main emulator process. This allows extending the emulated target with simulation or emulation outside of the main emulator. For example, for BLE emulation the main emulator could emulate just the serial port while the HCI emulation done is in an external program (e.g. bumble, netsim).
Configuration fragments#
Emulation targets can be stored in JSON files outside of pigweed.json.
These are known as configuration fragments. pigweed.json imports these
fragments via target_files.
Example configuration fragments:
Configuration reference#
The following list explains the valid schema for the pw_emu dict in
pigweed.json.
Caution
All the values below should be nested under pw.pw_emu in pigweed.json.
For example, the top-level gdb item in the list below actually lives
here:
{
"pw": {
"pw_emu": {
"gdb": ["..."]
}
}
}
gdb(list of strings) - The default GDB command to run. Can be overridden at the target level.target_files(list of strings) - Relative or absolute paths to Configuration fragments. Relative paths are interpreted relative to the project root directory.qemu(dict) - QEMU options.executable(string) - The default command for starting QEMU, e.g.system-arm-qemu. Can be overridden at the target level.args(list of strings) - Command line options to pass directly to QEMU whenexecutableis invoked. Can be extended (not overridden) at the target level.channels(dict) - Channel options.type(string) - The channel type. Optional.gdb(dict) - Channel-specific GDB options. Optional.type(string) - The channel type. Optional.
qmp(dict) - Channel-specific QMP options. Optional.type(string) - The channel type. Optional.
monitor(dict) - Channel-specific Monitor options. Optional.type(string) - The channel type. Optional.
renode(dict) - Renode options.executable(string) - The default command for starting Renode. Can be overridden at the target level.channels(dict) - Channel options.terminals(dict) - Generic options for exposed terminal devices, e.g. serial ports.type(string) - The channel type. Optional.
targets(dict) - Target configuration. Each key of this dict represents a target name.<target-name>(dict) - Configuration for a single target. Replace<target-name>with a real target name, e.g.qemu-lm3s6965evb.gdb(list of strings) - The GDB command to run for this target. Overrides the top-levelgdbcommand.pre-start-cmds(dict) - Commands to run before the emulator is started. See also Pre-start and post-start expression substitutions.<command-id>(list of strings) - A pre-start command. Replace<command-id>with a descriptive name for the command.
post-start-cmds(dict) - Commands to run after the emulator is started. See also Pre-start and post-start expression substitutions.<command-id>(list of strings) - A post-start command. Replace<command-id>with a descriptive name.
qemu(dict) - QEMU options for this target. Overrides the top-levelqemucommand.executable(string) - The command for starting QEMU on this target. Required.machine(string) - The QEMU-machinevalue for this target, e.g.stm32vldiscovery. Seeqemu-system-<arch> -machine helpfor a list of supported machines. Required.args(list of strings) - Command line options to pass directly to QEMU whenexecutableis invoked. This value extends the top-levelargsvalue; it does not override it. Optional.channels(dict) - Channel options for this target.chardevs(dict) - QEMU chardev device configuration. Usually serial ports.<channel-name>(dict) - The configuration for a single channel. Replace<channel-name>with a descriptive name.id(string) - The ID of the QEMU chardev.type(string) - The channel type. Optional.gdb(dict) - Channel-specific GDB options. Optional.type(string) - The channel type. Optional.
qmp(dict) - Channel-specific QMP options. Optional.type(string) - The channel type. Optional.
monitor(dict) - Channel-specific Monitor options. Optional.type(string) - The channel type. Optional.
renode(dict) - Renode options for this target.executable(string) - The command for starting Renode on this target, e.g.renode.machine(string) - The Renode script to use for machine definitions, e.g.platforms/boards/stm32f4_discovery-kit.repl.channels(dict) - Channel options.terminals(dict) - Exposed terminal devices, usually serial ports.<device-name>(dict) - Device configuration. Replace<device-name>with a descriptive name, e.g.serial0.device-path(string) - The path to the device, e.g.sysbus.usart1.type(string) - The channel type. Optional.
Channel types#
The following channel types are currently supported:
pty- Full support on macOS and Linux. Renode only supports PTYs forterminals.tcp- Full support on all platforms and channels. This is the default value if no channel type is configured.
The channel configuration can be set at the emulator, target, or channel level. The channel level takes precedence, then the target level, then the emulator level.
Pre-start and post-start expression substitutions#
The following expressions are substituted in the pre-start-cmd and
post-start-cmd strings:
$pw_emu_wdir{relative-path}- Replaces the statement with an absolute path by concatenating the emulator’s working directory with the given relative path.$pw_emu_channel_port{channel-name}- Replaces the statement with the port number for the given channel name. The channel type should betcp.$pw_emu_channel_host{channel-name}- Replaces the statement with the host for the given channel name. The channel type should betcp.$pw_emu_channel_path{channel-name}- Replaces the statement with the path for the given channel name. The channel type should bepty.
Configuration string substitutions#
The following expressions are substituted in configuration strings, including Configuration fragments:
$pw_env{envvar}- Replaces the statement with the value ofenvvar. Ifenvvardoesn’t exist a configuration error is raised.