| 1 | ======== |
| 2 | Codebase |
| 3 | ======== |
| 4 | |
| 5 | This section presents the various parts of QEMU and how the codebase is |
| 6 | organized. |
| 7 | |
| 8 | Beyond giving succinct descriptions, the goal is to offer links to various |
| 9 | parts of the documentation/codebase. |
| 10 | |
| 11 | Those two videos are an excellent introduction to QEMU codebase: |
| 12 | |
| 13 | - `QEMU Dev Starter guide - General overview <https://www.youtube.com/watch?v=OCBLTMKLGAk>`_ |
| 14 | - `QEMU Dev Starter guide - System mode <https://www.youtube.com/watch?v=jrZ56K3Sl_k>`_ |
| 15 | |
| 16 | Subsystems |
| 17 | ---------- |
| 18 | |
| 19 | An exhaustive list of subsystems and associated files can be found in the |
| 20 | `MAINTAINERS <https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS>`_ |
| 21 | file. |
| 22 | |
| 23 | Some of the main QEMU subsystems are: |
| 24 | |
| 25 | - `Accelerators<Accelerators>` |
| 26 | - Block devices and `disk images<disk images>` support |
| 27 | - `CI<ci>` and `Tests<testing>` |
| 28 | - `Devices<device-emulation>` & Board models |
| 29 | - `Documentation <documentation-root>` |
| 30 | - `GDB support<GDB usage>` |
| 31 | - :ref:`Migration<migration>` |
| 32 | - `Monitor<QEMU monitor>` |
| 33 | - :ref:`QOM (QEMU Object Model)<qom>` |
| 34 | - `System mode<System emulation>` |
| 35 | - :ref:`TCG (Tiny Code Generator)<tcg>` |
| 36 | - `User mode<user-mode>` (`Linux<linux-user-mode>` & `BSD<bsd-user-mode>`) |
| 37 | - User Interfaces |
| 38 | |
| 39 | More documentation on QEMU subsystems can be found on :ref:`internal-subsystem` |
| 40 | page. |
| 41 | |
| 42 | The Grand tour |
| 43 | -------------- |
| 44 | |
| 45 | We present briefly here what every folder in the top directory of the codebase |
| 46 | contains. Hop on! |
| 47 | |
| 48 | The folder name links here will take you to that folder in our gitlab |
| 49 | repository. Other links will take you to more detailed documentation for that |
| 50 | subsystem, where we have it. Unfortunately not every subsystem has documentation |
| 51 | yet, so sometimes the source code is all you have. |
| 52 | |
| 53 | * `accel <https://gitlab.com/qemu-project/qemu/-/tree/master/accel>`_: |
| 54 | Infrastructure and architecture agnostic code related to the various |
| 55 | `accelerators <Accelerators>` supported by QEMU |
| 56 | (TCG, KVM, hvf, whpx, xen, nvmm, mshv). |
| 57 | Contains interfaces for operations that will be implemented per |
| 58 | `target <https://gitlab.com/qemu-project/qemu/-/tree/master/target>`_. |
| 59 | * `audio <https://gitlab.com/qemu-project/qemu/-/tree/master/audio>`_: |
| 60 | Audio (host) support. |
| 61 | * `authz <https://gitlab.com/qemu-project/qemu/-/tree/master/authz>`_: |
| 62 | `QEMU Authorization framework<client authorization>`. |
| 63 | * `backends <https://gitlab.com/qemu-project/qemu/-/tree/master/backends>`_: |
| 64 | Various backends that are used to access resources on the host (e.g. for |
| 65 | random number generation, memory backing or cryptographic functions). |
| 66 | * `block <https://gitlab.com/qemu-project/qemu/-/tree/master/block>`_: |
| 67 | Block devices and `image formats<disk images>` implementation. |
| 68 | * `bsd-user <https://gitlab.com/qemu-project/qemu/-/tree/master/bsd-user>`_: |
| 69 | `BSD User mode<bsd-user-mode>`. |
| 70 | * build: Where the code built goes by default. You can tell the QEMU build |
| 71 | system to put the built code anywhere else you like. |
| 72 | * `chardev <https://gitlab.com/qemu-project/qemu/-/tree/master/chardev>`_: |
| 73 | Various backends used by char devices. |
| 74 | * `common-user <https://gitlab.com/qemu-project/qemu/-/tree/master/common-user>`_: |
| 75 | User-mode assembly code for dealing with signals occurring during syscalls. |
| 76 | * `configs <https://gitlab.com/qemu-project/qemu/-/tree/master/configs>`_: |
| 77 | Makefiles defining configurations to build QEMU. |
| 78 | * `contrib <https://gitlab.com/qemu-project/qemu/-/tree/master/contrib>`_: |
| 79 | Community contributed devices/plugins/tools. |
| 80 | * `crypto <https://gitlab.com/qemu-project/qemu/-/tree/master/crypto>`_: |
| 81 | Cryptographic algorithms used in QEMU. |
| 82 | * `disas <https://gitlab.com/qemu-project/qemu/-/tree/master/disas>`_: |
| 83 | Disassembly functions used by QEMU target code. |
| 84 | * `docs <https://gitlab.com/qemu-project/qemu/-/tree/master/docs>`_: |
| 85 | QEMU Documentation. |
| 86 | * `dump <https://gitlab.com/qemu-project/qemu/-/tree/master/dump>`_: |
| 87 | Code to dump memory of a running VM. |
| 88 | * `ebpf <https://gitlab.com/qemu-project/qemu/-/tree/master/ebpf>`_: |
| 89 | eBPF program support in QEMU. `virtio-net RSS<ebpf-rss>` uses it. |
| 90 | * `fpu <https://gitlab.com/qemu-project/qemu/-/tree/master/fpu>`_: |
| 91 | Floating-point software emulation. |
| 92 | * `fsdev <https://gitlab.com/qemu-project/qemu/-/tree/master/fsdev>`_: |
| 93 | `VirtFS <https://www.linux-kvm.org/page/VirtFS>`_ support. |
| 94 | * `gdbstub <https://gitlab.com/qemu-project/qemu/-/tree/master/gdbstub>`_: |
| 95 | `GDB <GDB usage>` support. |
| 96 | * `host <https://gitlab.com/qemu-project/qemu/-/tree/master/host>`_: |
| 97 | Various architecture specific header files (crypto, atomic, memory |
| 98 | operations). |
| 99 | * `linux-headers <https://gitlab.com/qemu-project/qemu/-/tree/master/linux-headers>`_: |
| 100 | A subset of headers imported from Linux kernel and used for implementing |
| 101 | KVM support and user-mode. |
| 102 | * `linux-user <https://gitlab.com/qemu-project/qemu/-/tree/master/linux-user>`_: |
| 103 | `User mode <user-mode>` implementation. Contains one folder per target |
| 104 | architecture. |
| 105 | * `.gitlab-ci.d <https://gitlab.com/qemu-project/qemu/-/tree/master/.gitlab-ci.d>`_: |
| 106 | `CI <ci>` yaml and scripts. |
| 107 | * `include <https://gitlab.com/qemu-project/qemu/-/tree/master/include>`_: |
| 108 | All headers associated to different subsystems in QEMU. The hierarchy used |
| 109 | mirrors source code organization and naming. |
| 110 | * `hw <https://gitlab.com/qemu-project/qemu/-/tree/master/hw>`_: |
| 111 | `Devices <device-emulation>` and boards emulation. Devices are categorized by |
| 112 | type/protocol/architecture and located in associated subfolder. |
| 113 | * `io <https://gitlab.com/qemu-project/qemu/-/tree/master/io>`_: |
| 114 | QEMU `I/O channels <https://lists.gnu.org/archive/html/qemu-devel/2015-11/msg04208.html>`_. |
| 115 | * `libdecnumber <https://gitlab.com/qemu-project/qemu/-/tree/master/libdecnumber>`_: |
| 116 | Import of gcc library, used to implement decimal number arithmetic. |
| 117 | * `migration <https://gitlab.com/qemu-project/qemu/-/tree/master/migration>`__: |
| 118 | :ref:`Migration framework <migration>`. |
| 119 | * `monitor <https://gitlab.com/qemu-project/qemu/-/tree/master/monitor>`_: |
| 120 | `Monitor <QEMU monitor>` implementation (HMP & QMP). |
| 121 | * `nbd <https://gitlab.com/qemu-project/qemu/-/tree/master/nbd>`_: |
| 122 | QEMU NBD (Network Block Device) server. |
| 123 | * `net <https://gitlab.com/qemu-project/qemu/-/tree/master/net>`_: |
| 124 | Network (host) support. |
| 125 | * `pc-bios <https://gitlab.com/qemu-project/qemu/-/tree/master/pc-bios>`_: |
| 126 | Contains pre-built firmware binaries and boot images, ready to use in |
| 127 | QEMU without compilation. |
| 128 | * `plugins <https://gitlab.com/qemu-project/qemu/-/tree/master/plugins>`_: |
| 129 | :ref:`TCG plugins <tcg-plugins>` core implementation. Plugins can be found in |
| 130 | `tests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tcg/plugins>`__ |
| 131 | and `contrib <https://gitlab.com/qemu-project/qemu/-/tree/master/contrib/plugins>`__ |
| 132 | folders. |
| 133 | * `po <https://gitlab.com/qemu-project/qemu/-/tree/master/po>`_: |
| 134 | Translation files. |
| 135 | * `python <https://gitlab.com/qemu-project/qemu/-/tree/master/python>`_: |
| 136 | Python part of our build/test system. |
| 137 | * `qapi <https://gitlab.com/qemu-project/qemu/-/tree/master/qapi>`_: |
| 138 | `QAPI <qapi>` implementation. |
| 139 | * `qobject <https://gitlab.com/qemu-project/qemu/-/tree/master/qobject>`_: |
| 140 | QEMU Object implementation. |
| 141 | * `qga <https://gitlab.com/qemu-project/qemu/-/tree/master/qga>`_: |
| 142 | QEMU `Guest agent <qemu-ga>` implementation. |
| 143 | * `qom <https://gitlab.com/qemu-project/qemu/-/tree/master/qom>`_: |
| 144 | QEMU :ref:`Object model <qom>` implementation, with monitor associated commands. |
| 145 | * `replay <https://gitlab.com/qemu-project/qemu/-/tree/master/replay>`_: |
| 146 | QEMU :ref:`Record/replay <replay>` implementation. |
| 147 | * `roms <https://gitlab.com/qemu-project/qemu/-/tree/master/roms>`_: |
| 148 | Contains source code for various firmware and ROMs, which can be compiled if |
| 149 | custom or updated versions are needed. |
| 150 | * `rust <https://gitlab.com/qemu-project/qemu/-/tree/master/rust>`_: |
| 151 | Rust integration in QEMU. It contains the new interfaces defined and |
| 152 | associated devices using it. |
| 153 | * `scripts <https://gitlab.com/qemu-project/qemu/-/tree/master/scripts>`_: |
| 154 | Collection of scripts used in build and test systems, and various |
| 155 | tools for QEMU codebase and execution traces. |
| 156 | * `scsi <https://gitlab.com/qemu-project/qemu/-/tree/master/scsi>`_: |
| 157 | Code related to SCSI support, used by SCSI devices. |
| 158 | * `semihosting <https://gitlab.com/qemu-project/qemu/-/tree/master/semihosting>`_: |
| 159 | QEMU `Semihosting <Semihosting>` implementation. |
| 160 | * `stats <https://gitlab.com/qemu-project/qemu/-/tree/master/stats>`_: |
| 161 | `Monitor <QEMU monitor>` stats commands implementation. |
| 162 | * `storage-daemon <https://gitlab.com/qemu-project/qemu/-/tree/master/storage-daemon>`_: |
| 163 | QEMU `Storage daemon <storage-daemon>` implementation. |
| 164 | * `stubs <https://gitlab.com/qemu-project/qemu/-/tree/master/stubs>`_: |
| 165 | Various stubs (empty functions) used to compile QEMU with specific |
| 166 | configurations. |
| 167 | * `subprojects <https://gitlab.com/qemu-project/qemu/-/tree/master/subprojects>`_: |
| 168 | QEMU submodules used by QEMU build system. |
| 169 | * `system <https://gitlab.com/qemu-project/qemu/-/tree/master/system>`_: |
| 170 | QEMU `system mode <System emulation>` implementation (cpu, mmu, boot support). |
| 171 | * `target <https://gitlab.com/qemu-project/qemu/-/tree/master/target>`_: |
| 172 | Contains code for all target architectures supported (one subfolder |
| 173 | per arch). For every architecture, you can find accelerator specific |
| 174 | implementations. |
| 175 | * `tcg <https://gitlab.com/qemu-project/qemu/-/tree/master/tcg>`_: |
| 176 | :ref:`TCG <tcg>` related code. |
| 177 | Contains one subfolder per host supported architecture. |
| 178 | * `tests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests>`_: |
| 179 | QEMU `test <testing>` suite |
| 180 | |
| 181 | - `data <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/data>`_: |
| 182 | Data for various tests. |
| 183 | - `decode <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/decode>`_: |
| 184 | Testsuite for :ref:`decodetree <decodetree>` implementation. |
| 185 | - `docker <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/docker>`_: |
| 186 | Code and scripts to create `containers <container-ref>` used in `CI <ci>`. |
| 187 | - `fp <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/fp>`_: |
| 188 | QEMU testsuite for soft float implementation. |
| 189 | - `functional <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/functional>`_: |
| 190 | `Functional tests <checkfunctional-ref>` (full VM boot). |
| 191 | - `lcitool <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/lcitool>`_: |
| 192 | Generate dockerfiles for CI containers. |
| 193 | - `migration <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/migration>`_: |
| 194 | Test scripts and data for :ref:`Migration framework <migration>`. |
| 195 | - `multiboot <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/multiboot>`_: |
| 196 | Test multiboot functionality for x86_64/i386. |
| 197 | - `qapi-schema <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qapi-schema>`_: |
| 198 | Test scripts and data for `QAPI <qapi-tests>`. |
| 199 | - `qemu-iotests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qemu-iotests>`_: |
| 200 | `Disk image and block tests <qemu-iotests>`. |
| 201 | - `qtest <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qtest>`_: |
| 202 | `Device emulation testing <qtest>`. |
| 203 | - `tcg <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tcg>`__: |
| 204 | `TCG related tests <checktcg-ref>`. Contains code per architecture |
| 205 | (subfolder) and multiarch tests as well. |
| 206 | - `tsan <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tsan>`_: |
| 207 | `Suppressions <tsan-suppressions>` for thread sanitizer. |
| 208 | - `uefi-test-tools <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/uefi-test-tools>`_: |
| 209 | Test tool for UEFI support. |
| 210 | - `unit <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/unit>`_: |
| 211 | QEMU `Unit tests <unit-tests>`. |
| 212 | * `trace <https://gitlab.com/qemu-project/qemu/-/tree/master/trace>`_: |
| 213 | :ref:`Tracing framework <tracing>`. Used to print information associated to various |
| 214 | events during execution. |
| 215 | * `ui <https://gitlab.com/qemu-project/qemu/-/tree/master/ui>`_: |
| 216 | QEMU User interfaces. |
| 217 | * `util <https://gitlab.com/qemu-project/qemu/-/tree/master/util>`_: |
| 218 | Utility code used by other parts of QEMU. |