xref: /aosp_15_r20/external/pigweed/pw_emu/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_emu:
2
3.. rst-class:: with-subtitle
4
5======
6pw_emu
7======
8.. pigweed-module::
9   :name: pw_emu
10
11* **Declarative**. Define emulation targets in JSON. A target encapsulates the
12  emulated machine, tools, and host channels configuration.
13* **Flexible**. Manage multiple emulator instances over a CLI or Python API.
14* **Unopinionated**. Use QEMU or Renode, or extend ``pw_emu`` to support your
15  favorite emulator.
16* **Configurable**. Expose channels for debugging and monitoring through
17  configurable host resources like sockets.
18
19Declaratively configure an emulation target like this:
20
21.. code-block:: json
22
23   {
24     "targets": {
25       "qemu-lm3s6965evb": {
26         "gdb": [
27           "arm-none-eabi-gdb"
28         ],
29         "qemu": {
30           "executable": "qemu-system-arm",
31           "machine": "lm3s6965evb",
32           "channels": {
33             "chardevs": {
34               "serial0": {
35                 "id": "serial0"
36               }
37             }
38           }
39         }
40       }
41     }
42   }
43
44Then run a binary like this!
45
46.. code-block:: console
47
48   pw emu run --args=-no-reboot qemu-lm3s6965evb \
49       out/lm3s6965evb_qemu_gcc_size_optimized/obj/pw_snapshot/test/cpp_compile_test
50
51.. pw_emu-nav-start
52
53.. grid:: 1
54
55   .. grid-item-card:: :octicon:`rocket` Get started & guides
56      :link: module-pw_emu-guide
57      :link-type: ref
58      :class-item: sales-pitch-cta-primary
59
60      How to set up and use ``pw_emu``
61
62.. grid:: 2
63
64   .. grid-item-card:: :octicon:`terminal` CLI reference
65      :link: module-pw_emu-cli
66      :link-type: ref
67      :class-item: sales-pitch-cta-secondary
68
69      Reference details about the ``pw_emu`` command line interface
70
71   .. grid-item-card:: :octicon:`code-square` API reference
72      :link: module-pw_emu-api
73      :link-type: ref
74      :class-item: sales-pitch-cta-secondary
75
76      Reference details about the ``pw_emu`` Python API
77
78.. grid:: 2
79
80   .. grid-item-card:: :octicon:`gear` Configuration
81      :link: module-pw_emu-config
82      :link-type: ref
83      :class-item: sales-pitch-cta-secondary
84
85      Reference details about ``pw_emu`` declarative configuration
86
87   .. grid-item-card:: :octicon:`stack` Design
88      :link: module-pw_emu-design
89      :link-type: ref
90      :class-item: sales-pitch-cta-secondary
91
92      Design details about ``pw_emu``
93
94.. grid:: 2
95
96   .. grid-item-card:: :octicon:`comment-discussion` SEED-0108: Emulators Frontend
97      :link: seed-0108
98      :link-type: ref
99      :class-item: sales-pitch-cta-secondary
100
101      The RFC explaining the initial design and motivations for ``pw_emu``
102
103   .. grid-item-card:: :octicon:`code-square` Source code
104      :link: seed-0108
105      :link-type: ref
106      :class-item: sales-pitch-cta-secondary
107
108      Source code for ``pw_emu``
109
110.. pw_emu-nav-end
111
112.. toctree::
113   :hidden:
114   :maxdepth: 1
115
116   guide
117   cli
118   api
119   config
120   design
121   SEED-0108 <../seed/0108>
122