From nobody Sun May 19 19:01:00 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1549966276027447.6577361471832; Tue, 12 Feb 2019 02:11:16 -0800 (PST) Received: from localhost ([127.0.0.1]:36646 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gtV1y-0004Or-W6 for importer@patchew.org; Tue, 12 Feb 2019 05:11:11 -0500 Received: from eggs.gnu.org ([209.51.188.92]:53607) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gtUzG-0002Kn-K3 for qemu-devel@nongnu.org; Tue, 12 Feb 2019 05:08:26 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gtUpF-00051I-6A for qemu-devel@nongnu.org; Tue, 12 Feb 2019 04:58:03 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:35179) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gtUpE-0004qc-Qh for qemu-devel@nongnu.org; Tue, 12 Feb 2019 04:58:01 -0500 Received: by mail-wr1-x442.google.com with SMTP id t18so1964837wrx.2 for ; Tue, 12 Feb 2019 01:57:52 -0800 (PST) Received: from localhost.localdomain ([2001:b07:6468:f312:942c:94db:9853:9c8f]) by smtp.gmail.com with ESMTPSA id y20sm27701669wra.51.2019.02.12.01.57.49 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 12 Feb 2019 01:57:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=AQ/CkJkJuMspBA6S2VI2fO2H55YJHRy+3tPtIfUntyI=; b=JXKP2PUJFif+9Jufa9wYKnhsNNgtx3iYZr/D6C983RHYekGQtMZ73fugBzSoU/MOf/ 0bjqMIcAUxzntewhl35DsnRLxiAbCpLYX8Xm0L741rgIPQ0kD9kOgB0RCznzgjPoftxL AR+GRrij0rKZ/ZapLcGrXkMQtNMqx8XSTvBDUNlwR4nEKXnF14duB5/lnXQc5KpHTSPY uZN2H2gTMmRLrDxFAZR4wkZ3gTa9+dg1oktrgVczC9I0W82/yXzig6eA17KtZz8nX2gN M09V+5QQ1rViS1oyBFxImfg6/azHFn4Ir64WkhJsv6twcDV2lAONREnB95YkrCJXYHYQ wq/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :mime-version:content-transfer-encoding; bh=AQ/CkJkJuMspBA6S2VI2fO2H55YJHRy+3tPtIfUntyI=; b=IhRhJTXoC0fqVek2d/JQHMg0jy22Qlriuy2cKqO5bufBb0ZpdmL0rwxhYRzBET8hy+ Ciyr2NycRXq9s5F2pD/cFfy4MC7dBOgH5cjeLZgPk0bpaaljc8o5xyx1IzWvnPP6nT6j 1TMAJmP3FVLM/zMHR4HzvBC/Av/afXhwu0bsFXuc9CQrL4/AylMtLQBH3n842fYGEvAz Cf3xOPvSiZa0K7+4aOkcyiS1usoOFr3jPsKDXNV4SHIqfsDtQIoT6k7LPK810hFnf2in OzEeFstTGNrmccGH52YnmJzfR8hq2PsUjuZhrzbyV08NQLYlsXt05RctoCgOVY0EG1VI yI/A== X-Gm-Message-State: AHQUAuZRtKfcjqDpb06LEqMjAxGYlPSxcXFMOdWsCdKWdQiJFQJcLqJN qxieIYbTMYtlbvhknqavlOwEpJo/ X-Google-Smtp-Source: AHgI3IbSFUk/Oo4j6VbsGvPuuKPutQ/zOlyKApmes7BKe8JZIq+4L8BO7rm2AC0wP8C9lCXo3/HH0A== X-Received: by 2002:adf:afce:: with SMTP id y14mr1729439wrd.219.1549965470976; Tue, 12 Feb 2019 01:57:50 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Tue, 12 Feb 2019 10:57:49 +0100 Message-Id: <20190212095749.20313-1-pbonzini@redhat.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 Subject: [Qemu-devel] [PATCH v2] Kconfig: add documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org, thuth@redhat.com, cohuck@redhat.com, Mark Cave-Ayland , armbru@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Signed-off-by: Paolo Bonzini Reviewed-by: Cornelia Huck Reviewed-by: Liam Merwick --- docs/devel/kconfig.rst | 305 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 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..ff1ed3d1b2 --- /dev/null +++ b/docs/devel/kconfig.rst @@ -0,0 +1,305 @@ +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 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 subs= et + 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 preproces= sor +symbols; they are only visible in the Makefile. Each configurable compone= nt +defines a Makefile variable whose name starts with ``CONFIG_``. + +All elements have boolean (true/false) type; truth is written as ``y``, wh= ile +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 exa= mple +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 ```` +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 `` + + 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 [if ]`` + + While ``depends on`` can force a symbol to false, reverse dependencies c= an + 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 [if ]`` + + 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. + + ```` 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 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 [if = ]`` + + 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 two device groups, ``PCI_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. + ``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=3Dn + #CONFIG_TEST_DEVICES=3Dn + + # Boards: + # + CONFIG_DP264=3Dy + +The first part, consisting of commented-out ``=3Dn`` assignments, tells +the user which devices or device groups are implied by the boards. +The second part, consisting of ``=3Dy`` 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. 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=3Dy + #CONFIG_TEST_DEVICES=3Dn + +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 =3D \ + $@ $*-config.devices.mak.d $< $(MINIKCONF_INPUTS) \ + CONFIG_KVM=3D$(CONFIG_KVM) \ + CONFIG_SPICE=3D$(CONFIG_SPICE) \ + CONFIG_TPM=3D$(CONFIG_TPM) \ + ... --=20 2.20.1