[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH] Kconfig: add documentation
From: |
Paolo Bonzini |
Subject: |
[Qemu-devel] [PATCH] Kconfig: add documentation |
Date: |
Mon, 11 Feb 2019 17:38:29 +0100 |
Signed-off-by: Paolo Bonzini <address@hidden>
---
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
- [Qemu-devel] [PATCH] Kconfig: add documentation,
Paolo Bonzini <=