1================ 2QEMU and Kconfig 3================ 4 5QEMU is a very versatile emulator; it can be built for a variety of 6targets, where each target can emulate various boards and at the same 7time different targets can share large amounts of code. For example, 8a POWER and an x86 board can run the same code to emulate a PCI network 9card, even though the boards use different PCI host bridges, and they 10can run the same code to emulate a SCSI disk while using different 11SCSI adapters. ARM, s390 and x86 boards can all present a virtio-blk 12disk to their guests, but with three different virtio guest interfaces. 13 14Each QEMU target enables a subset of the boards, devices and buses that 15are included in QEMU's source code. As a result, each QEMU executable 16only links a small subset of the files that form QEMU's source code; 17anything that is not needed to support a particular target is culled. 18 19QEMU uses a simple domain-specific language to describe the dependencies 20between components. This is useful for two reasons: 21 22* new targets and boards can be added without knowing in detail the 23 architecture of the hardware emulation subsystems. Boards only have 24 to list the components they need, and the compiled executable will 25 include all the required dependencies and all the devices that the 26 user can add to that board; 27 28* users can easily build reduced versions of QEMU that support only a subset 29 of boards or devices. For example, by default most targets will include 30 all emulated PCI devices that QEMU supports, but the build process is 31 configurable and it is easy to drop unnecessary (or otherwise unwanted) 32 code to make a leaner binary. 33 34This domain-specific language is based on the Kconfig language that 35originated in the Linux kernel, though it was heavily simplified and 36the handling of dependencies is stricter in QEMU. 37 38Unlike Linux, there is no user interface to edit the configuration, which 39is instead specified in per-target files under the ``default-configs/`` 40directory of the QEMU source tree. This is because, unlike Linux, 41configuration and dependencies can be treated as a black box when building 42QEMU; the default configuration that QEMU ships with should be okay in 43almost all cases. 44 45The Kconfig language 46-------------------- 47 48Kconfig defines configurable components in files named ``hw/*/Kconfig``. 49Note that configurable components are _not_ visible in C code as preprocessor 50symbols; they are only visible in the Makefile. Each configurable component 51defines a Makefile variable whose name starts with ``CONFIG_``. 52 53All elements have boolean (true/false) type; truth is written as ``y``, while 54falsehood is written ``n``. They are defined in a Kconfig 55stanza like the following:: 56 57 config ARM_VIRT 58 bool 59 imply PCI_DEVICES 60 imply VFIO_AMD_XGBE 61 imply VFIO_XGMAC 62 select A15MPCORE 63 select ACPI 64 select ARM_SMMUV3 65 66The ``config`` keyword introduces a new configuration element. In the example 67above, Makefiles will have access to a variable named ``CONFIG_ARM_VIRT``, 68with value ``y`` or ``n`` (respectively for boolean true and false). 69 70Boolean expressions can be used within the language, whenever ``<expr>`` 71is written in the remainder of this section. The ``&&``, ``||`` and 72``!`` operators respectively denote conjunction (AND), disjunction (OR) 73and negation (NOT). 74 75The ``bool`` data type declaration is optional, but it is suggested to 76include it for clarity and future-proofing. After ``bool`` the following 77directives 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 ``default-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 ``default-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 133Guidelines for writing Kconfig files 134------------------------------------ 135 136Configurable elements in QEMU fall under five broad groups. Each group 137declares 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 ``default-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 two device groups, ``PCI_DEVICES`` and 194 ``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 ``TEST_DEVICES`` instead is used for devices that are rarely used on 199 production virtual machines, but provide useful hooks to test QEMU 200 or KVM. 201 202**boards** 203 204 Example:: 205 206 config SUN4M 207 bool 208 imply TCX 209 imply CG3 210 select CS4231 211 select ECCMEMCTL 212 select EMPTY_SLOT 213 select ESCC 214 select ESP 215 select FDC 216 select SLAVIO 217 select LANCE 218 select M48T59 219 select STP2000 220 221 Boards specify their constituent devices using ``imply`` and ``select`` 222 directives. A device should be listed under ``select`` if the board 223 cannot be started at all without it. It should be listed under 224 ``imply`` if (depending on the QEMU command line) the board may or 225 may not be started without it. Boards also default to false; they are 226 enabled by the ``default-configs/*.mak`` for the target they apply to. 227 228**internal elements** 229 230 Example:: 231 232 config ECCMEMCTL 233 bool 234 select ECC 235 236 Internal elements group code that is useful in several boards or 237 devices. They are usually enabled with ``select`` and in turn select 238 other elements; they are never visible in ``default-configs/*.mak`` 239 files, and often not even in the Makefile. 240 241Writing and modifying default configurations 242-------------------------------------------- 243 244In addition to the Kconfig files under hw/, each target also includes 245a file called ``default-configs/TARGETNAME-softmmu.mak``. These files 246initialize some Kconfig variables to non-default values and provide the 247starting point to turn on devices and subsystems. 248 249A file in ``default-configs/`` looks like the following example:: 250 251 # Default configuration for alpha-softmmu 252 253 # Uncomment the following lines to disable these optional devices: 254 # 255 #CONFIG_PCI_DEVICES=n 256 #CONFIG_TEST_DEVICES=n 257 258 # Boards: 259 # 260 CONFIG_DP264=y 261 262The first part, consisting of commented-out ``=n`` assignments, tells 263the user which devices or device groups are implied by the boards. 264The second part, consisting of ``=y`` assignments, tells the user which 265boards are supported by the target. The user will typically modify 266the default configuration by uncommenting lines in the first group, 267or commenting out lines in the second group. 268 269It is also possible to run QEMU's configure script with the 270``--with-default-devices`` option. When this is done, everything defaults 271to ``n`` unless it is ``select``ed or explicitly switched on in the 272``.mak`` files. In other words, ``default`` and ``imply`` directives 273are disabled. When QEMU is built with this option, the user will probably 274want to change some lines in the first group, for example like this:: 275 276 CONFIG_PCI_DEVICES=y 277 #CONFIG_TEST_DEVICES=n 278 279and/or pick a subset of the devices in those device groups. Right now 280there is no single place that lists all the optional devices for 281``CONFIG_PCI_DEVICES`` and ``CONFIG_TEST_DEVICES``. In the future, 282we expect that ``.mak`` files will be automatically generated, so that 283they will include all these symbols and some help text on what they do. 284 285``Kconfig.host`` 286---------------- 287 288In some special cases, a configurable element depends on host features 289that are detected by QEMU's configure script; for example some devices 290depend on the availability of KVM or on the presence of a library on 291the host. 292 293These symbols should be listed in ``Kconfig.host`` like this:: 294 295 config KVM 296 bool 297 298and also listed as follows in the top-level Makefile's ``MINIKCONF_ARGS`` 299variable:: 300 301 MINIKCONF_ARGS = \ 302 $@ $*/config-devices.mak.d $< $(MINIKCONF_INPUTS) \ 303 CONFIG_KVM=$(CONFIG_KVM) \ 304 CONFIG_SPICE=$(CONFIG_SPICE) \ 305 CONFIG_TPM=$(CONFIG_TPM) \ 306 ... 307