From 4ed2ab47ab39de39f9753074b79303638dac020d Mon Sep 17 00:00:00 2001 From: zhanghailiang Date: Wed, 17 Jul 2019 09:51:03 +0800 Subject: [PATCH] Revert "Enable build and install of our rST docs" --- .gitignore | 1 - MAINTAINERS | 6 - Makefile | 88 +++--------- configure | 15 +- docs/conf.py | 216 ----------------------------- docs/cpu-hotplug.rst | 2 +- docs/devel/conf.py | 15 -- docs/devel/index.rst | 22 --- docs/devel/memory.rst | 363 ------------------------------------------------- docs/devel/memory.txt | 351 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 15 -- docs/interop/conf.py | 15 -- docs/interop/index.rst | 18 --- 13 files changed, 374 insertions(+), 753 deletions(-) delete mode 100644 docs/conf.py delete mode 100644 docs/devel/conf.py delete mode 100644 docs/devel/index.rst delete mode 100644 docs/devel/memory.rst create mode 100644 docs/devel/memory.txt delete mode 100644 docs/index.rst delete mode 100644 docs/interop/conf.py delete mode 100644 docs/interop/index.rst diff --git a/.gitignore b/.gitignore index 8f78221..7385d5c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ -/.doctrees /config-devices.* /config-all-devices.* /config-all-disas.* diff --git a/MAINTAINERS b/MAINTAINERS index 56139ac..a162586 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2586,9 +2586,3 @@ GIT submodules M: Daniel P. Berrange S: Odd Fixes F: scripts/git-submodule.sh - -Sphinx documentation configuration and build machinery -M: Peter Maydell -S: Maintained -F: docs/conf.py -F: docs/*/conf.py diff --git a/Makefile b/Makefile index 04a0d45..d1e465f 100644 --- a/Makefile +++ b/Makefile @@ -87,20 +87,6 @@ endif include $(SRC_PATH)/rules.mak -# Create QEMU_PKGVERSION and FULL_VERSION strings -# If PKGVERSION is set, use that; otherwise get version and -dirty status from git -QEMU_PKGVERSION := $(if $(PKGVERSION),$(PKGVERSION),$(shell \ - cd $(SRC_PATH); \ - if test -e .git; then \ - git describe --match 'v*' 2>/dev/null | tr -d '\n'; \ - if ! git diff-index --quiet HEAD &>/dev/null; then \ - echo "-dirty"; \ - fi; \ - fi)) - -# Either "version (pkgversion)", or just "version" if pkgversion not set -FULL_VERSION := $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),$(VERSION)) - GENERATED_FILES = qemu-version.h config-host.h qemu-options.def GENERATED_QAPI_FILES = qapi/qapi-builtin-types.h qapi/qapi-builtin-types.c @@ -419,12 +405,27 @@ dummy := $(call unnest-vars,, \ include $(SRC_PATH)/tests/Makefile.include -all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules qemu-version.h: FORCE $(call quiet-command, \ - (printf '#define QEMU_PKGVERSION "$(QEMU_PKGVERSION)"\n'; \ - printf '#define QEMU_FULL_VERSION "$(FULL_VERSION)"\n'; \ + (cd $(SRC_PATH); \ + if test -n "$(PKGVERSION)"; then \ + pkgvers="$(PKGVERSION)"; \ + else \ + if test -d .git; then \ + pkgvers=$$(git describe --match 'v*' 2>/dev/null | tr -d '\n');\ + if ! git diff-index --quiet HEAD &>/dev/null; then \ + pkgvers="$${pkgvers}-dirty"; \ + fi; \ + fi; \ + fi; \ + printf "#define QEMU_PKGVERSION \"$${pkgvers}\"\n"; \ + if test -n "$${pkgvers}"; then \ + printf '#define QEMU_FULL_VERSION QEMU_VERSION " (" QEMU_PKGVERSION ")"\n'; \ + else \ + printf '#define QEMU_FULL_VERSION QEMU_VERSION\n'; \ + fi; \ ) > $@.tmp) $(call quiet-command, if ! cmp -s $@ $@.tmp; then \ mv $@.tmp $@; \ @@ -656,22 +657,6 @@ dist: qemu-$(VERSION).tar.bz2 qemu-%.tar.bz2: $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)" -# Sphinx does not allow building manuals into the same directory as -# the source files, so if we're doing an in-tree QEMU build we must -# build the manuals into a subdirectory (and then install them from -# there for 'make install'). For an out-of-tree build we can just -# use the docs/ subdirectory in the build tree as normal. -ifeq ($(realpath $(SRC_PATH)),$(realpath .)) -MANUAL_BUILDDIR := docs/built -else -MANUAL_BUILDDIR := docs -endif - -define clean-manual = -rm -rf $(MANUAL_BUILDDIR)/$1/_static -rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(MANUAL_BUILDDIR)/$1/*.html -endef - distclean: clean rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi rm -f config-all-devices.mak config-all-disas.mak config.status @@ -692,9 +677,6 @@ distclean: clean rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html rm -f docs/qemu-block-drivers.7 rm -f docs/qemu-cpu-models.7 - rm -rf .doctrees - $(call clean-manual,devel) - $(call clean-manual,interop) for d in $(TARGET_DIRS); do \ rm -rf $$d || exit 1 ; \ done @@ -728,20 +710,7 @@ else BLOBS= endif -# Note that we manually filter-out the non-Sphinx documentation which -# is currently built into the docs/interop directory in the build tree. -define install-manual = -for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done -endef - -# Note that we deliberately do not install the "devel" manual: it is -# for QEMU developers, and not interesting to our users. -.PHONY: install-sphinxdocs -install-sphinxdocs: sphinxdocs - $(call install-manual,interop) - -install-doc: $(DOCS) install-sphinxdocs +install-doc: $(DOCS) $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" @@ -892,23 +861,6 @@ docs/version.texi: $(SRC_PATH)/VERSION %.pdf: %.texi docs/version.texi $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") -# Sphinx builds all its documentation at once in one invocation -# and handles "don't rebuild things unless necessary" itself. -# The '.doctrees' files are cached information to speed this up. -.PHONY: sphinxdocs -sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html - -# Canned command to build a single manual -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") -# We assume all RST files in the manual's directory are used in it -manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py - -$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) - $(call build-manual,devel) - -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) - $(call build-manual,interop) - qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") @@ -937,7 +889,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt diff --git a/configure b/configure index 1c563a7..384a241 100755 --- a/configure +++ b/configure @@ -4708,24 +4708,13 @@ if compile_prog "" "" ; then syncfs=yes fi -# Check we have a new enough version of sphinx-build -has_sphinx_build() { - # This is a bit awkward but works: create a trivial document and - # try to run it with our configuration file (which enforces a - # version requirement). This will fail if either - # sphinx-build doesn't exist at all or if it is too old. - mkdir -p "$TMPDIR1/sphinx" - touch "$TMPDIR1/sphinx/index.rst" - sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1 -} - # Check if tools are available to build documentation. if test "$docs" != "no" ; then - if has makeinfo && has pod2man && has_sphinx_build; then + if has makeinfo && has pod2man; then docs=yes else if test "$docs" = "yes" ; then - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx" + feature_not_found "docs" "Install texinfo and Perl/perl-podlators" fi docs=no fi diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index befbcc6..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,216 +0,0 @@ -# -*- 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 d0b0640..cfeb79f 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/conf.py b/docs/devel/conf.py deleted file mode 100644 index 7441f87..0000000 --- a/docs/devel/conf.py +++ /dev/null @@ -1,15 +0,0 @@ -# -*- 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 deleted file mode 100644 index ebbab63..0000000 --- a/docs/devel/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. 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 - decodetree diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst deleted file mode 100644 index b6a4c37..0000000 --- a/docs/devel/memory.rst +++ /dev/null @@ -1,363 +0,0 @@ -============== -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 - -The memory model provides support for - -- 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 -buses, memory controllers, and memory regions that have been rerouted. - -In addition to MemoryRegion objects, the memory API provides AddressSpace -objects for every root and possibly for intermediate MemoryRegions too. -These represent memory as seen from the CPU or a device's viewpoint. - -Types of regions ----------------- - -There are multiple types of memory regions (all represented by a single C type -MemoryRegion): - -- RAM: a RAM region is simply a range of host memory that can be made available - to the guest. - You typically initialize these with memory_region_init_ram(). Some special - purposes require the variants memory_region_init_resizeable_ram(), - memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). - -- MMIO: a range of guest memory that is implemented by host callbacks; - each read or write causes a callback to be called on the host. - You initialize these with memory_region_init_io(), passing it a - MemoryRegionOps structure describing the callbacks. - -- ROM: a ROM memory region works like RAM for reads (directly accessing - a region of host memory), and forbids writes. You initialize these with - memory_region_init_rom(). - -- ROM device: a ROM device memory region works like RAM for reads - (directly accessing a region of host memory), but like MMIO for - writes (invoking a callback). You initialize these with - memory_region_init_rom_device(). - -- IOMMU region: an IOMMU region translates addresses of accesses made to it - and forwards them to some other target memory region. As the name suggests, - these are only needed for modelling an IOMMU, not for simple devices. - You initialize these with memory_region_init_iommu(). - -- container: a container simply includes other memory regions, each at - a different offset. Containers are useful for grouping several regions - into one unit. For example, a PCI BAR may be composed of a RAM region - and an MMIO region. - - A container's subregions are usually non-overlapping. In some cases it is - useful to have overlapping regions; for example a memory controller that - can overlay a subregion of RAM with MMIO or ROM, or a PCI controller - that does not prevent card from claiming overlapping BARs. - - You initialize a pure container with memory_region_init(). - -- alias: a subsection of another region. Aliases allow a region to be - split apart into discontiguous regions. Examples of uses are memory banks - used when the guest address space is smaller than the amount of RAM - addressed, or a memory controller that splits main memory to expose a "PCI - hole". Aliases may point to any type of region, including other aliases, - but an alias may not point back to itself, directly or indirectly. - You initialize these with memory_region_init_alias(). - -- reservation region: a reservation region is primarily for debugging. - It claims I/O space that is not supposed to be handled by QEMU itself. - The typical use is to track parts of the address space which will be - handled by the host kernel when KVM is enabled. You initialize these - by passing a NULL callback parameter to memory_region_init_io(). - -It is valid to add subregions to a region which is not a pure container -(that is, to an MMIO, RAM or ROM region). This means that the region -will act like a container, except that any addresses within the container's -region which are not claimed by any subregion are handled by the -container itself (ie by its MMIO callbacks or RAM backing). However -it is generally possible to achieve the same effect with a pure container -one of whose subregions is a low priority "background" region covering -the whole address range; this is often clearer and is preferred. -Subregions cannot be added to an alias region. - -Migration ---------- - -Where the memory region is backed by host memory (RAM, ROM and -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() - -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() - -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() - -are for special cases only, and so they do not automatically -register the backing memory for migration; the caller must -manage migration if necessary. - -Region names ------------- - -Regions are assigned names by the constructor. For most regions these are -only used for debugging purposes, but RAM regions also use the name to identify -live migration sections. This means that RAM region names need to have ABI -stability. - -Region lifecycle ----------------- - -A region is created by one of the memory_region_init*() functions and -attached to an object, which acts as its owner or parent. QEMU ensures -that the owner object remains alive as long as the region is visible to -the guest, or as long as the region is in use by a virtual CPU or another -device. For example, the owner object will not die between an -address_space_map operation and the corresponding address_space_unmap. - -After creation, a region can be added to an address space or a -container with memory_region_add_subregion(), and removed using -memory_region_del_subregion(). - -Various region attributes (read-only, dirty logging, coalesced mmio, -ioeventfd) can be changed during the region lifecycle. They take effect -as soon as the region is made visible. This can be immediately, later, -or never. - -Destruction of a memory region happens automatically when the owner -object dies. - -If however the memory region is part of a dynamically allocated data -structure, you should call object_unparent() to destroy the memory region -before the data structure is freed. For an example see VFIOMSIXInfo -and VFIOQuirk in hw/vfio/pci.c. - -You must not destroy a memory region as long as it may be in use by a -device or CPU. In order to do this, as a general rule do not create or -destroy memory regions dynamically during a device's lifetime, and only -call object_unparent() in the memory region owner's instance_finalize -callback. The dynamically allocated data structure that contains the -memory region then should obviously be freed in the instance_finalize -callback as well. - -If you break this rule, the following situation can happen: - -- the memory region's owner had a reference taken via memory_region_ref - (for example by address_space_map) - -- the region is unparented, and has no owner anymore - -- when address_space_unmap is called, the reference to the memory region's - owner is leaked. - - -There is an exception to the above rule: it is okay to call -object_unparent at any time for an alias or a container region. It is -therefore also okay to create or destroy alias and container regions -dynamically during a device's lifetime. - -This exceptional usage is valid because aliases and containers only help -QEMU building the guest's memory map; they are never accessed directly. -memory_region_ref and memory_region_unref are never called on aliases -or containers, and the above situation then cannot happen. Exploiting -this exception is rarely necessary, and therefore it is discouraged, -but nevertheless it is used in a few places. - -For regions that "have no owner" (NULL is passed at creation time), the -machine object is actually used as the owner. Since instance_finalize is -never called for the machine object, you must never call object_unparent -on regions that have no owner, unless they are aliases or containers. - - -Overlapping regions and priority --------------------------------- -Usually, regions may not overlap each other; a memory address decodes into -exactly one target. In some cases it is useful to allow regions to overlap, -and sometimes to control which of an overlapping regions is visible to the -guest. This is done with memory_region_add_subregion_overlap(), which -allows the region to overlap any other region in the same container, and -specifies a priority that allows the core to decide which of two regions at -the same address are visible (highest wins). -Priority values are signed, and the default value is zero. This means that -you can use memory_region_add_subregion_overlap() both to specify a region -that must sit 'above' any others (with a positive priority) and also a -background region that sits 'below' others (with a negative priority). - -If the higher priority region in an overlap is a container or alias, then -the lower priority region will appear in any "holes" that the higher priority -region has left by not mapping subregions to that area of its address range. -(This applies recursively -- if the subregions are themselves containers or -aliases that leave holes then the lower priority region will appear in these -holes too.) - -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:: - - 0 1000 2000 3000 4000 5000 6000 7000 8000 - |------|------|------|------|------|------|------|------| - A: [ ] - C: [CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC] - B: [ ] - D: [DDDDD] - E: [EEEEE] - -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 -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] - -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. -This means that the device in charge of the container (typically modelling -a bus or a memory controller) can use them to manage the interaction of -its child regions without any side effects on other parts of the system. -In the example above, the priorities of D and E are unimportant because -they do not overlap each other. It is the relative priority of B and C -that causes D and E to appear on top of C: D and E's priorities are never -compared against the priority of C. - -Visibility ----------- -The memory core uses the following rules to select a memory region when the -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 - this leaf region - - if the subregion is a container, the same algorithm is used within the - subregion (after the address is adjusted by the subregion offset) - - if the subregion is an alias, the search is continued at the alias target - (after the address is adjusted by the subregion offset and alias offset) - - if a recursive search within a container or alias subregion does not - find a match (because of a "hole" in the container's coverage of its - 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 - -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 -3.5GB; "himem" maps the last 0.5GB at address 4GB. This leaves 0.5GB for the -so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with -4GB of memory. - -The memory controller diverts addresses in the range 640K-768K to the PCI -address space. This is modelled using the "vga-window" alias, mapped at a -higher priority so it obscures the RAM at the same addresses. The vga window -can be removed by programming the memory controller; this is modelled by -removing the alias and exposing the RAM underneath. - -The pci address space is not a direct child of the system address space, since -we only want parts of it to be visible (we accomplish this using aliases). -It has two subregions: vga-area models the legacy vga window and is occupied -by two 32K memory banks pointing at two sections of the framebuffer. -In addition the vram is mapped as a BAR at address e1000000, and an additional -BAR containing MMIO registers is mapped after it. - -Note that if the guest maps a BAR outside the PCI hole, it would not be -visible as the pci-hole alias clips it to a 0.5GB range. - -MMIO Operations ---------------- - -MMIO regions are provided with ->read() and ->write() callbacks, -which are sufficient for most devices. Some devices change behaviour -based on the attributes used for the memory transaction, or need -to be able to respond that the access should provoke a bus error -rather than completing successfully; those devices can use the -->read_with_attrs() and ->write_with_attrs() callbacks instead. - -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. diff --git a/docs/devel/memory.txt b/docs/devel/memory.txt new file mode 100644 index 0000000..42577e1 --- /dev/null +++ b/docs/devel/memory.txt @@ -0,0 +1,351 @@ +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 + +The memory model provides support for + + - 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 +buses, memory controllers, and memory regions that have been rerouted. + +In addition to MemoryRegion objects, the memory API provides AddressSpace +objects for every root and possibly for intermediate MemoryRegions too. +These represent memory as seen from the CPU or a device's viewpoint. + +Types of regions +---------------- + +There are multiple types of memory regions (all represented by a single C type +MemoryRegion): + +- RAM: a RAM region is simply a range of host memory that can be made available + to the guest. + You typically initialize these with memory_region_init_ram(). Some special + purposes require the variants memory_region_init_resizeable_ram(), + memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). + +- MMIO: a range of guest memory that is implemented by host callbacks; + each read or write causes a callback to be called on the host. + You initialize these with memory_region_init_io(), passing it a + MemoryRegionOps structure describing the callbacks. + +- ROM: a ROM memory region works like RAM for reads (directly accessing + a region of host memory), and forbids writes. You initialize these with + memory_region_init_rom(). + +- ROM device: a ROM device memory region works like RAM for reads + (directly accessing a region of host memory), but like MMIO for + writes (invoking a callback). You initialize these with + memory_region_init_rom_device(). + +- IOMMU region: an IOMMU region translates addresses of accesses made to it + and forwards them to some other target memory region. As the name suggests, + these are only needed for modelling an IOMMU, not for simple devices. + You initialize these with memory_region_init_iommu(). + +- container: a container simply includes other memory regions, each at + a different offset. Containers are useful for grouping several regions + into one unit. For example, a PCI BAR may be composed of a RAM region + and an MMIO region. + + A container's subregions are usually non-overlapping. In some cases it is + useful to have overlapping regions; for example a memory controller that + can overlay a subregion of RAM with MMIO or ROM, or a PCI controller + that does not prevent card from claiming overlapping BARs. + + You initialize a pure container with memory_region_init(). + +- alias: a subsection of another region. Aliases allow a region to be + split apart into discontiguous regions. Examples of uses are memory banks + used when the guest address space is smaller than the amount of RAM + addressed, or a memory controller that splits main memory to expose a "PCI + hole". Aliases may point to any type of region, including other aliases, + but an alias may not point back to itself, directly or indirectly. + You initialize these with memory_region_init_alias(). + +- reservation region: a reservation region is primarily for debugging. + It claims I/O space that is not supposed to be handled by QEMU itself. + The typical use is to track parts of the address space which will be + handled by the host kernel when KVM is enabled. You initialize these + by passing a NULL callback parameter to memory_region_init_io(). + +It is valid to add subregions to a region which is not a pure container +(that is, to an MMIO, RAM or ROM region). This means that the region +will act like a container, except that any addresses within the container's +region which are not claimed by any subregion are handled by the +container itself (ie by its MMIO callbacks or RAM backing). However +it is generally possible to achieve the same effect with a pure container +one of whose subregions is a low priority "background" region covering +the whole address range; this is often clearer and is preferred. +Subregions cannot be added to an alias region. + +Migration +--------- + +Where the memory region is backed by host memory (RAM, ROM and +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() + +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() +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() +are for special cases only, and so they do not automatically +register the backing memory for migration; the caller must +manage migration if necessary. + +Region names +------------ + +Regions are assigned names by the constructor. For most regions these are +only used for debugging purposes, but RAM regions also use the name to identify +live migration sections. This means that RAM region names need to have ABI +stability. + +Region lifecycle +---------------- + +A region is created by one of the memory_region_init*() functions and +attached to an object, which acts as its owner or parent. QEMU ensures +that the owner object remains alive as long as the region is visible to +the guest, or as long as the region is in use by a virtual CPU or another +device. For example, the owner object will not die between an +address_space_map operation and the corresponding address_space_unmap. + +After creation, a region can be added to an address space or a +container with memory_region_add_subregion(), and removed using +memory_region_del_subregion(). + +Various region attributes (read-only, dirty logging, coalesced mmio, +ioeventfd) can be changed during the region lifecycle. They take effect +as soon as the region is made visible. This can be immediately, later, +or never. + +Destruction of a memory region happens automatically when the owner +object dies. + +If however the memory region is part of a dynamically allocated data +structure, you should call object_unparent() to destroy the memory region +before the data structure is freed. For an example see VFIOMSIXInfo +and VFIOQuirk in hw/vfio/pci.c. + +You must not destroy a memory region as long as it may be in use by a +device or CPU. In order to do this, as a general rule do not create or +destroy memory regions dynamically during a device's lifetime, and only +call object_unparent() in the memory region owner's instance_finalize +callback. The dynamically allocated data structure that contains the +memory region then should obviously be freed in the instance_finalize +callback as well. + +If you break this rule, the following situation can happen: + +- the memory region's owner had a reference taken via memory_region_ref + (for example by address_space_map) + +- the region is unparented, and has no owner anymore + +- when address_space_unmap is called, the reference to the memory region's + owner is leaked. + + +There is an exception to the above rule: it is okay to call +object_unparent at any time for an alias or a container region. It is +therefore also okay to create or destroy alias and container regions +dynamically during a device's lifetime. + +This exceptional usage is valid because aliases and containers only help +QEMU building the guest's memory map; they are never accessed directly. +memory_region_ref and memory_region_unref are never called on aliases +or containers, and the above situation then cannot happen. Exploiting +this exception is rarely necessary, and therefore it is discouraged, +but nevertheless it is used in a few places. + +For regions that "have no owner" (NULL is passed at creation time), the +machine object is actually used as the owner. Since instance_finalize is +never called for the machine object, you must never call object_unparent +on regions that have no owner, unless they are aliases or containers. + + +Overlapping regions and priority +-------------------------------- +Usually, regions may not overlap each other; a memory address decodes into +exactly one target. In some cases it is useful to allow regions to overlap, +and sometimes to control which of an overlapping regions is visible to the +guest. This is done with memory_region_add_subregion_overlap(), which +allows the region to overlap any other region in the same container, and +specifies a priority that allows the core to decide which of two regions at +the same address are visible (highest wins). +Priority values are signed, and the default value is zero. This means that +you can use memory_region_add_subregion_overlap() both to specify a region +that must sit 'above' any others (with a positive priority) and also a +background region that sits 'below' others (with a negative priority). + +If the higher priority region in an overlap is a container or alias, then +the lower priority region will appear in any "holes" that the higher priority +region has left by not mapping subregions to that area of its address range. +(This applies recursively -- if the subregions are themselves containers or +aliases that leave holes then the lower priority region will appear in these +holes too.) + +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: + + 0 1000 2000 3000 4000 5000 6000 7000 8000 + |------|------|------|------|------|------|------|------| + A: [ ] + C: [CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC] + B: [ ] + D: [DDDDD] + E: [EEEEE] + +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 +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] + +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. +This means that the device in charge of the container (typically modelling +a bus or a memory controller) can use them to manage the interaction of +its child regions without any side effects on other parts of the system. +In the example above, the priorities of D and E are unimportant because +they do not overlap each other. It is the relative priority of B and C +that causes D and E to appear on top of C: D and E's priorities are never +compared against the priority of C. + +Visibility +---------- +The memory core uses the following rules to select a memory region when the +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 + this leaf region + - if the subregion is a container, the same algorithm is used within the + subregion (after the address is adjusted by the subregion offset) + - if the subregion is an alias, the search is continued at the alias target + (after the address is adjusted by the subregion offset and alias offset) + - if a recursive search within a container or alias subregion does not + find a match (because of a "hole" in the container's coverage of its + 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 + +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 +3.5GB; "himem" maps the last 0.5GB at address 4GB. This leaves 0.5GB for the +so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with +4GB of memory. + +The memory controller diverts addresses in the range 640K-768K to the PCI +address space. This is modelled using the "vga-window" alias, mapped at a +higher priority so it obscures the RAM at the same addresses. The vga window +can be removed by programming the memory controller; this is modelled by +removing the alias and exposing the RAM underneath. + +The pci address space is not a direct child of the system address space, since +we only want parts of it to be visible (we accomplish this using aliases). +It has two subregions: vga-area models the legacy vga window and is occupied +by two 32K memory banks pointing at two sections of the framebuffer. +In addition the vram is mapped as a BAR at address e1000000, and an additional +BAR containing MMIO registers is mapped after it. + +Note that if the guest maps a BAR outside the PCI hole, it would not be +visible as the pci-hole alias clips it to a 0.5GB range. + +MMIO Operations +--------------- + +MMIO regions are provided with ->read() and ->write() callbacks, +which are sufficient for most devices. Some devices change behaviour +based on the attributes used for the memory transaction, or need +to be able to respond that the access should provoke a bus error +rather than completing successfully; those devices can use the +->read_with_attrs() and ->write_with_attrs() callbacks instead. + +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. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3690955..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. 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 deleted file mode 100644 index cf3c69d..0000000 --- a/docs/interop/conf.py +++ /dev/null @@ -1,15 +0,0 @@ -# -*- 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 deleted file mode 100644 index 2df977d..0000000 --- a/docs/interop/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. 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 - -- 1.8.3.1