From nobody Sun Oct 5 01:46:25 2025 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 1551729147463854.8813885438911; Mon, 4 Mar 2019 11:52:27 -0800 (PST) Received: from localhost ([127.0.0.1]:59986 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0tdL-0003gG-Q3 for importer@patchew.org; Mon, 04 Mar 2019 14:52:19 -0500 Received: from eggs.gnu.org ([209.51.188.92]:46513) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0sDE-0002am-QN for qemu-devel@nongnu.org; Mon, 04 Mar 2019 13:21:18 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h0sDC-0005J9-MT for qemu-devel@nongnu.org; Mon, 04 Mar 2019 13:21:16 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:45480) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h0sD9-00058w-Ea for qemu-devel@nongnu.org; Mon, 04 Mar 2019 13:21:11 -0500 Received: by mail-wr1-x42f.google.com with SMTP id w17so6627752wrn.12 for ; Mon, 04 Mar 2019 10:21:07 -0800 (PST) Received: from 640k.lan ([93.56.166.5]) by smtp.gmail.com with ESMTPSA id q5sm8371364wrn.43.2019.03.04.10.21.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 04 Mar 2019 10:21:06 -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:in-reply-to:references; bh=c8MBxh0TvUsXJW3IaRTdLId6t6GlV1PR4IInMtg/35A=; b=FlVAv0BgVaTBqmBHXwK5RDxLZQaCY6WF4lYmx0q+l+6Va9J33vcAfc1pwLMg6GIUgR 1PafXOcNm5DfCWH9fuLV4/7+sGKKDczVHezhhbM/FSgYyf9k9aJqE1Qm3h+7VMh9yb6Z Km+aUVxwWwF5IM4cNaLuHLwxOoKgWVnarzb49EvJSqT+Xye/DOW3/pjKxUrm+kteyGuU mdTlur+ayUy90k7YdTtz+DabkhvB5Bj+gUvBfZFGjisCEEhwZvtNdcb+sQRuPHrPBS3t PCbtWwOk5siyx0QhCDD50EHyZcl5H9llthgmOl9HBuKMowheA8FgLrffjBbWn6K5uU94 oMCQ== 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 :in-reply-to:references; bh=c8MBxh0TvUsXJW3IaRTdLId6t6GlV1PR4IInMtg/35A=; b=C7jkMUAB/bF1bhiQF4j+ELCg7t9ByFoGnuOjdNvLIS9zOPAniTkFdPztjlO7Ga4L9b Y5QJG6+Wq5lZdkltZPDcjrdrJ52fTqztDvGXb2PEAx6zVX4xHn0qeG/DyFIMx/bBltNg s3stOoq1MvP/rxNZBpRGWHV11KhE1BgYRvA/T+HZFCpM6OpOWlkoSlIJy7fRcueTWsg5 OlOl/W8mzbI6MbhlgoH3Lu1U6UCYDE2E3D4TY7QSlgsT8+QowyFdIQmM/RRpSvL26MOa UlbJsapcrap+rGJ4ICLIKvDCi9jrGU8eJr4q27EyDTZ3C+WqU2RvjTwqj0t9dPicB+sR jGxA== X-Gm-Message-State: APjAAAWEXiIT6Qt8QQifoyo3jGJczYHvfzIZroPTmTfvYEpwPcyv5Nzv 2WYf8ymOLz8PmHJUr4qRQUqPWLMp X-Google-Smtp-Source: APXvYqxhVqIzzwQxLxjJXKmem6VGygR1GTL/b7KRiYhfWnaQu3OUZ6AiRH4i3lAQS6S8H8/9sJKsZA== X-Received: by 2002:adf:e8cf:: with SMTP id k15mr13030937wrn.193.1551723666584; Mon, 04 Mar 2019 10:21:06 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Mon, 4 Mar 2019 19:20:14 +0100 Message-Id: <1551723614-1823-55-git-send-email-pbonzini@redhat.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1551723614-1823-1-git-send-email-pbonzini@redhat.com> References: <1551723614-1823-1-git-send-email-pbonzini@redhat.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42f Subject: [Qemu-devel] [PULL 54/54] 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: Yang Zhong , thuth@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-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Paolo Bonzini --- 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 0000000..0f84522 --- /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's Kconfig implementation, QEMU will detect + contradictions between ``depends on`` and ``select`` statements and prev= ent + 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 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 [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 +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 +``--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 1.8.3.1