| 1 | .. _kconfig: |
| 2 | |
| 3 | ================ |
| 4 | QEMU and Kconfig |
| 5 | ================ |
| 6 | |
| 7 | QEMU is a very versatile emulator; it can be built for a variety of |
| 8 | targets, where each target can emulate various boards and at the same |
| 9 | time different targets can share large amounts of code. For example, |
| 10 | a POWER and an x86 board can run the same code to emulate a PCI network |
| 11 | card, even though the boards use different PCI host bridges, and they |
| 12 | can run the same code to emulate a SCSI disk while using different |
| 13 | SCSI adapters. Arm, s390 and x86 boards can all present a virtio-blk |
| 14 | disk to their guests, but with three different virtio guest interfaces. |
| 15 | |
| 16 | Each QEMU target enables a subset of the boards, devices and buses that |
| 17 | are included in QEMU's source code. As a result, each QEMU executable |
| 18 | only links a small subset of the files that form QEMU's source code; |
| 19 | anything that is not needed to support a particular target is culled. |
| 20 | |
| 21 | QEMU uses a simple domain-specific language to describe the dependencies |
| 22 | between components. This is useful for two reasons: |
| 23 | |
| 24 | * new targets and boards can be added without knowing in detail the |
| 25 | architecture of the hardware emulation subsystems. Boards only have |
| 26 | to list the components they need, and the compiled executable will |
| 27 | include all the required dependencies and all the devices that the |
| 28 | user can add to that board; |
| 29 | |
| 30 | * users can easily build reduced versions of QEMU that support only a subset |
| 31 | of boards or devices. For example, by default most targets will include |
| 32 | all emulated PCI devices that QEMU supports, but the build process is |
| 33 | configurable and it is easy to drop unnecessary (or otherwise unwanted) |
| 34 | code to make a leaner binary. |
| 35 | |
| 36 | This domain-specific language is based on the Kconfig language that |
| 37 | originated in the Linux kernel, though it was heavily simplified and |
| 38 | the handling of dependencies is stricter in QEMU. |
| 39 | |
| 40 | Unlike Linux, there is no user interface to edit the configuration, which |
| 41 | is instead specified in per-target files under the ``configs/`` |
| 42 | directory of the QEMU source tree. This is because, unlike Linux, |
| 43 | configuration and dependencies can be treated as a black box when building |
| 44 | QEMU; the default configuration that QEMU ships with should be okay in |
| 45 | almost all cases. |
| 46 | |
| 47 | The Kconfig language |
| 48 | -------------------- |
| 49 | |
| 50 | Kconfig defines configurable components in files named ``hw/*/Kconfig``. |
| 51 | Note that configurable components are _not_ visible in C code as preprocessor |
| 52 | symbols; they are only visible in the Makefile. Each configurable component |
| 53 | defines a Makefile variable whose name starts with ``CONFIG_``. |
| 54 | |
| 55 | All elements have boolean (true/false) type; truth is written as ``y``, while |
| 56 | falsehood is written ``n``. They are defined in a Kconfig |
| 57 | stanza like the following:: |
| 58 | |
| 59 | config ARM_VIRT |
| 60 | bool |
| 61 | imply PCI_DEVICES |
| 62 | select A15MPCORE |
| 63 | select ACPI |
| 64 | select ARM_SMMUV3 |
| 65 | |
| 66 | The ``config`` keyword introduces a new configuration element. In the example |
| 67 | above, Makefiles will have access to a variable named ``CONFIG_ARM_VIRT``, |
| 68 | with value ``y`` or ``n`` (respectively for boolean true and false). |
| 69 | |
| 70 | Boolean expressions can be used within the language, whenever ``<expr>`` |
| 71 | is written in the remainder of this section. The ``&&``, ``||`` and |
| 72 | ``!`` operators respectively denote conjunction (AND), disjunction (OR) |
| 73 | and negation (NOT). |
| 74 | |
| 75 | The ``bool`` data type declaration is optional, but it is suggested to |
| 76 | include it for clarity and future-proofing. After ``bool`` the following |
| 77 | directives can be included: |
| 78 | |
| 79 | **dependencies**: ``depends on <expr>`` |
| 80 | |
| 81 | This defines a dependency for this configurable element. Dependencies |
| 82 | evaluate an expression and force the value of the variable to false |
| 83 | if the expression is false. |
| 84 | |
| 85 | **reverse dependencies**: ``select <symbol> [if <expr>]`` |
| 86 | |
| 87 | While ``depends on`` can force a symbol to false, reverse dependencies can |
| 88 | be used to force another symbol to true. In the following example, |
| 89 | ``CONFIG_BAZ`` will be true whenever ``CONFIG_FOO`` is true:: |
| 90 | |
| 91 | config FOO |
| 92 | select BAZ |
| 93 | |
| 94 | The optional expression will prevent ``select`` from having any effect |
| 95 | unless it is true. |
| 96 | |
| 97 | Note that unlike Linux's Kconfig implementation, QEMU will detect |
| 98 | contradictions between ``depends on`` and ``select`` statements and prevent |
| 99 | you from building such a configuration. |
| 100 | |
| 101 | **default value**: ``default <value> [if <expr>]`` |
| 102 | |
| 103 | Default values are assigned to the config symbol if no other value was |
| 104 | set by the user via ``configs/*.mak`` files, and only if |
| 105 | ``select`` or ``depends on`` directives do not force the value to true |
| 106 | or false respectively. ``<value>`` can be ``y`` or ``n``; it cannot |
| 107 | be an arbitrary Boolean expression. However, a condition for applying |
| 108 | the default value can be added with ``if``. |
| 109 | |
| 110 | A configuration element can have any number of default values (usually, |
| 111 | if more than one default is present, they will have different |
| 112 | conditions). If multiple default values satisfy their condition, |
| 113 | only the first defined one is active. |
| 114 | |
| 115 | **reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]`` |
| 116 | |
| 117 | This is similar to ``select`` as it applies a lower limit of ``y`` |
| 118 | to another symbol. However, the lower limit is only a default |
| 119 | and the "implied" symbol's value may still be set to ``n`` from a |
| 120 | ``configs/*.mak`` files. The following two examples are |
| 121 | equivalent:: |
| 122 | |
| 123 | config FOO |
| 124 | bool |
| 125 | imply BAZ |
| 126 | |
| 127 | config BAZ |
| 128 | bool |
| 129 | default y if FOO |
| 130 | |
| 131 | The next section explains where to use ``imply`` or ``default y``. |
| 132 | |
| 133 | Guidelines for writing Kconfig files |
| 134 | ------------------------------------ |
| 135 | |
| 136 | Configurable elements in QEMU fall under five broad groups. Each group |
| 137 | declares its dependencies in different ways: |
| 138 | |
| 139 | **subsystems**, of which **buses** are a special case |
| 140 | |
| 141 | Example:: |
| 142 | |
| 143 | config SCSI |
| 144 | bool |
| 145 | |
| 146 | Subsystems always default to false (they have no ``default`` directive) |
| 147 | and are never visible in ``configs/*.mak`` files. It's |
| 148 | up to other symbols to ``select`` whatever subsystems they require. |
| 149 | |
| 150 | They sometimes have ``select`` directives to bring in other required |
| 151 | subsystems or buses. For example, ``AUX`` (the DisplayPort auxiliary |
| 152 | channel "bus") selects ``I2C`` because it can act as an I2C master too. |
| 153 | |
| 154 | **devices** |
| 155 | |
| 156 | Example:: |
| 157 | |
| 158 | config MEGASAS_SCSI_PCI |
| 159 | bool |
| 160 | default y if PCI_DEVICES |
| 161 | depends on PCI |
| 162 | select SCSI |
| 163 | |
| 164 | Devices are the most complex of the five. They can have a variety |
| 165 | of directives that cooperate so that a default configuration includes |
| 166 | all the devices that can be accessed from QEMU. |
| 167 | |
| 168 | Devices *depend on* the bus that they lie on, for example a PCI |
| 169 | device would specify ``depends on PCI``. An MMIO device will likely |
| 170 | have no ``depends on`` directive. Devices also *select* the buses |
| 171 | that the device provides, for example a SCSI adapter would specify |
| 172 | ``select SCSI``. Finally, devices are usually ``default y`` if and |
| 173 | only if they have at least one ``depends on``; the default could be |
| 174 | conditional on a device group. |
| 175 | |
| 176 | Devices also select any optional subsystem that they use; for example |
| 177 | a video card might specify ``select EDID`` if it needs to build EDID |
| 178 | information and publish it to the guest. |
| 179 | |
| 180 | **device groups** |
| 181 | |
| 182 | Example:: |
| 183 | |
| 184 | config PCI_DEVICES |
| 185 | bool |
| 186 | |
| 187 | Device groups provide a convenient mechanism to enable/disable many |
| 188 | devices in one go. This is useful when a set of devices is likely to |
| 189 | be enabled/disabled by several targets. Device groups usually need |
| 190 | no directive and are not used in the Makefile either; they only appear |
| 191 | as conditions for ``default y`` directives. |
| 192 | |
| 193 | QEMU currently has three device groups, ``PCI_DEVICES``, ``I2C_DEVICES``, |
| 194 | and ``TEST_DEVICES``. PCI devices usually have a ``default y if |
| 195 | PCI_DEVICES`` directive rather than just ``default y``. This lets |
| 196 | some boards (notably s390) easily support a subset of PCI devices, |
| 197 | for example only VFIO (passthrough) and virtio-pci devices. |
| 198 | ``I2C_DEVICES`` is similar to ``PCI_DEVICES``. It contains i2c devices |
| 199 | that users might reasonably want to plug in to an i2c bus on any |
| 200 | board (and not ones which are very board-specific or that need |
| 201 | to be wired up in a way that can't be done on the command line). |
| 202 | ``TEST_DEVICES`` instead is used for devices that are rarely used on |
| 203 | production virtual machines, but provide useful hooks to test QEMU |
| 204 | or KVM. |
| 205 | |
| 206 | **boards** |
| 207 | |
| 208 | Example:: |
| 209 | |
| 210 | config SUN4M |
| 211 | bool |
| 212 | default y |
| 213 | depends on SPARC && !SPARC64 |
| 214 | imply TCX |
| 215 | imply CG3 |
| 216 | select CS4231 |
| 217 | select ECCMEMCTL |
| 218 | select EMPTY_SLOT |
| 219 | select ESCC |
| 220 | select ESP |
| 221 | select FDC |
| 222 | select SLAVIO |
| 223 | select LANCE |
| 224 | select M48T59 |
| 225 | select STP2000 |
| 226 | |
| 227 | Boards specify their constituent devices using ``imply`` and ``select`` |
| 228 | directives. A device should be listed under ``select`` if the board |
| 229 | cannot be started at all without it. It should be listed under |
| 230 | ``imply`` if (depending on the QEMU command line) the board may or |
| 231 | may not be started without it. Boards default to true, but also |
| 232 | have a ``depends on`` clause to limit them to the appropriate targets. |
| 233 | For some targets, not all boards may be supported by hardware |
| 234 | virtualization, in which case they also depend on the ``TCG`` symbol, |
| 235 | Other symbols that are commonly used as dependencies for boards |
| 236 | include libraries (such as ``FDT``) or ``TARGET_BIG_ENDIAN`` |
| 237 | (possibly negated). |
| 238 | |
| 239 | Boards are listed for convenience in the ``configs/*.mak`` |
| 240 | for the target they apply to. |
| 241 | |
| 242 | **internal elements** |
| 243 | |
| 244 | Example:: |
| 245 | |
| 246 | config ECCMEMCTL |
| 247 | bool |
| 248 | select ECC |
| 249 | |
| 250 | Internal elements group code that is useful in several boards or |
| 251 | devices. They are usually enabled with ``select`` and in turn select |
| 252 | other elements; they are never visible in ``configs/*.mak`` |
| 253 | files, and often not even in the Makefile. |
| 254 | |
| 255 | Writing and modifying default configurations |
| 256 | -------------------------------------------- |
| 257 | |
| 258 | In addition to the Kconfig files under hw/, each target also includes |
| 259 | a file called ``configs/TARGETNAME-softmmu.mak``. These files |
| 260 | initialize some Kconfig variables to non-default values and provide the |
| 261 | starting point to turn on devices and subsystems. |
| 262 | |
| 263 | A file in ``configs/`` looks like the following example:: |
| 264 | |
| 265 | # Default configuration for alpha-softmmu |
| 266 | |
| 267 | # Uncomment the following lines to disable these optional devices: |
| 268 | # |
| 269 | #CONFIG_PCI_DEVICES=n |
| 270 | #CONFIG_TEST_DEVICES=n |
| 271 | |
| 272 | # Boards: |
| 273 | # |
| 274 | CONFIG_DP264=y |
| 275 | |
| 276 | The first part, consisting of commented-out ``=n`` assignments, tells |
| 277 | the user which devices or device groups are implied by the boards. |
| 278 | The second part, consisting of ``=y`` assignments, tells the user which |
| 279 | boards are supported by the target. The user will typically modify |
| 280 | the default configuration by uncommenting lines in the first group, |
| 281 | or commenting out lines in the second group. |
| 282 | |
| 283 | It is also possible to run QEMU's configure script with the |
| 284 | ``--without-default-devices`` option. When this is done, everything defaults |
| 285 | to ``n`` unless it is ``select``\ ed or explicitly switched on in the |
| 286 | ``.mak`` files. In other words, ``default`` and ``imply`` directives |
| 287 | are disabled. When QEMU is built with this option, the user will probably |
| 288 | want to change some lines in the first group, for example like this:: |
| 289 | |
| 290 | CONFIG_PCI_DEVICES=y |
| 291 | #CONFIG_TEST_DEVICES=n |
| 292 | |
| 293 | and/or pick a subset of the devices in those device groups. Without |
| 294 | further modifications to ``configs/devices/``, a system emulator built |
| 295 | without default devices might not do much more than start an empty |
| 296 | machine, and even then only if ``--nodefaults`` is specified on the |
| 297 | command line. Starting a VM *without* ``--nodefaults`` is allowed to |
| 298 | fail, but should never abort. Failures in ``make check`` with |
| 299 | ``--without-default-devices`` are considered bugs in the test code: |
| 300 | the tests should either use ``--nodefaults``, and should be skipped |
| 301 | if a necessary device is not present in the build. Such failures |
| 302 | should not be worked around with ``select`` directives. |
| 303 | |
| 304 | Right now there is no single place that lists all the optional devices |
| 305 | for ``CONFIG_PCI_DEVICES`` and ``CONFIG_TEST_DEVICES``. In the future, |
| 306 | we expect that ``.mak`` files will be automatically generated, so that |
| 307 | they will include all these symbols and some help text on what they do. |
| 308 | |
| 309 | ``Kconfig.host`` |
| 310 | ---------------- |
| 311 | |
| 312 | In some special cases, a configurable element depends on host features |
| 313 | that are detected by QEMU's configure or ``meson.build`` scripts; for |
| 314 | example some devices depend on the availability of KVM or on the presence |
| 315 | of a library on the host. |
| 316 | |
| 317 | These symbols should be listed in ``Kconfig.host`` like this:: |
| 318 | |
| 319 | config TPM |
| 320 | bool |
| 321 | |
| 322 | and also listed as follows in the top-level meson.build's host_kconfig |
| 323 | variable:: |
| 324 | |
| 325 | host_kconfig = \ |
| 326 | (have_tpm ? ['CONFIG_TPM=y'] : []) + \ |
| 327 | (host_os == 'linux' ? ['CONFIG_LINUX=y'] : []) + \ |
| 328 | (have_ivshmem ? ['CONFIG_IVSHMEM=y'] : []) + \ |
| 329 | ... |