qapi: Require boxed for conditional command and event arguments

[qemu/armbru.git] / docs / devel / kconfig.rst

.. _kconfig:

================
QEMU and Kconfig
================

QEMU is a very versatile emulator; it can be built for a variety of
targets, where each target can emulate various boards and at the same
time different targets can share large amounts of code.  For example,
a POWER and an x86 board can run the same code to emulate a PCI network
card, even though the boards use different PCI host bridges, and they
can run the same code to emulate a SCSI disk while using different
SCSI adapters.  Arm, s390 and x86 boards can all present a virtio-blk
disk to their guests, but with three different virtio guest interfaces.

Each QEMU target enables a subset of the boards, devices and buses that
are included in QEMU's source code.  As a result, each QEMU executable
only links a small subset of the files that form QEMU's source code;
anything that is not needed to support a particular target is culled.

QEMU uses a simple domain-specific language to describe the dependencies
between components.  This is useful for two reasons:

* new targets and boards can be added without knowing in detail the
  architecture of the hardware emulation subsystems.  Boards only have
  to list the components they need, and the compiled executable will
  include all the required dependencies and all the devices that the
  user can add to that board;

* users can easily build reduced versions of QEMU that support only a subset
  of boards or devices.  For example, by default most targets will include
  all emulated PCI devices that QEMU supports, but the build process is
  configurable and it is easy to drop unnecessary (or otherwise unwanted)
  code to make a leaner binary.

This domain-specific language is based on the Kconfig language that
originated in the Linux kernel, though it was heavily simplified and
the handling of dependencies is stricter in QEMU.

Unlike Linux, there is no user interface to edit the configuration, which
is instead specified in per-target files under the ``default-configs/``
directory of the QEMU source tree.  This is because, unlike Linux,
configuration and dependencies can be treated as a black box when building
QEMU; the default configuration that QEMU ships with should be okay in
almost all cases.

The Kconfig language
--------------------

