diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 216 | ||||
| -rw-r--r-- | docs/cpu-hotplug.rst | 2 | ||||
| -rw-r--r-- | docs/devel/build-system.txt | 1 | ||||
| -rw-r--r-- | docs/devel/conf.py | 15 | ||||
| -rw-r--r-- | docs/devel/index.rst | 22 | ||||
| -rw-r--r-- | docs/devel/kconfig.rst | 306 | ||||
| -rw-r--r-- | docs/devel/memory.rst (renamed from docs/devel/memory.txt) | 132 | ||||
| -rw-r--r-- | docs/devel/testing.rst | 42 | ||||
| -rw-r--r-- | docs/index.rst | 15 | ||||
| -rw-r--r-- | docs/interop/conf.py | 15 | ||||
| -rw-r--r-- | docs/interop/index.rst | 18 |
11 files changed, 720 insertions, 64 deletions
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..befbcc6c3e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file, created by +# sphinx-quickstart on Thu Jan 31 16:40:14 2019. +# +# This config file can be used in one of two ways: +# (1) as a common config file which is included by the conf.py +# for each of QEMU's manuals: in this case sphinx-build is run multiple +# times, once per subdirectory. +# (2) as a top level conf file which will result in building all +# the manuals into a single document: in this case sphinx-build is +# run once, on the top-level docs directory. +# +# QEMU's makefiles take option (1), which allows us to install +# only the ones the user cares about (in particular we don't want +# to ship the 'devel' manual to end-users). +# Third-party sites such as readthedocs.org will take option (2). +# +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +import sys + +# The per-manual conf.py will set qemu_docdir for a single-manual build; +# otherwise set it here if this is an entire-manual-set build. +# This is always the absolute path of the docs/ directory in the source tree. +try: + qemu_docdir +except NameError: + qemu_docdir = os.path.abspath(".") + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use an absolute path starting from qemu_docdir. +# +# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# 1.3 is where the 'alabaster' theme was shipped with Sphinx. +needs_sphinx = '1.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'QEMU' +copyright = u'2019, The QEMU Project Developers' +author = u'The QEMU Project Developers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# Extract this information from the VERSION file, for the benefit of +# standalone Sphinx runs as used by readthedocs.org. Builds run from +# the Makefile will pass version and release on the sphinx-build +# command line, which override this. +try: + extracted_version = None + with open(os.path.join(qemu_docdir, '../VERSION')) as f: + extracted_version = f.readline().strip() +except: + pass +finally: + if extracted_version: + version = release = extracted_version + else: + version = release = "unknown version" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# Sphinx defaults to warning about use of :option: for options not defined +# with "option::" in the document being processed. Turn that off. +suppress_warnings = ["ref.option"] + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# We initialize this to empty here, so the per-manual conf.py can just +# add individual key/value entries. +html_theme_options = { +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# QEMU doesn't yet have any static files, so comment this out so we don't +# get a warning about a missing directory. +# If we do ever add this then it would probably be better to call the +# subdirectory sphinx_static, as the Linux kernel does. +# html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'searchbox.html', + ] +} + +# Don't copy the rST source files to the HTML output directory, +# and don't put links to the sources into the output HTML. +html_copy_source = False + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'QEMUdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'QEMU.tex', u'QEMU Documentation', + u'The QEMU Project Developers', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'qemu', u'QEMU Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'QEMU', u'QEMU Documentation', + author, 'QEMU', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst index cfeb79f571..d0b06403f1 100644 --- a/docs/cpu-hotplug.rst +++ b/docs/cpu-hotplug.rst @@ -60,7 +60,7 @@ vCPU hotplug hot-plugged (no "qom-path" member). From its output in step (3), we can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, while hot-plugging a CPU into socket 1 requires passing the listed - properties to QMP ``device_add``: + properties to QMP ``device_add``:: (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0 { diff --git a/docs/devel/build-system.txt b/docs/devel/build-system.txt index f9fd27fab0..addd274eeb 100644 --- a/docs/devel/build-system.txt +++ b/docs/devel/build-system.txt @@ -417,7 +417,6 @@ into each QEMU system and userspace emulator targets. They merely contain a long list of config variable definitions. For example, default-configs/x86_64-softmmu.mak has: - include pci.mak include sound.mak include usb.mak CONFIG_QXL=$(CONFIG_SPICE) diff --git a/docs/devel/conf.py b/docs/devel/conf.py new file mode 100644 index 0000000000..7441f87e7f --- /dev/null +++ b/docs/devel/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'devel' manual. +# +# This includes the top level conf file and then makes any necessary tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] = u'Developer''s Guide' diff --git a/docs/devel/index.rst b/docs/devel/index.rst new file mode 100644 index 0000000000..6b11e49caa --- /dev/null +++ b/docs/devel/index.rst @@ -0,0 +1,22 @@ +.. This is the top level page for the 'devel' manual. + + +QEMU Developer's Guide +====================== + +This manual documents various parts of the internals of QEMU. +You only need to read it if you are interested in reading or +modifying QEMU's source code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + kconfig + loads-stores + memory + migration + stable-process + testing + 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 @@ +================ +QEMU and Kconfig +================ + +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's Kconfig implementation, 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 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 <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 +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=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) \ + ... diff --git a/docs/devel/memory.txt b/docs/devel/memory.rst index 42577e1d86..b6a4c37ea5 100644 --- a/docs/devel/memory.txt +++ b/docs/devel/memory.rst @@ -1,19 +1,20 @@ +============== The memory API ============== The memory API models the memory and I/O buses and controllers of a QEMU machine. It attempts to allow modelling of: - - ordinary RAM - - memory-mapped I/O (MMIO) - - memory controllers that can dynamically reroute physical memory regions - to different destinations +- ordinary RAM +- memory-mapped I/O (MMIO) +- memory controllers that can dynamically reroute physical memory regions + to different destinations The memory model provides support for - - tracking RAM changes by the guest - - setting up coalesced memory for kvm - - setting up ioeventfd regions for kvm +- tracking RAM changes by the guest +- setting up coalesced memory for kvm +- setting up ioeventfd regions for kvm Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks (leaves) are RAM and MMIO regions, while other nodes represent @@ -98,25 +99,30 @@ ROM device memory region types), this host memory needs to be copied to the destination on migration. These APIs which allocate the host memory for you will also register the memory so it is migrated: - - memory_region_init_ram() - - memory_region_init_rom() - - memory_region_init_rom_device() + +- memory_region_init_ram() +- memory_region_init_rom() +- memory_region_init_rom_device() For most devices and boards this is the correct thing. If you have a special case where you need to manage the migration of the backing memory yourself, you can call the functions: - - memory_region_init_ram_nomigrate() - - memory_region_init_rom_nomigrate() - - memory_region_init_rom_device_nomigrate() + +- memory_region_init_ram_nomigrate() +- memory_region_init_rom_nomigrate() +- memory_region_init_rom_device_nomigrate() + which only initialize the MemoryRegion and leave handling migration to the caller. The functions: - - memory_region_init_resizeable_ram() - - memory_region_init_ram_from_file() - - memory_region_init_ram_from_fd() - - memory_region_init_ram_ptr() - - memory_region_init_ram_device_ptr() + +- memory_region_init_resizeable_ram() +- memory_region_init_ram_from_file() +- memory_region_init_ram_from_fd() +- memory_region_init_ram_ptr() +- memory_region_init_ram_device_ptr() + are for special cases only, and so they do not automatically register the backing memory for migration; the caller must manage migration if necessary. @@ -218,7 +224,7 @@ For example, suppose we have a container A of size 0x8000 with two subregions B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at -offset 0x2000. As a diagram: +offset 0x2000. As a diagram:: 0 1000 2000 3000 4000 5000 6000 7000 8000 |------|------|------|------|------|------|------|------| @@ -228,8 +234,9 @@ offset 0x2000. As a diagram: D: [DDDDD] E: [EEEEE] -The regions that will be seen within this address range then are: - [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] +The regions that will be seen within this address range then are:: + + [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] Since B has higher priority than C, its subregions appear in the flat map even where they overlap with C. In ranges where B has not mapped anything @@ -237,8 +244,9 @@ C's region appears. If B had provided its own MMIO operations (ie it was not a pure container) then these would be used for any addresses in its range not handled by -D or E, and the result would be: - [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] +D or E, and the result would be:: + + [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] Priority values are local to a container, because the priorities of two regions are only compared when they are both children of the same container. @@ -257,6 +265,7 @@ guest accesses an address: - all direct subregions of the root region are matched against the address, in descending priority order + - if the address lies outside the region offset/size, the subregion is discarded - if the subregion is a leaf (RAM or MMIO), the search terminates, returning @@ -270,36 +279,39 @@ guest accesses an address: address range), then if this is a container with its own MMIO or RAM backing the search terminates, returning the container itself. Otherwise we continue with the next subregion in priority order + - if none of the subregions match the address then the search terminates with no match found Example memory map ------------------ -system_memory: container@0-2^48-1 - | - +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) - | - +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) - | - +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) - | (prio 1) - | - +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) - -pci (0-2^32-1) - | - +--- vga-area: container@0xa0000-0xbffff - | | - | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) - | | - | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) - | - +---- vram: ram@0xe1000000-0xe1ffffff - | - +---- vga-mmio: mmio@0xe2000000-0xe200ffff - -ram: ram@0x00000000-0xffffffff +:: + + system_memory: container@0-2^48-1 + | + +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) + | + +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) + | + +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) + | (prio 1) + | + +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) + + pci (0-2^32-1) + | + +--- vga-area: container@0xa0000-0xbffff + | | + | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) + | | + | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) + | + +---- vram: ram@0xe1000000-0xe1ffffff + | + +---- vga-mmio: mmio@0xe2000000-0xe200ffff + + ram: ram@0x00000000-0xffffffff This is a (simplified) PC memory map. The 4GB RAM block is mapped into the system address space via two aliases: "lomem" is a 1:1 mapping of the first @@ -336,16 +348,16 @@ rather than completing successfully; those devices can use the In addition various constraints can be supplied to control how these callbacks are called: - - .valid.min_access_size, .valid.max_access_size define the access sizes - (in bytes) which the device accepts; accesses outside this range will - have device and bus specific behaviour (ignored, or machine check) - - .valid.unaligned specifies that the *device being modelled* supports - unaligned accesses; if false, unaligned accesses will invoke the - appropriate bus or CPU specific behaviour. - - .impl.min_access_size, .impl.max_access_size define the access sizes - (in bytes) supported by the *implementation*; other access sizes will be - emulated using the ones available. For example a 4-byte write will be - emulated using four 1-byte writes, if .impl.max_access_size = 1. - - .impl.unaligned specifies that the *implementation* supports unaligned - accesses; if false, unaligned accesses will be emulated by two aligned - accesses. +- .valid.min_access_size, .valid.max_access_size define the access sizes + (in bytes) which the device accepts; accesses outside this range will + have device and bus specific behaviour (ignored, or machine check) +- .valid.unaligned specifies that the *device being modelled* supports + unaligned accesses; if false, unaligned accesses will invoke the + appropriate bus or CPU specific behaviour. +- .impl.min_access_size, .impl.max_access_size define the access sizes + (in bytes) supported by the *implementation*; other access sizes will be + emulated using the ones available. For example a 4-byte write will be + emulated using four 1-byte writes, if .impl.max_access_size = 1. +- .impl.unaligned specifies that the *implementation* supports unaligned + accesses; if false, unaligned accesses will be emulated by two aligned + accesses. diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 135743a2bf..60f897d915 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -600,7 +600,6 @@ the ``avocado_qemu.Test`` class. Here's a simple usage example: class Version(Test): """ - :avocado: enable :avocado: tags=quick """ def test_qmp_human_info_version(self): @@ -634,7 +633,46 @@ instance, available at ``self.vm``. Because many tests will tweak the QEMU command line, launching the QEMUMachine (by using ``self.vm.launch()``) is left to the test writer. -At test "tear down", ``avocado_qemu.Test`` handles the QEMUMachine +The base test class has also support for tests with more than one +QEMUMachine. The way to get machines is through the ``self.get_vm()`` +method which will return a QEMUMachine instance. The ``self.get_vm()`` +method accepts arguments that will be passed to the QEMUMachine creation +and also an optional `name` attribute so you can identify a specific +machine and get it more than once through the tests methods. A simple +and hypothetical example follows: + +.. code:: + + from avocado_qemu import Test + + + class MultipleMachines(Test): + """ + :avocado: enable + """ + def test_multiple_machines(self): + first_machine = self.get_vm() + second_machine = self.get_vm() + self.get_vm(name='third_machine').launch() + + first_machine.launch() + second_machine.launch() + + first_res = first_machine.command( + 'human-monitor-command', + command_line='info version') + + second_res = second_machine.command( + 'human-monitor-command', + command_line='info version') + + third_res = self.get_vm(name='third_machine').command( + 'human-monitor-command', + command_line='info version') + + self.assertEquals(first_res, second_res, third_res) + +At test "tear down", ``avocado_qemu.Test`` handles all the QEMUMachines shutdown. QEMUMachine diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..3690955dd1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,15 @@ +.. QEMU documentation master file, created by + sphinx-quickstart on Thu Jan 31 16:40:14 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to QEMU's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + interop/index + devel/index + diff --git a/docs/interop/conf.py b/docs/interop/conf.py new file mode 100644 index 0000000000..cf3c69d4a7 --- /dev/null +++ b/docs/interop/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'interop' manual. +# +# This includes the top level conf file and then makes any necessary tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] = u'System Emulation Management and Interoperability Guide' diff --git a/docs/interop/index.rst b/docs/interop/index.rst new file mode 100644 index 0000000000..2df977dd52 --- /dev/null +++ b/docs/interop/index.rst @@ -0,0 +1,18 @@ +.. This is the top level page for the 'interop' manual. + + +QEMU System Emulation Management and Interoperability Guide +=========================================================== + +This manual contains documents and specifications that are useful +for making QEMU interoperate with other software. + +Contents: + +.. toctree:: + :maxdepth: 2 + + bitmaps + live-block-operations + pr-helper + |