On Mon, 11 Feb 2019 17:38:29 +0100 Paolo Bonzini <pbonz...@redhat.com> wrote:
> Signed-off-by: Paolo Bonzini <pbonz...@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.
