Signed-off-by: Paolo Bonzini <pbonz...@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