1.. _module-pw_emu-config: 2 3============= 4Configuration 5============= 6.. pigweed-module-subpage:: 7 :name: pw_emu 8 9``pw_emu`` configuration is done in the ``pw.pw_emu`` namespace of 10:ref:`pigweed.json <seed-0101>`. 11 12The target configuration allows users to start other programs before 13or after starting the main emulator process. This allows extending the 14emulated target with simulation or emulation outside of the main 15emulator. For example, for BLE emulation the main emulator could 16emulate just the serial port while the HCI emulation done is in an 17external program (e.g. `bumble <https://google.github.io/bumble>`_, 18`netsim <https://android.googlesource.com/platform/tools/netsim>`_). 19 20.. _module-pw_emu-config-fragments: 21 22----------------------- 23Configuration fragments 24----------------------- 25Emulation targets can be stored in JSON files outside of ``pigweed.json``. 26These are known as *configuration fragments*. ``pigweed.json`` imports these 27fragments via ``target_files``. 28 29Example configuration fragments: 30 31* `//pw_emu/qemu-lm3s6965evb.json <https://cs.opensource.google/pigweed/pigweed/+/main:pw_emu/qemu-lm3s6965evb.json>`_ 32* `//pw_emu/renode-stm32f4_discovery.json <https://cs.opensource.google/pigweed/pigweed/+/main:pw_emu/renode-stm32f4_discovery.json>`_ 33 34.. _module-pw_emu-config-options: 35 36----------------------- 37Configuration reference 38----------------------- 39The following list explains the valid schema for the ``pw_emu`` dict in 40:ref:`pigweed.json <seed-0101>`. 41 42.. caution:: 43 44 All the values below should be nested under ``pw.pw_emu`` in ``pigweed.json``. 45 For example, the top-level ``gdb`` item in the list below actually lives 46 here: 47 48 .. code-block:: json 49 50 { 51 "pw": { 52 "pw_emu": { 53 "gdb": ["..."] 54 } 55 } 56 } 57 58.. Note to maintainers: Multi-level unordered lists in reST are very finicky. 59.. The syntax below is the only one that works (e.g. spaces are significant). 60 61* ``gdb`` (list of strings) - The default GDB command to run. 62 Can be overridden at the target level. 63 64* ``target_files`` (list of strings) - Relative or absolute paths 65 to :ref:`module-pw_emu-config-fragments`. Relative paths are 66 interpreted relative to the project root directory. 67 68* ``qemu`` (dict) - QEMU options. 69 70 * ``executable`` (string) - The default command for starting 71 QEMU, e.g. ``system-arm-qemu``. Can be overridden at the target level. 72 73 * ``args`` (list of strings) - Command line options to pass 74 directly to QEMU when ``executable`` is invoked. Can be **extended** (not 75 overridden) at the target level. 76 77 * ``channels`` (dict) - Channel options. 78 79 * ``type`` (string) - The :ref:`channel type 80 <module-pw_emu-config-channel-types>`. Optional. 81 82 * ``gdb`` (dict) - Channel-specific GDB options. Optional. 83 84 * ``type`` (string) - The :ref:`channel type 85 <module-pw_emu-config-channel-types>`. Optional. 86 87 * ``qmp`` (dict) - Channel-specific QMP options. Optional. 88 89 * ``type`` (string) - The :ref:`channel type 90 <module-pw_emu-config-channel-types>`. Optional. 91 92 * ``monitor`` (dict) - Channel-specific Monitor options. Optional. 93 94 * ``type`` (string) - The :ref:`channel type 95 <module-pw_emu-config-channel-types>`. Optional. 96 97* ``renode`` (dict) - Renode options. 98 99 * ``executable`` (string) - The default command for starting Renode. Can be 100 overridden at the target level. 101 102 * ``channels`` (dict) - Channel options. 103 104 * ``terminals`` (dict) - Generic options for exposed terminal devices, e.g. 105 serial ports. 106 107 * ``type`` (string) - The :ref:`channel type 108 <module-pw_emu-config-channel-types>`. Optional. 109 110* ``targets`` (dict) - Target configuration. Each key of this dict represents 111 a target name. 112 113 * ``<target-name>`` (dict) - Configuration for a single target. Replace 114 ``<target-name>`` with a real target name, e.g. ``qemu-lm3s6965evb``. 115 116 * ``gdb`` (list of strings) - The GDB command to run for this target. 117 Overrides the top-level ``gdb`` command. 118 119 * ``pre-start-cmds`` (dict) - Commands to run before the emulator 120 is started. See also :ref:`module-pw_emu-config-pre-post-substitutions`. 121 122 * ``<command-id>`` (list of strings) - A pre-start command. 123 Replace ``<command-id>`` with a descriptive name for the command. 124 125 * ``post-start-cmds`` (dict) - Commands to run after the emulator 126 is started. See also :ref:`module-pw_emu-config-pre-post-substitutions`. 127 128 * ``<command-id>`` (list of strings) - A post-start command. 129 Replace ``<command-id>`` with a descriptive name. 130 131 * ``qemu`` (dict) - QEMU options for this target. Overrides the top-level 132 ``qemu`` command. 133 134 * ``executable`` (string) - The command for starting QEMU on this target. 135 Required. 136 137 * ``machine`` (string) - The QEMU ``-machine`` value for this target, 138 e.g. ``stm32vldiscovery``. See ``qemu-system-<arch> -machine help`` 139 for a list of supported machines. Required. 140 141 * ``args`` (list of strings) - Command line options to pass 142 directly to QEMU when ``executable`` is invoked. This value **extends** 143 the top-level ``args`` value; it does *not* override it. Optional. 144 145 * ``channels`` (dict) - Channel options for this target. 146 147 * ``chardevs`` (dict) - QEMU chardev device configuration. Usually 148 serial ports. 149 150 * ``<channel-name>`` (dict) - The configuration for a single channel. 151 Replace ``<channel-name>`` with a descriptive name. 152 153 * ``id`` (string) - The ID of the QEMU chardev. 154 155 * ``type`` (string) - The :ref:`channel type 156 <module-pw_emu-config-channel-types>`. Optional. 157 158 * ``gdb`` (dict) - Channel-specific GDB options. Optional. 159 160 * ``type`` (string) - The :ref:`channel type 161 <module-pw_emu-config-channel-types>`. Optional. 162 163 * ``qmp`` (dict) - Channel-specific QMP options. Optional. 164 165 * ``type`` (string) - The :ref:`channel type 166 <module-pw_emu-config-channel-types>`. Optional. 167 168 * ``monitor`` (dict) - Channel-specific Monitor options. Optional. 169 170 * ``type`` (string) - The :ref:`channel type 171 <module-pw_emu-config-channel-types>`. Optional. 172 173 * ``renode`` (dict) - Renode options for this target. 174 175 * ``executable`` (string) - The command for starting Renode on this target, 176 e.g. ``renode``. 177 178 * ``machine`` (string) - The Renode script to use for machine definitions, 179 e.g. ``platforms/boards/stm32f4_discovery-kit.repl``. 180 181 * ``channels`` (dict) - Channel options. 182 183 * ``terminals`` (dict) - Exposed terminal devices, usually serial ports. 184 185 * ``<device-name>`` (dict) - Device configuration. Replace ``<device-name>`` 186 with a descriptive name, e.g. ``serial0``. 187 188 * ``device-path`` (string) - The path to the device, e.g. 189 ``sysbus.usart1``. 190 191 * ``type`` (string) - The :ref:`channel type 192 <module-pw_emu-config-channel-types>`. Optional. 193 194.. _module-pw_emu-config-channel-types: 195 196Channel types 197============= 198The following channel types are currently supported: 199 200* ``pty`` - Full support on macOS and Linux. Renode only supports PTYs for 201 ``terminals``. 202 203* ``tcp`` - Full support on all platforms and channels. This is the default 204 value if no channel type is configured. 205 206The channel configuration can be set at the emulator, target, or channel level. 207The channel level takes precedence, then the target level, then the emulator 208level. 209 210.. _module-pw_emu-config-pre-post-substitutions: 211 212Pre-start and post-start expression substitutions 213================================================= 214The following expressions are substituted in the ``pre-start-cmd`` and 215``post-start-cmd`` strings: 216 217* ``$pw_emu_wdir{relative-path}`` - Replaces the statement with an absolute path 218 by concatenating the emulator's working directory with the given relative path. 219 220* ``$pw_emu_channel_port{channel-name}`` - Replaces the statement with the port 221 number for the given channel name. The channel type should be ``tcp``. 222 223* ``$pw_emu_channel_host{channel-name}`` - Replaces the statement with the host 224 for the given channel name. The channel type should be ``tcp``. 225 226* ``$pw_emu_channel_path{channel-name}`` - Replaces the statement with the path 227 for the given channel name. The channel type should be ``pty``. 228 229.. _module-pw_emu-config-string-substitutions: 230 231Configuration string substitutions 232================================== 233The following expressions are substituted in configuration strings, including 234:ref:`module-pw_emu-config-fragments`: 235 236* ``$pw_env{envvar}`` - Replaces the statement with the value of ``envvar``. 237 If ``envvar`` doesn't exist a configuration error is raised. 238 239---------------- 240More pw_emu docs 241---------------- 242.. include:: docs.rst 243 :start-after: .. pw_emu-nav-start 244 :end-before: .. pw_emu-nav-end 245