docs/devel/kconfig.rst

13 SCSI adapters.  Arm, s390 and x86 boards can all present a virtio-blk
16 Each QEMU target enables a subset of the boards, devices and buses that
21 QEMU uses a simple domain-specific language to describe the dependencies
24 * new targets and boards can be added without knowing in detail the
27   include all the required dependencies and all the devices that the
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
36 This domain-specific language is based on the Kconfig language that
41 is instead specified in per-target files under the ``configs/``
44 QEMU; the default configuration that QEMU ships with should be okay in
48 --------------------
78 include it for clarity and future-proofing.  After ``bool`` the following
103 **default value**: ``default <value> [if <expr>]``
105   Default values are assigned to the config symbol if no other value was
110   the default value can be added with ``if``.
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,
117 **reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``
120   to another symbol.  However, the lower limit is only a default
131       default y if FOO
133   The next section explains where to use ``imply`` or ``default y``.
136 ------------------------------------
148   Subsystems always default to false (they have no ``default`` directive)
156 **devices**
162       default y if PCI_DEVICES
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.
170   Devices *depend on* the bus that they lie on, for example a PCI
172   have no ``depends on`` directive.  Devices also *select* the buses
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
178   Devices also select any optional subsystem that they use; for example
190   devices in one go.  This is useful when a set of devices is likely to
193   as conditions for ``default y`` directives.
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
202   board (and not ones which are very board-specific or that need
204   ``TEST_DEVICES`` instead is used for devices that are rarely used on
214       default y
229   Boards specify their constituent devices using ``imply`` and ``select``
231   cannot be started at all without it.  It should be listed under
233   may not be started without it.  Boards default to true, but also
253   devices.  They are usually enabled with ``select`` and in turn select
257 Writing and modifying default configurations
258 --------------------------------------------
261 a file called ``configs/TARGETNAME-softmmu.mak``.  These files
262 initialize some Kconfig variables to non-default values and provide the
263 starting point to turn on devices and subsystems.
267     # Default configuration for alpha-softmmu
269     # Uncomment the following lines to disable these optional devices:
278 The first part, consisting of commented-out ``=n`` assignments, tells
279 the user which devices or device groups are implied by the boards.
282 the default configuration by uncommenting lines in the first group,
286 ``--without-default-devices`` option.  When this is done, everything defaults
288 ``.mak`` files.  In other words, ``default`` and ``imply`` directives
295 and/or pick a subset of the devices in those device groups.  Without
296 further modifications to ``configs/devices/``, a system emulator built
297 without default devices might not do much more than start an empty
298 machine, and even then only if ``--nodefaults`` is specified on the
299 command line.  Starting a VM *without* ``--nodefaults`` is allowed to
301 ``--without-default-devices`` are considered bugs in the test code:
302 the tests should either use ``--nodefaults``, and should be skipped
306 Right now there is no single place that lists all the optional devices
312 ----------------
316 example some devices depend on the availability of KVM or on the presence
324 and also listed as follows in the top-level meson.build's host_kconfig