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