[Qemu-devel] [PATCH] Kconfig: add documentation

[Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini]

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

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Cornelia Huck]

On Mon, 11 Feb 2019 17:38:29 +0100
Paolo Bonzini <pbonzini@redhat.com> wrote:

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

s/x86 boards/x86 board/

> +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

s/can both/can all/

> +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;

Is this a stray semicolon, or is something else supposed to follow?

Both points feature full sentences, so I think they should start with a
capital letter?

> +
> +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.

So this is only about devices and friends, and not about cpu features
etc.?

> +
> +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

s/components/component/

> +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).

That seems to be true for any of the <expr> below as well. Maybe
specify it further up instead?

> +
> +**reverse dependencies**: ``select <symbol> [if <expr>]``
> +
> +  While ``depends on`` forces a symbol to false, reverse dependencies can be

s/forces/can force/

> +  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

It reads a bit odd that you first pick one example, and then show a
completely different one :)

> +
> +  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

Maybe replace "if several targets want to do so" with "This is useful
when a set of devices is likely to be enabled/disabled by several
targets." ?

> +  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

s/support only/support only e.g./ ?

> +  (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.

s/several other/several/ ?

> +  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

I find that sentence a bit confusing. Does it mean that everything
defaults to 'n' that is not explicitly switched on? Maybe an example
would help...

> +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) \
> +      ...
> +

Mostly some nitpicking from me; on the whole, I think that's useful
information.

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini]

On 11/02/19 18:17, Cornelia Huck wrote:
>> +
>> +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.
> So this is only about devices and friends, and not about cpu features
> etc.?
> 

For now it is...  Ideas are welcome on extensions to the mechanism; for
now it is only about what default-configs/ has always covered, just
better. :)

Paolo

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 378 bytes --]

On Mon, Feb 11, 2019 at 05:38:29PM +0100, Paolo Bonzini wrote:
> +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

s/components/component/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Markus Armbruster]

Paolo Bonzini <pbonzini@redhat.com> writes:

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

Please wrap your lines at column 70 or so.  Humans tend to have trouble
following long lines with their eyes (I sure do).  Typographic manuals
suggest to limit columns to roughly 60 characters for exactly that
reason[*].

> +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

Really?  Hmm...

$ size aarch64-softmmu/qemu-system-aarch64
   text	   data	    bss	    dec	    hex	filename
19183216	7200124	 592732	26976072	19b9f48	aarch64-softmmu/qemu-system-aarch64
$ size -t `find -name \*.o `| grep TOT
92713559	18652227	1183961440	1295327226	4d351ffa	(TOTALS)

Yep, really.

> +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.

Hmm.  Is "multiple default values, first one wins" a healthy state?
How obvious is "first defined" to humans?  

> +
> +**reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``

If "reverse default" can be regarded as weak reverse dependency, could
"default value" be regarded as weak (forward) dependency?

> +
> +  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

I'm afraid I don't get "lower limit".  What's the ordering relation?

> +  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
> +------------------------------------
[...]

Good work, I like it!


[*] https://en.wikipedia.org/wiki/Column_(typography)#Typographic_style

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini]

On 12/02/19 10:08, Markus Armbruster wrote:
> Please wrap your lines at column 70 or so.  Humans tend to have trouble
> following long lines with their eyes (I sure do).  Typographic manuals
> suggest to limit columns to roughly 60 characters for exactly that
> reason[*].

Yup, fixed in v2.

>> +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
> 
> Really?  Hmm...
> 
> $ size aarch64-softmmu/qemu-system-aarch64
>    text	   data	    bss	    dec	    hex	filename
> 19183216	7200124	 592732	26976072	19b9f48	aarch64-softmmu/qemu-system-aarch64
> $ size -t `find -name \*.o `| grep TOT
> 92713559	18652227	1183961440	1295327226	4d351ffa	(TOTALS)
> 
> Yep, really.

Haha. :)

>> +  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.
> 
> Hmm.  Is "multiple default values, first one wins" a healthy state?
> How obvious is "first defined" to humans?  

It certainly helps that we never have more than one default. :)

I could also be persuaded to remove "default n", so that multiple
"default y" clauses are just an OR of the conditions and the ordering
does not matter.

Are multiple "default y" clauses useful?  They were there in earlier
versions of the patches, for now "imply" has removed the need
everywhere.  However, I'm not sure it's a good idea to remove them
altogether before we try to extend Kconfig to more features.  (A
secondary effect of the documentation is to clarify the current scope of
Kconfig).

>> +**reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``
> 
> If "reverse default" can be regarded as weak reverse dependency, could
> "default value" be regarded as weak (forward) dependency?

