Configuration

Emulators frontend

The emulators configuration is part of the Pigweed root configuration file (pigweed.json) and reside in the pw:pw_emu namespace.

Projects can define emulation targets in the Pigweed root configuration file and can also import predefined targets from other files (configuration fragments). The pw_emu module provides a set of targets as examples and to promote reusability.

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 reference

• gdb: top level gdb command as a list of strings

  (e.g. [gdb-multiarch]); this can be overridden at the target level

• target_files: list of paths to json files to include targets from; the target configuration should be placed under a target key; if paths are relative they are interpreted relative to the project root directory

• qemu: options for the QEMU emulator:

  • executable`: command used to start QEMU (e.g. `system-arm-qemu); this can be overridden at the target level

  • args: list of command line options to pass directly to QEMU when starting an emulator instance; can be extended at the target level

  • channels: options for channel configuration:

    • type: optional type for channels, see channel types below

    • gdb, qmp, monitor: optional channel configuration entries

      • type: channel type, see channel types below

• renode: options for the renode emulator:

  • executable: command used to start renode (e.g. “system-arm-qemu”); this can be overridden at the target level

  • channels: options for channel configuration:

    • terminals: exposed terminal devices (serial ports) generic options:

      • type: optional type for channels, see channel types below

• targets: target configurations with target names as keys:

  • <target-name>: target options:

    • gdb: gdb command as a list of strings (e.g. [arm-none-eabi-gdb])

    • pre-start-cmds: commands to run before the emulator is started

      • <name>: command for starting the process as a list of strings

    • post-start-cmds: processes to run after the emulator is started

      • <name>: command for starting the process as a list of strings

    • qemu: options for the QEMU emulator:

      • executable: command used to start QEMU (e.g. system-arm-qemu)

      • args: list of command line options passed directly to QEMU when starting this target

      • machine: QEMU machine name; passed to the QEMU -machine command line argument

      • channels: exposed channels:

        • chardevs: exposed QEMU chardev devices (typically serial ports):

          • <channel-name>: channel options:

            • id: the id of the QEMU chardev

            • type: optional type of the channel see channel types below

        • gdb, qmp`, ``monitor: optional channel configuration entries

          • type: channel type, see channel types below

    • renode: options for the renode emulator:

      • executable: command used to start renode

      • machine: machine script to use when running this target

      • channels: exposed channels:

        • terminals: exposed terminal devices (serial ports):

          • <channel-name>: channel options:

            • device-path: device path

            • type: optional type of the channel see channel types below

The following channel types are currently supported:

• pty: supported on Mac and Linux; renode only supports ptys for terminals channels

• tcp: supported on all platforms and for all channels; it is also the default type if no channel type is configured

The channel configuration can be set at multiple levels: emulator, target, or specific channel. The channel configuration takes precedence, then the target channel configuration then the emulator channel configuration.

The following expressions are substituted in the pre-start-cmd and post-start-cmd strings:

• $pw_emu_wdir{relative-path}: replaces 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 be tcp

• $pw_emu_channel_host{channel-name}: replaces the statement with the host for the given channel name; the channel type should be tcp

• $pw_emu_channel_path{channel-name}: replaces the statement with the path for the given channel name; the channel type should be pty

The followng expressions are substituted in configuration strings, including configuration framents:

• $pw_env{envvar}: replaces statement with the value of the envar environment variable; if the variable does not exists in the environment a configuration error is raised