diff options
Diffstat (limited to 'pw_emu/config.rst')
| -rw-r--r-- | pw_emu/config.rst | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/pw_emu/config.rst b/pw_emu/config.rst new file mode 100644 index 000000000..41d1b2fe4 --- /dev/null +++ b/pw_emu/config.rst @@ -0,0 +1,155 @@ +.. _module-pw_emu-config: + +============= +Configuration +============= +.. pigweed-module-subpage:: + :name: pw_emu + :tagline: 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 <https://google.github.io/bumble>`_, +`netsim <https://android.googlesource.com/platform/tools/netsim>`_). + +.. _module-pw_emu-config-options: + +----------------------- +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 |