Kconfig defines configurable components in files named ``hw/*/Kconfig``.
Note that configurable components are _not_ visible in C code as preprocessor
symbols; they are only visible in the Makefile.  Each configurable component
defines a Makefile variable whose name starts with ``CONFIG_``.

All elements have boolean (true/false) type; truth is written as ``y``, while
falsehood is written ``n``.  They are defined in a Kconfig
stanza like the following::

      config ARM_VIRT
         bool
         imply PCI_DEVICES
         imply VFIO_AMD_XGBE
         imply VFIO_XGMAC
         select A15MPCORE
         select ACPI
         select ARM_SMMUV3

The ``config`` keyword introduces a new configuration element.  In the example
above, Makefiles will have access to a variable named ``CONFIG_ARM_VIRT``,
with value ``y`` or ``n`` (respectively for boolean true and false).

Boolean expressions can be used within the language, whenever ``<expr>``
is written in the remainder of this section.  The ``&&``, ``||`` and
``!`` operators respectively denote conjunction (AND), disjunction (OR)
and negation (NOT).

The ``bool`` data type declaration is optional, but it is suggested to
include it for clarity and future-proofing.  After ``bool`` the following
directives can be included:

**dependencies**: ``depends on <expr>``

  This defines a dependency for this configurable element. Dependencies
  evaluate an expression and force the value of the variable to false
  if the expression is false.

**reverse dependencies**: ``select <symbol> [if <expr>]``

  While ``depends on`` can force a symbol to false, reverse dependencies can
  be used to force another symbol to true.  In the following example,
  ``CONFIG_BAZ`` will be true whenever ``CONFIG_FOO`` is true::

    config FOO
      select BAZ

  The optional expression will prevent ``select`` from having any effect
  unless it is true.

  Note that unlike Linux's Kconfig implementation, QEMU will detect
  contradictions between ``depends on`` and ``select`` statements and prevent
  you from building such a configuration.

**default value**: ``default <value> [if <expr>]``

  Default values are assigned to the config symbol if no other value was
  set by the user via ``default-configs/*.mak`` files, and only if
  ``select`` or ``depends on`` directives do not force the value to true
  or false respectively.  ``<value>`` can be ``y`` or ``n``; it cannot
  be an arbitrary Boolean expression.  However, a condition for applying
  the default value can be added with ``if``.

  A configuration element can have any number of default values (usually,
  if more than one default is present, they will have different
  conditions). If multiple default values satisfy their condition,
  only the first defined one is active.

**reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``

  This is similar to ``select`` as it applies a lower limit of ``y``
  to another symbol.  However, the lower limit is only a default
  and the "implied" symbol's value may still be set to ``n`` from a
  ``default-configs/*.mak`` files.  The following two examples are
  equivalent::

    config FOO
      bool
      imply BAZ

    config BAZ
      bool
      default y if FOO

  The next section explains where to use ``imply`` or ``default y``.

Guidelines for writing Kconfig files
------------------------------------

Configurable elements in QEMU fall under five broad groups.  Each group
declares its dependencies in different ways:

**subsystems**, of which **buses** are a special case

  Example::

    config SCSI
      bool

  Subsystems always default to false (they have no ``default`` directive)
  and are never visible in ``default-configs/*.mak`` files.  It's
  up to other symbols to ``select`` whatever subsystems they require.

  They sometimes have ``select`` directives to bring in other required
  subsystems or buses.  For example, ``AUX`` (the DisplayPort auxiliary
  channel "bus") selects ``I2C`` because it can act as an I2C master too.

**devices**

  Example::

    config MEGASAS_SCSI_PCI
      bool
      default y if PCI_DEVICES
      depends on PCI
      select SCSI

  Devices are the most complex of the five.  They can have a variety
  of directives that cooperate so that a default configuration includes
  all the devices that can be accessed from QEMU.

  Devices *depend on* the bus that they lie on, for example a PCI
  device would specify ``depends on PCI``.  An MMIO device will likely
  have no ``depends on`` directive.  Devices also *select* the buses
  that the device provides, for example a SCSI adapter would specify
  ``select SCSI``.  Finally, devices are usually ``default y`` if and
  only if they have at least one ``depends on``; the default could be
  conditional on a device group.

  Devices also select any optional subsystem that they use; for example
  a video card might specify ``select EDID`` if it needs to build EDID
  information and publish it to the guest.

**device groups**

  Example::

    config PCI_DEVICES
      bool

  Device groups provide a convenient mechanism to enable/disable many
  devices in one go.  This is useful when a set of devices is likely to
  be enabled/disabled by several targets.  Device groups usually need
  no directive and are not used in the Makefile either; they only appear
  as conditions for ``default y`` directives.

  QEMU currently has three device groups, ``PCI_DEVICES``, ``I2C_DEVICES``,
  and ``TEST_DEVICES``.  PCI devices usually have a ``default y if
  PCI_DEVICES`` directive rather than just ``default y``.  This lets
  some boards (notably s390) easily support a subset of PCI devices,
  for example only VFIO (passthrough) and virtio-pci devices.
  ``I2C_DEVICES`` is similar to ``PCI_DEVICES``. It contains i2c devices
  that users might reasonably want to plug in to an i2c bus on any
  board (and not ones which are very board-specific or that need
  to be wired up in a way that can't be done on the command line).
  ``TEST_DEVICES`` instead is used for devices that are rarely used on
  production virtual machines, but provide useful hooks to test QEMU
  or KVM.

**boards**

  Example::

    config SUN4M
      bool
      imply TCX
      imply CG3
      select CS4231
      select ECCMEMCTL
      select EMPTY_SLOT
      select ESCC
      select ESP
      select FDC
      select SLAVIO
      select LANCE
      select M48T59
      select STP2000

  Boards specify their constituent devices using ``imply`` and ``select``
  directives.  A device should be listed under ``select`` if the board
  cannot be started at all without it.  It should be listed under
  ``imply`` if (depending on the QEMU command line) the board may or
  may not be started without it.  Boards also default to false; they are
  enabled by the ``default-configs/*.mak`` for the target they apply to.

**internal elements**

  Example::

    config ECCMEMCTL
      bool
      select ECC

  Internal elements group code that is useful in several boards or
  devices.  They are usually enabled with ``select`` and in turn select
  other elements; they are never visible in ``default-configs/*.mak``
  files, and often not even in the Makefile.

Writing and modifying default configurations
--------------------------------------------

In addition to the Kconfig files under hw/, each target also includes
a file called ``default-configs/TARGETNAME-softmmu.mak``.  These files
initialize some Kconfig variables to non-default values and provide the
starting point to turn on devices and subsystems.

A file in ``default-configs/`` looks like the following example::

    # Default configuration for alpha-softmmu

    # Uncomment the following lines to disable these optional devices:
    #
    #CONFIG_PCI_DEVICES=n
    #CONFIG_TEST_DEVICES=n

    # Boards:
    #
    CONFIG_DP264=y

The first part, consisting of commented-out ``=n`` assignments, tells
the user which devices or device groups are implied by the boards.
The second part, consisting of ``=y`` assignments, tells the user which
boards are supported by the target.  The user will typically modify
the default configuration by uncommenting lines in the first group,
or commenting out lines in the second group.

It is also possible to run QEMU's configure script with the
``--without-default-devices`` option.  When this is done, everything defaults
to ``n`` unless it is ``select``\ ed or explicitly switched on in the
``.mak`` files.  In other words, ``default`` and ``imply`` directives
are disabled.  When QEMU is built with this option, the user will probably
want to change some lines in the first group, for example like this::

   CONFIG_PCI_DEVICES=y
   #CONFIG_TEST_DEVICES=n

and/or pick a subset of the devices in those device groups.  Right now
there is no single place that lists all the optional devices for
``CONFIG_PCI_DEVICES`` and ``CONFIG_TEST_DEVICES``.  In the future,
we expect that ``.mak`` files will be automatically generated, so that
they will include all these symbols and some help text on what they do.

``Kconfig.host``
----------------

In some special cases, a configurable element depends on host features
that are detected by QEMU's configure or ``meson.build`` scripts; for
example some devices depend on the availability of KVM or on the presence
of a library on the host.

These symbols should be listed in ``Kconfig.host`` like this::

    config TPM
      bool

and also listed as follows in the top-level meson.build's host_kconfig
variable::

    host_kconfig = \
      (have_tpm ? ['CONFIG_TPM=y'] : []) + \
      ('CONFIG_LINUX' in config_host ? ['CONFIG_LINUX=y'] : []) + \
      (have_ivshmem ? ['CONFIG_IVSHMEM=y'] : []) + \
      ...