Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
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 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 component
+defines a Makefile variable whose name starts with ``CONFIG_``.
+
+All elements have boolean (true/false) type; truth is written as ``y``, while
+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 example
+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 ``<expr>``
+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 <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.
+
+**reverse dependencies**: ``select <symbol> [if <expr>]``
+
+ While ``depends on`` can force 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.
+
+ ``<value>`` 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 <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. 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=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. 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=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
On 12/02/2019 09:57, Paolo Bonzini wrote: > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Liam Merwick <liam.merwick@oracle.com> > --- > 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 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 component > +defines a Makefile variable whose name starts with ``CONFIG_``. > + > +All elements have boolean (true/false) type; truth is written as ``y``, while > +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 example > +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 ``<expr>`` > +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 <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. > + > +**reverse dependencies**: ``select <symbol> [if <expr>]`` > + > + While ``depends on`` can force 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. > + > + ``<value>`` 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 <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. 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=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. 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=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) \ > + ... >
On Tue, Feb 12, 2019 at 10:57:49AM +0100, Paolo Bonzini wrote: [...] > +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, (noticed a trivial typo when read...) s/default the/the default/ -- Peter Xu
On Tue, 12 Feb 2019 10:57:49 +0100 Paolo Bonzini <pbonzini@redhat.com> wrote: > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> > --- > docs/devel/kconfig.rst | 305 +++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 305 insertions(+) > create mode 100644 docs/devel/kconfig.rst Looks good! Reviewed-by: Cornelia Huck <cohuck@redhat.com>
© 2016 - 2024 Red Hat, Inc.