[Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini <pbonzini@redhat.com>]

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/devel/kconfig.rst | 284 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 284 insertions(+)
 create mode 100644 docs/devel/kconfig.rst

diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst
new file mode 100644
index 0000000000..b653c43b12
--- /dev/null
+++ b/docs/devel/kconfig.rst
@@ -0,0 +1,284 @@
+Introduction
+------------
+
+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 boards 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 both 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 components
+defines a Makefile variable whose name starts with ``CONFIG_``.
+
+All elements have boolean (true/false) type.  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).
+
+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.
+
+  ``<expr>`` can be an arbitrary Boolean expression.  The ``&&``, ``||`` and ``!``
+  operators are supported, respectively for conjunction (AND), disjunction
+  (OR) and negation (NOT).
+
+**reverse dependencies**: ``select <symbol> [if <expr>]``
+
+  While ``depends on`` forces 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, 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.
+
+  Optionally, a condition for applying the default value can be added with
+  ``if``.  A config option 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 which declare
+their 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**, for example SERIAL
+
+  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, if several targets want to do so.  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 two device groups, ``PCI_DEVICES`` and ``TEST_DEVICES``.  PCI
+  devices usually have a ``default y if PCI_DEVICES`` directive rather than just
+  ``default y``, so that some boards (notably s390) can easily support only VFIO
+  (passthrough) and virtio-pci devices.  ``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 other boards or devices.
+  They are usually enabled with ``select`` and in turn select other elements; they
+  are never visible in ``default-configs/*.mak`` files.
+
+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 default the 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 ``--with-default-devices``
+option.  Doing so disables all the ``default`` and ``imply`` directives.  In this
+case, 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 script; 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 KVM
+      bool
+
+and also listed as follows in the top-level Makefile's ``MINIKCONF_ARGS`` variable::
+
+    MINIKCONF_ARGS = \
+      $@ $*-config.devices.mak.d $< $(MINIKCONF_INPUTS) \
+      CONFIG_KVM=$(CONFIG_KVM) \
+      CONFIG_SPICE=$(CONFIG_SPICE) \
+      CONFIG_TPM=$(CONFIG_TPM) \
+      ...
+
-- 
2.20.1