"default n if" could, but we never use it.  This also shows how we use
the language in a very limited way, according to the very simple rules
in the second part of the document; but even Linux only has a handful of
occurrences of "default n 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
> 
> I'm afraid I don't get "lower limit".  What's the ordering relation?

False < true, so "lower limit of y" means "tries to force to y".  The
difference is that a contradiction is ignored by "imply" (and then the
symbol remains at n), while it causes a build error for "select".

Paolo

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Markus Armbruster]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 12/02/19 10:08, Markus Armbruster wrote:
>> Please wrap your lines at column 70 or so.  Humans tend to have trouble
>> following long lines with their eyes (I sure do).  Typographic manuals
>> suggest to limit columns to roughly 60 characters for exactly that
>> reason[*].
>
> Yup, fixed in v2.
>
>>> +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
>> 
>> Really?  Hmm...
>> 
>> $ size aarch64-softmmu/qemu-system-aarch64
>>    text	   data	    bss	    dec	    hex	filename
>> 19183216	7200124	 592732	26976072	19b9f48	aarch64-softmmu/qemu-system-aarch64
>> $ size -t `find -name \*.o `| grep TOT
>> 92713559	18652227	1183961440	1295327226	4d351ffa	(TOTALS)
>> 
>> Yep, really.
>
> Haha. :)
>
>>> +  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.
>> 
>> Hmm.  Is "multiple default values, first one wins" a healthy state?
>> How obvious is "first defined" to humans?  
>
> It certainly helps that we never have more than one default. :)

True!

> I could also be persuaded to remove "default n", so that multiple
> "default y" clauses are just an OR of the conditions and the ordering
> does not matter.

I'm looking for something that doesn't involve too much global
reasoning.

"All default directives must provide the same value; their conditions
are ORed" feels fine to me.  Order doesn't matter then.  "if <expr>"
really means "if", not "if-and-only-if", and that's fine.

Additionally permitting an *unconditional* default with the negated
value would still be okay, I guess.  But I'd do that only when we have a
use.

> Are multiple "default y" clauses useful?  They were there in earlier
> versions of the patches, for now "imply" has removed the need
> everywhere.  However, I'm not sure it's a good idea to remove them
> altogether before we try to extend Kconfig to more features.  (A
> secondary effect of the documentation is to clarify the current scope of
> Kconfig).

My general advice would be YAGNI.  However, keeping currently unused
features around while we grow Kconfig makes sense to me.

>>> +**reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``
>> 
>> If "reverse default" can be regarded as weak reverse dependency, could
>> "default value" be regarded as weak (forward) dependency?
>
> "default n if" could, but we never use it.  This also shows how we use
> the language in a very limited way, according to the very simple rules
> in the second part of the document; but even Linux only has a handful of
> occurrences of "default n 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
>> 
>> I'm afraid I don't get "lower limit".  What's the ordering relation?
>
> False < true, so "lower limit of y" means "tries to force to y".  The
> difference is that a contradiction is ignored by "imply" (and then the
> symbol remains at n), while it causes a build error for "select".

Can we use this explanation to rephrase the documentation in simpler
language?

Let me summarize to see whether I got it.  Please correct
misunderstandings.

* "depends on" forces to false unless condition is met

* "select" forces to true if condition is met

* Contradictions between "depends on" and "select" are rejected

* If neither applies, default-configs/*.mak may supply the value

* If it doesn't, "default" / "imply" supply the value if condition is
  met

* What about contradictions between "default" / "imply"?


PS: Thanks for writing down intended use in "Guidelines for writing
Kconfig files", not just the language specification, makes the document
so much more useful.

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini]

On 13/02/19 08:45, Markus Armbruster wrote:
> * If it doesn't, "default" / "imply" supply the value if condition is
>   met
> 
> * What about contradictions between "default" / "imply"?

We would avoid those by forbidding "default n", then "imply" would also
be just another "default y".  I'm quite sold on only having "default y"
lines (which then are easily ORed among themselves and with "imply" lines).

Paolo

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Thomas Huth]

On 2019-02-11 17:38, Paolo Bonzini wrote:
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  docs/devel/kconfig.rst | 284 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 284 insertions(+)
>  create mode 100644 docs/devel/kconfig.rst

Thanks for writing this up - that's a really helpful text!

> 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 @@
[...]
> +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.

I'd like to suggest to replace "Linux" with "Linux-Kconfig".

[...]
> +**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

dito

 Thomas

Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Paolo Bonzini]

On 12/02/19 10:13, Thomas Huth wrote:
>> +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.
> I'd like to suggest to replace "Linux" with "Linux-Kconfig".

Here I think it's really Linux vs. QEMU, not Linux-Kconfig versus
minikconf.  However...

> [...]
>> +**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
> dito

...  I'll do the replacement you suggest here.

Paolo