.. _module-pw_emu:

.. rst-class:: with-subtitle

======
pw_emu
======
.. pigweed-module::
   :name: pw_emu
   :tagline: Emulators frontend
   :status: experimental

--------
Overview
--------
``pw_emu`` is an emulators frontend with the following features:

* It allows users to define an emulation target that encapsulates the emulated
  machine configuration, the tools configuration and the host channels
  configuration.

* It provides a command line interface that manages multiple emulator instances
  and provides interactive access to the emulator's host channels.

* It provides a Python API to control emulator instances and access the
  emulator's host channels (e.g. serial ports).

* It supports multiple emulators, QEMU and renode.

* It expose channels for gdb, monitor and user selected devices through
  configurable host resources like sockets and ptys.

For background on why the module exists and some of the design
choices see :ref:`seed-0108`.

.. _module-pw_emu-get-started:

-----------
Get started
-----------
Include the desired emulator target files in the ``pigweed.json`` configuration
file, e.g.:

.. code-block::

   ...
   "pw_emu": {
      "target_files": [

        "pw_emu/qemu-lm3s6965evb.json",
        "pw_emu/qemu-stm32vldiscovery.json",
        "pw_emu/qemu-netduinoplus2.json",
        "renode-stm32f4_discovery.json"
      ]
    }
    ...


Build the ``qemu_gcc`` target and use ``pw emu run`` command to run the target
binaries on the host using the ``qemu-lm3s6965evb`` emulation target:

.. code:: bash

   ninja -C out qemu_gcc
   pw emu run --args=-no-reboot qemu-lm3s6965evb out/lm3s6965evb_qemu_gcc_size_optimized/obj/pw_snapshot/test/cpp_compile_test

See :ref:`module-pw_emu-guide` for more examples,
:ref:`module-pw_emu-config` for detailed configuration information,
:ref:`module-pw_emu-cli` for detailed CLI usage information and
:ref:`module-pw_emu-api` for managing emulators with Python APIs.

.. toctree::
   :hidden:
   :maxdepth: 1

   guide
   config
   cli
   api
   design