From e4766d9eeec84c6ea6ea183529a4db4ecac3a9c2 Mon Sep 17 00:00:00 2001 From: Ying Fang Date: Fri, 21 Feb 2020 18:27:32 +0800 Subject: [PATCH] docs: Enable build and install of our rST docs drop Revert-Enable-build-and-install-of-our-rST-docs.patch to enable python-sphnix doc support. Signed-off-by: Ying Fang --- ...le-build-and-install-of-our-rST-docs.patch | 1306 ----------------- qemu.spec | 3 +- 2 files changed, 2 insertions(+), 1307 deletions(-) delete mode 100644 Revert-Enable-build-and-install-of-our-rST-docs.patch diff --git a/Revert-Enable-build-and-install-of-our-rST-docs.patch b/Revert-Enable-build-and-install-of-our-rST-docs.patch deleted file mode 100644 index e357273..0000000 --- a/Revert-Enable-build-and-install-of-our-rST-docs.patch +++ /dev/null @@ -1,1306 +0,0 @@ -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 - diff --git a/qemu.spec b/qemu.spec index e0096dd..a2279a5 100644 --- a/qemu.spec +++ b/qemu.spec @@ -11,7 +11,6 @@ Source2: 99-qemu-guest-agent.rules Source3: bridge.conf Patch0001: qxl-check-release-info-object.patch -Patch0003: Revert-Enable-build-and-install-of-our-rST-docs.patch Patch0004: ARM64-record-vtimer-tick-when-cpu-is-stopped.patch Patch0005: pl011-reset-read-FIFO-when-UARTTIMSC-0-UARTICR-0xfff.patch Patch0006: pl031-support-rtc-timer-property-for-pl031.patch @@ -51,6 +50,7 @@ BuildRequires: perl-podlators BuildRequires: kernel BuildRequires: chrpath BuildRequires: gettext +BuildRequires: python-sphinx BuildRequires: zlib-devel BuildRequires: gtk3-devel @@ -342,6 +342,7 @@ getent passwd qemu >/dev/null || \ %doc %{qemudocdir}/qemu-ga-ref.txt %doc %{qemudocdir}/qemu-qmp-ref.html %doc %{qemudocdir}/qemu-qmp-ref.txt +%doc %{qemudocdir}/interop %doc %{qemudocdir}/README %doc %{qemudocdir}/Changelog %{_mandir}/man1/qemu.1*