Lines Matching +full:multiple +full:- +full:instance
5 .. _seed-0108:
14 :proposal_date: 2023-06-24
19 -------
21 -------
23 targets, start, control and interact with multiple running emulator instances,
26 -----------
28 -----------
30 for :ref:`target <docs-targets>` on the host machine. The **host** is the machine that
34 has a correspondence in the real world - a product, an evaluation board, a
65 ----------
67 ----------
75 Once started, the user is responsible for managing the emulator life-cycle,
76 potentially for multiple instances. They also have to interact with it through
78 host resource management. Especially in the case of using multiple emulator
82 conflict with multiple emulator instances or with other debuggers running on the
97 --------
99 --------
102 * Allows users to define emulation :ref:`targets <docs-targets>` that
106 * Provides a command line interface that manages multiple emulator instances and
112 * Supports multiple emulators, QEMU and renode as a starting point.
132 target fragment from the ``pw_emu/qemu-lm3s6965evb.json`` file:
134 .. code-block::
140 "pw_emu/qemu-lm3s6965evb.json"
147 ``pw_emu/qemu-lm3s6965evb.json`` defines the ``qemu-lm3s6965evb`` target
151 .. code-block::
155 "qemu-lm3s6965evb": {
156 "gdb": "arm-none-eabi-gdb",
158 "executable": "qemu-system-arm",
173 :ref:`target-lm3s6965evb-qemu` Pigweed build target.
182 .. code-block::
186 "renode-stm32f4_discovery": {
187 "gdb": "arm-none-eabi-gdb",
190 "machine": "platforms/boards/stm32f4_discovery-kit.repl",
194 "device-path": "sysbus.uart0",
217 The channel configuration can be set at multiple levels: emulator, target, or
223 * ``$pw_emu_wdir{relative-path}``: replaces statement with an absolute path by
226 * ``$pw_emu_channel_port{channel-name}``: replaces the statement with the port
229 * ``$pw_emu_channel_host{channel-name}``: replaces the statement with the host
232 * ``$pw_emu_channel_path{channel-name}``: replaces the statement with the path
249 .. code-block:: text
251 usage: pw emu [-h] [-i STRING] [-w WDIR] {command} ...
266 prop-ls List emulator object properties.
267 prop-get Show the emulator's object properties.
268 prop-set Show emulator's object properties.
269 gdb-cmds Run gdb commands in batch mode.
274 -h, --help show this help message and exit
275 -i STRING, --instance STRING
276 instance to use (default: default)
277 -w WDIR, --wdir WDIR path to working directory (default: None)
280 usage: pw emu start [-h] [--file FILE] [--runner {None,qemu,renode}]
281 [--args ARGS] [--pause] [--debug] [--foreground]
282 {qemu-lm3s6965evb,qemu-stm32vldiscovery,qemu-netduinoplus2}
283 usage: pw emu restart [-h] [--file FILE] [--runner {None,qemu,renode}]
284 [--args ARGS] [--pause] [--debug] [--foreground]
285 {qemu-lm3s6965evb,qemu-stm32vldiscovery,qemu-netduinoplus2}
286 usage: pw emu stop [-h]
287 usage: pw emu run [-h] [--args ARGS] [--channel CHANNEL]
288 {qemu-lm3s6965evb,qemu-stm32vldiscovery,qemu-netduinoplus2} FILE
289 usage: pw emu load [-h] [--pause] FILE
290 usage: pw emu reset [-h]
291 usage: pw emu gdb [-h] [--executable FILE]
292 usage: pw emu prop-ls [-h] path
293 usage: pw emu prop-get [-h] path property
294 usage: pw emu prop-set [-h] path property value
295 usage: pw emu gdb-cmds [-h] [--pause] [--executable FILE] gdb-command [gdb-command ...]
296 usage: pw emu term [-h] channel
302 .. code-block::
304 …$ pw emu run qemu-netduinoplus2 out/stm32f429i_disc1_debug/obj/pw_snapshot/test/cpp_compile_test.e…
306 --- Miniterm on serial0 ---
307 --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
313 --- exit ---
315 Multiple emulator instances can be run and each emulator instance is identified
317 ``$PW_PROJECT_ROOT/.pw_emu/<instance-id>`` where ``<instance-id>`` is a command
321 launch an emulator instance in the background. Then, the user can debug the
324 change emulator properties with the ``prop-ls``, ``prop-get``, ``prop-set`` and
325 finally stop the emulator instance with ``stop``.
331 emulator instance.
336 .. code-block:: python
338 # start an emulator instance and load the image to execute
353 # open the serial port and create a miniterm instance
358 miniterm.set_tx_encoding('UTF-8')
359 miniterm.set_rx_encoding('UTF-8')
377 emulator instance is stopped and the working directory is cleared when the with
385 .. code-block:: python
400 "--run_under=pw emu start <target> --file "
408 ------------------
413 emulator instance:
415 .. code-block:: python
425 ) -> None:
443 :python:`def running(self) -> bool:`
446 :python:`def stop(self) -> None`
449 :python:`def get_gdb_remote(self) -> str:`
452 :python:`def get_gdb(self) -> str | None:`
455 .. code-block:: python
461 ) -> subprocess.CompletedProcess:
473 :python:`def reset() -> None`
476 :python:`def list_properties(self, path: str) -> List[dict]`
486 :python:`def set_property(path: str, prop: str, value: str) -> None`
489 :python:`def get_property(self, path: str, prop: str) -> None`
492 :python:`def get_channel_type(self, name: str) -> str`
497 :python:`def get_channel_path(self, name: str) -> str:`
501 :python:`def get_channel_addr(self, name: str) -> tuple:`
505 .. code-block:: python
510 ) -> io.RawIOBase:
516 stream is operating in non-blocking mode. Otherwise read and write will
519 :python:`def get_channels(self) -> List[str]:`
522 :python:`def cont(self) -> None:`
525 ---------------------
527 ---------------------
534 get started with emulation will be lower - significantly lower for projects
537 There are two main use-cases that this proposal is addressing:
542 based testing (and trivial CI deployment - as long as the Pigweed bootstrap
551 multiple emulators from the start.
568 `qt-virt-manager <https://f1ash.github.io/qt-virt-manager/>`_,
569 `virt-manager <https://virt-manager.org/>`_) and virtualization (
572 `qemu-init <https://github.com/mm1ke/qemu-init>`_ is a qemu CLI frontend but since
576 .. inclusive-language: disable
584 use-cases (e.g. does not support running the QEMU process in the background,
585 does not multiple serial ports, does not support configuring how to expose the
590 .. inclusive-language: enable
592 ---------------
594 ---------------
598 Multiple instances are supported in order to enable developers who work on
599 multiple downstream Pigweed projects to work unhindered and also to run
600 multiple test instances in parallel on the same machine.
602 Each instance is identified by a system absolute path that is also used to store
603 state about the running instance such as pid files for running processes,
610 TemporaryEmulator & pw_emu_cli[pw emu cli] <--> Emulator
611 Emulator <--> Launcher & Connector
612 Launcher <--> Handles
613 Connector <--- Handles
614 Launcher <--> Config
615 Handles --Save--> WD --Load--> Handles
623 instance for a given configuration and target
629 a running emulator instance such as ports to reach emulator channels; it is
641 of direct QEMU invocation: :ref:`module-pw_rust`,
642 :ref:`target-lm3s6965evb-qemu`. The referenced QEMU targets are defined in
646 ------------
648 ------------
656 --------------
658 --------------
667 .. code-block:: python
681 :ref:`target-lm3s6965evb-qemu` however, once ``pw_emu`` is implemented it is