1307 lines
52 KiB
Diff
1307 lines
52 KiB
Diff
From 4ed2ab47ab39de39f9753074b79303638dac020d Mon Sep 17 00:00:00 2001
|
|
From: zhanghailiang <zhang.zhanghailiang@huawei.com>
|
|
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 <berrange@redhat.com>
|
|
S: Odd Fixes
|
|
F: scripts/git-submodule.sh
|
|
-
|
|
-Sphinx documentation configuration and build machinery
|
|
-M: Peter Maydell <peter.maydell@linaro.org>
|
|
-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
|
|
|