1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
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
|
