From nobody Sun Oct 5 03:35:59 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 1551992568926404.4245957163598; Thu, 7 Mar 2019 13:02:48 -0800 (PST) Received: from localhost ([127.0.0.1]:59481 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h20A8-0003t1-RE for importer@patchew.org; Thu, 07 Mar 2019 16:02:44 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38327) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h206Q-0001gl-UV for qemu-devel@nongnu.org; Thu, 07 Mar 2019 15:58:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h206P-0006YG-55 for qemu-devel@nongnu.org; Thu, 07 Mar 2019 15:58:54 -0500 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]:41324) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h206O-0006W7-P5 for qemu-devel@nongnu.org; Thu, 07 Mar 2019 15:58:53 -0500 Received: by mail-wr1-x434.google.com with SMTP id n2so19076554wrw.8 for ; Thu, 07 Mar 2019 12:58:51 -0800 (PST) Received: from donizetti.lan ([2001:b07:6468:f312:c1b:dbd7:15a6:4014]) by smtp.gmail.com with ESMTPSA id h126sm5581833wmf.2.2019.03.07.12.58.48 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2019 12:58:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=+rf1LDArg9Rt+ukIdVVsCaryH8BzsesEqW2muBvxYIM=; b=Qg9rZ7W2uWAomY2W5YBIhs2YEFfuys7l+uJPFGbfYTH7DxsmQ2KJhhvHXGU/MPacRM 8Rqy94Wl0+nTp3duEhdLa9iqy8yl3aWxE/hkbV0ylDQaN1yBn2pjaD3fUh0T+hhzoLbu UTZUKcpYY8/BJKe2fYt4rYOLdU9+ubJ+3vgl1rW0sOmnX4dN1ANbpED4ojk1k4KxArT/ bRBLJKrKoMLkT85VDynHtH5ZXkZVfrpuEy3CxKiW+XrkL3NtIDmYT/PM5vOi0A4Mb07s fpyGfKTKcj99yNEnJj2ApqZeT4Kdt7yZK0TnyzmLLhEOCPhweNtr4QibWfDAn/OLYVsf J6BQ== 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:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=+rf1LDArg9Rt+ukIdVVsCaryH8BzsesEqW2muBvxYIM=; b=r4kEPfchfCiON+vZyDL3Jtu3wiRivayu9j08RpDvD7rxFJe/mOwhDBTOYcERUEnCbt GMNIIUfrvW4df8G0lkSTEwyH0eMDn1vMBJQjF4lR5oNzemHrtrmUt7KjG5PJdF8n03hR I7/UZcrJ0mY9BY0CqhlR3R77x75upTvDnVxFF783sz6NA/1xoeoU4/YtryBrI6zW+oE+ fNQaGcTuuGxYiMANnlJ+x/5b+j5SJxrmmDTKMy/Usmz5BLRetg3TvuXQkz+ZcxLi40Y8 AcVZVbZawfhtnW3Rm07KZ8gYQZEa/cyvWagLHxxLa0o+mTxSAdjN61Giqr0ypPyf9x0u wYgg== X-Gm-Message-State: APjAAAWdCHgqIXzHpSK4wQvqoEDttbGCMIAJwIHMgKvJwc2jOvlFPy3o Q4U9pJMxHq1nXcyqs7Ui4l95m+H+ X-Google-Smtp-Source: APXvYqyvsvhLC7nQUvr75lmdrBuRIiZwOGt0zuSUsWWtOw+7C7h8DfLen1Bl+uekAu67kRK3WugaXw== X-Received: by 2002:a5d:4a05:: with SMTP id m5mr8707865wrq.46.1551992329871; Thu, 07 Mar 2019 12:58:49 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Thu, 7 Mar 2019 21:58:44 +0100 Message-Id: <20190307205844.20236-3-pbonzini@redhat.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190307205844.20236-1-pbonzini@redhat.com> References: <20190307205844.20236-1-pbonzini@redhat.com> 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::434 Subject: [Qemu-devel] [PULL v3 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: , 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 --- docs/devel/index.rst | 1 + docs/devel/kconfig.rst | 306 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 docs/devel/kconfig.rst diff --git a/docs/devel/index.rst b/docs/devel/index.rst index cd0fa6c9ba..6b11e49caa 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -13,6 +13,7 @@ Contents: .. toctree:: :maxdepth: 2 =20 + kconfig loads-stores memory migration diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst new file mode 100644 index 0000000000..cce146f87d --- /dev/null +++ b/docs/devel/kconfig.rst @@ -0,0 +1,306 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU and Kconfig +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 2.20.1