block: trickle down the fallback image creation function use to the block drivers
[qemu/ar7.git] / docs / devel / kconfig.rst
blobe5df72b34228ffb38a937d53a157f413e6aa8c5c
1 ================
2 QEMU and Kconfig
3 ================
5 QEMU is a very versatile emulator; it can be built for a variety of
6 targets, where each target can emulate various boards and at the same
7 time different targets can share large amounts of code.  For example,
8 a POWER and an x86 board can run the same code to emulate a PCI network
9 card, even though the boards use different PCI host bridges, and they
10 can run the same code to emulate a SCSI disk while using different
11 SCSI adapters.  Arm, s390 and x86 boards can all present a virtio-blk
12 disk to their guests, but with three different virtio guest interfaces.
14 Each QEMU target enables a subset of the boards, devices and buses that
15 are included in QEMU's source code.  As a result, each QEMU executable
16 only links a small subset of the files that form QEMU's source code;
17 anything that is not needed to support a particular target is culled.
19 QEMU uses a simple domain-specific language to describe the dependencies
20 between components.  This is useful for two reasons:
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;
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.
34 This domain-specific language is based on the Kconfig language that
35 originated in the Linux kernel, though it was heavily simplified and
36 the handling of dependencies is stricter in QEMU.
38 Unlike Linux, there is no user interface to edit the configuration, which
39 is instead specified in per-target files under the ``default-configs/``
40 directory of the QEMU source tree.  This is because, unlike Linux,
41 configuration and dependencies can be treated as a black box when building
42 QEMU; the default configuration that QEMU ships with should be okay in
43 almost all cases.
45 The Kconfig language
46 --------------------
48 Kconfig defines configurable components in files named ``hw/*/Kconfig``.
49 Note that configurable components are _not_ visible in C code as preprocessor
50 symbols; they are only visible in the Makefile.  Each configurable component
51 defines a Makefile variable whose name starts with ``CONFIG_``.
53 All elements have boolean (true/false) type; truth is written as ``y``, while
54 falsehood is written ``n``.  They are defined in a Kconfig
55 stanza like the following::
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
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).
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).
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:
79 **dependencies**: ``depends on <expr>``
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.
85 **reverse dependencies**: ``select <symbol> [if <expr>]``
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::
91     config FOO
92       select BAZ
94   The optional expression will prevent ``select`` from having any effect
95   unless it is true.
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.
101 **default value**: ``default <value> [if <expr>]``
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``.
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.
115 **reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``
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::
123     config FOO
124       bool
125       imply BAZ
127     config BAZ
128       bool
129       default y if FOO
131   The next section explains where to use ``imply`` or ``default y``.
133 Guidelines for writing Kconfig files
134 ------------------------------------
136 Configurable elements in QEMU fall under five broad groups.  Each group
137 declares its dependencies in different ways:
139 **subsystems**, of which **buses** are a special case
141   Example::
143     config SCSI
144       bool
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.
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.
154 **devices**
156   Example::
158     config MEGASAS_SCSI_PCI
159       bool
160       default y if PCI_DEVICES
161       depends on PCI
162       select SCSI
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.
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.
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.
180 **device groups**
182   Example::
184     config PCI_DEVICES
185       bool
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.
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.
202 **boards**
204   Example::
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
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.
228 **internal elements**
230   Example::
232     config ECCMEMCTL
233       bool
234       select ECC
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.
241 Writing and modifying default configurations
242 --------------------------------------------
244 In addition to the Kconfig files under hw/, each target also includes
245 a file called ``default-configs/TARGETNAME-softmmu.mak``.  These files
246 initialize some Kconfig variables to non-default values and provide the
247 starting point to turn on devices and subsystems.
249 A file in ``default-configs/`` looks like the following example::
251     # Default configuration for alpha-softmmu
253     # Uncomment the following lines to disable these optional devices:
254     #
255     #CONFIG_PCI_DEVICES=n
256     #CONFIG_TEST_DEVICES=n
258     # Boards:
259     #
260     CONFIG_DP264=y
262 The first part, consisting of commented-out ``=n`` assignments, tells
263 the user which devices or device groups are implied by the boards.
264 The second part, consisting of ``=y`` assignments, tells the user which
265 boards are supported by the target.  The user will typically modify
266 the default configuration by uncommenting lines in the first group,
267 or commenting out lines in the second group.
269 It is also possible to run QEMU's configure script with the
270 ``--without-default-devices`` option.  When this is done, everything defaults
271 to ``n`` unless it is ``select``ed or explicitly switched on in the
272 ``.mak`` files.  In other words, ``default`` and ``imply`` directives
273 are disabled.  When QEMU is built with this option, the user will probably
274 want to change some lines in the first group, for example like this::
276    CONFIG_PCI_DEVICES=y
277    #CONFIG_TEST_DEVICES=n
279 and/or pick a subset of the devices in those device groups.  Right now
280 there is no single place that lists all the optional devices for
281 ``CONFIG_PCI_DEVICES`` and ``CONFIG_TEST_DEVICES``.  In the future,
282 we expect that ``.mak`` files will be automatically generated, so that
283 they will include all these symbols and some help text on what they do.
285 ``Kconfig.host``
286 ----------------
288 In some special cases, a configurable element depends on host features
289 that are detected by QEMU's configure script; for example some devices
290 depend on the availability of KVM or on the presence of a library on
291 the host.
293 These symbols should be listed in ``Kconfig.host`` like this::
295     config KVM
296       bool
298 and also listed as follows in the top-level Makefile's ``MINIKCONF_ARGS``
299 variable::
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       ...