jcs.org / qemu
qemu with hax to log dma reads & writes jcs.org/2018/11/12/vfio
fork atom

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-sphinx-20190307' into staging

Enable building and installing rST docs with Sphinx

# gpg: Signature made Thu 07 Mar 2019 15:05:12 GMT
# gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg: issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-sphinx-20190307:
MAINTAINERS: Add entry for Sphinx documentation infrastructure
docs/conf.py: Don't hard-code QEMU version
Makefile: Abstract out "identify the pkgversion" code
Makefile, configure: Support building rST documentation
docs: Provide separate conf.py for each manual we want
docs/conf.py: Disable option warnings
docs/conf.py: Don't include rST sources in HTML build
docs/conf.py: Configure the 'alabaster' theme
docs/conf.py: Disable unused _static directory
docs: Commit initial files from sphinx-quickstart
docs: Convert memory.txt to rst format
docs/cpu-hotplug.rst: Fix rST markup issues

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Peter Maydell 21afe115 3a75ef6a

+449 -81
+1
.gitignore
··· 1 + /.doctrees 1 2 /config-devices.* 2 3 /config-all-devices.* 3 4 /config-all-disas.*
+6
MAINTAINERS
··· 2567 2567 M: Daniel P. Berrange <berrange@redhat.com> 2568 2568 S: Odd Fixes 2569 2569 F: scripts/git-submodule.sh 2570 + 2571 + Sphinx documentation configuration and build machinery 2572 + M: Peter Maydell <peter.maydell@linaro.org> 2573 + S: Maintained 2574 + F: docs/conf.py 2575 + F: docs/*/conf.py
+58 -20
Makefile
··· 87 87 88 88 include $(SRC_PATH)/rules.mak 89 89 90 + # Create QEMU_PKGVERSION and FULL_VERSION strings 91 + # If PKGVERSION is set, use that; otherwise get version and -dirty status from git 92 + QEMU_PKGVERSION := $(if $(PKGVERSION),$(PKGVERSION),$(shell \ 93 + cd $(SRC_PATH); \ 94 + if test -e .git; then \ 95 + git describe --match 'v*' 2>/dev/null | tr -d '\n'; \ 96 + if ! git diff-index --quiet HEAD &>/dev/null; then \ 97 + echo "-dirty"; \ 98 + fi; \ 99 + fi)) 100 + 101 + # Either "version (pkgversion)", or just "version" if pkgversion not set 102 + FULL_VERSION := $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),$(VERSION)) 103 + 90 104 GENERATED_FILES = qemu-version.h config-host.h qemu-options.def 91 105 92 106 GENERATED_QAPI_FILES = qapi/qapi-builtin-types.h qapi/qapi-builtin-types.c ··· 388 402 389 403 include $(SRC_PATH)/tests/Makefile.include 390 404 391 - all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules 405 + all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules 392 406 393 407 qemu-version.h: FORCE 394 408 $(call quiet-command, \ 395 - (cd $(SRC_PATH); \ 396 - if test -n "$(PKGVERSION)"; then \ 397 - pkgvers="$(PKGVERSION)"; \ 398 - else \ 399 - if test -d .git; then \ 400 - pkgvers=$$(git describe --match 'v*' 2>/dev/null | tr -d '\n');\ 401 - if ! git diff-index --quiet HEAD &>/dev/null; then \ 402 - pkgvers="$${pkgvers}-dirty"; \ 403 - fi; \ 404 - fi; \ 405 - fi; \ 406 - printf "#define QEMU_PKGVERSION \"$${pkgvers}\"\n"; \ 407 - if test -n "$${pkgvers}"; then \ 408 - printf '#define QEMU_FULL_VERSION QEMU_VERSION " (" QEMU_PKGVERSION ")"\n'; \ 409 - else \ 410 - printf '#define QEMU_FULL_VERSION QEMU_VERSION\n'; \ 411 - fi; \ 409 + (printf '#define QEMU_PKGVERSION "$(QEMU_PKGVERSION)"\n'; \ 410 + printf '#define QEMU_FULL_VERSION "$(FULL_VERSION)"\n'; \ 412 411 ) > $@.tmp) 413 412 $(call quiet-command, if ! cmp -s $@ $@.tmp; then \ 414 413 mv $@.tmp $@; \ ··· 637 636 qemu-%.tar.bz2: 638 637 $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)" 639 638 639 + # Note that these commands assume that there are no HTML files in 640 + # the docs subdir in the source tree! If there are then this will 641 + # blow them away for an in-source-tree 'make clean'. 642 + define clean-manual = 643 + rm -rf docs/$1/_static 644 + rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html 645 + endef 646 + 640 647 distclean: clean 641 648 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 642 649 rm -f config-all-devices.mak config-all-disas.mak config.status ··· 657 664 rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html 658 665 rm -f docs/qemu-block-drivers.7 659 666 rm -f docs/qemu-cpu-models.7 667 + rm -f .doctrees 668 + $(call clean-manual,devel) 669 + $(call clean-manual,interop) 660 670 for d in $(TARGET_DIRS); do \ 661 671 rm -rf $$d || exit 1 ; \ 662 672 done ··· 690 700 BLOBS= 691 701 endif 692 702 693 - install-doc: $(DOCS) 703 + define install-manual = 704 + for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done 705 + for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done 706 + endef 707 + 708 + # Note that we deliberately do not install the "devel" manual: it is 709 + # for QEMU developers, and not interesting to our users. 710 + .PHONY: install-sphinxdocs 711 + install-sphinxdocs: sphinxdocs 712 + $(call install-manual,interop) 713 + 714 + install-doc: $(DOCS) install-sphinxdocs 694 715 $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" 695 716 $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" 696 717 $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" ··· 841 862 %.pdf: %.texi docs/version.texi 842 863 $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") 843 864 865 + # Sphinx builds all its documentation at once in one invocation 866 + # and handles "don't rebuild things unless necessary" itself. 867 + # The '.doctrees' files are cached information to speed this up. 868 + .PHONY: sphinxdocs 869 + sphinxdocs: docs/devel/index.html docs/interop/index.html 870 + 871 + # Canned command to build a single manual 872 + 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 docs/$1 ,"SPHINX","docs/$1") 873 + # We assume all RST files in the manual's directory are used in it 874 + manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py 875 + 876 + docs/devel/index.html: $(call manual-deps,devel) 877 + $(call build-manual,devel) 878 + 879 + docs/interop/index.html: $(call manual-deps,interop) 880 + $(call build-manual,interop) 881 + 844 882 qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool 845 883 $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") 846 884 ··· 869 907 docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi 870 908 scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi 871 909 872 - html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html 910 + html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs 873 911 info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info 874 912 pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf 875 913 txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
+13 -2
configure
··· 4589 4589 syncfs=yes 4590 4590 fi 4591 4591 4592 + # Check we have a new enough version of sphinx-build 4593 + has_sphinx_build() { 4594 + # This is a bit awkward but works: create a trivial document and 4595 + # try to run it with our configuration file (which enforces a 4596 + # version requirement). This will fail if either 4597 + # sphinx-build doesn't exist at all or if it is too old. 4598 + mkdir -p "$TMPDIR1/sphinx" 4599 + touch "$TMPDIR1/sphinx/index.rst" 4600 + sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1 4601 + } 4602 + 4592 4603 # Check if tools are available to build documentation. 4593 4604 if test "$docs" != "no" ; then 4594 - if has makeinfo && has pod2man; then 4605 + if has makeinfo && has pod2man && has_sphinx_build; then 4595 4606 docs=yes 4596 4607 else 4597 4608 if test "$docs" = "yes" ; then 4598 - feature_not_found "docs" "Install texinfo and Perl/perl-podlators" 4609 + feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx" 4599 4610 fi 4600 4611 docs=no 4601 4612 fi
+216
docs/conf.py
··· 1 + # -*- coding: utf-8 -*- 2 + # 3 + # QEMU documentation build configuration file, created by 4 + # sphinx-quickstart on Thu Jan 31 16:40:14 2019. 5 + # 6 + # This config file can be used in one of two ways: 7 + # (1) as a common config file which is included by the conf.py 8 + # for each of QEMU's manuals: in this case sphinx-build is run multiple 9 + # times, once per subdirectory. 10 + # (2) as a top level conf file which will result in building all 11 + # the manuals into a single document: in this case sphinx-build is 12 + # run once, on the top-level docs directory. 13 + # 14 + # QEMU's makefiles take option (1), which allows us to install 15 + # only the ones the user cares about (in particular we don't want 16 + # to ship the 'devel' manual to end-users). 17 + # Third-party sites such as readthedocs.org will take option (2). 18 + # 19 + # 20 + # This file is execfile()d with the current directory set to its 21 + # containing dir. 22 + # 23 + # Note that not all possible configuration values are present in this 24 + # autogenerated file. 25 + # 26 + # All configuration values have a default; values that are commented out 27 + # serve to show the default. 28 + 29 + import os 30 + import sys 31 + 32 + # The per-manual conf.py will set qemu_docdir for a single-manual build; 33 + # otherwise set it here if this is an entire-manual-set build. 34 + # This is always the absolute path of the docs/ directory in the source tree. 35 + try: 36 + qemu_docdir 37 + except NameError: 38 + qemu_docdir = os.path.abspath(".") 39 + 40 + # If extensions (or modules to document with autodoc) are in another directory, 41 + # add these directories to sys.path here. If the directory is relative to the 42 + # documentation root, use an absolute path starting from qemu_docdir. 43 + # 44 + # sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) 45 + 46 + 47 + # -- General configuration ------------------------------------------------ 48 + 49 + # If your documentation needs a minimal Sphinx version, state it here. 50 + # 51 + # 1.3 is where the 'alabaster' theme was shipped with Sphinx. 52 + needs_sphinx = '1.3' 53 + 54 + # Add any Sphinx extension module names here, as strings. They can be 55 + # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 56 + # ones. 57 + extensions = [] 58 + 59 + # Add any paths that contain templates here, relative to this directory. 60 + templates_path = ['_templates'] 61 + 62 + # The suffix(es) of source filenames. 63 + # You can specify multiple suffix as a list of string: 64 + # 65 + # source_suffix = ['.rst', '.md'] 66 + source_suffix = '.rst' 67 + 68 + # The master toctree document. 69 + master_doc = 'index' 70 + 71 + # General information about the project. 72 + project = u'QEMU' 73 + copyright = u'2019, The QEMU Project Developers' 74 + author = u'The QEMU Project Developers' 75 + 76 + # The version info for the project you're documenting, acts as replacement for 77 + # |version| and |release|, also used in various other places throughout the 78 + # built documents. 79 + 80 + # Extract this information from the VERSION file, for the benefit of 81 + # standalone Sphinx runs as used by readthedocs.org. Builds run from 82 + # the Makefile will pass version and release on the sphinx-build 83 + # command line, which override this. 84 + try: 85 + extracted_version = None 86 + with open(os.path.join(qemu_docdir, '../VERSION')) as f: 87 + extracted_version = f.readline().strip() 88 + except: 89 + pass 90 + finally: 91 + if extracted_version: 92 + version = release = extracted_version 93 + else: 94 + version = release = "unknown version" 95 + 96 + # The language for content autogenerated by Sphinx. Refer to documentation 97 + # for a list of supported languages. 98 + # 99 + # This is also used if you do content translation via gettext catalogs. 100 + # Usually you set "language" from the command line for these cases. 101 + language = None 102 + 103 + # List of patterns, relative to source directory, that match files and 104 + # directories to ignore when looking for source files. 105 + # This patterns also effect to html_static_path and html_extra_path 106 + exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 107 + 108 + # The name of the Pygments (syntax highlighting) style to use. 109 + pygments_style = 'sphinx' 110 + 111 + # If true, `todo` and `todoList` produce output, else they produce nothing. 112 + todo_include_todos = False 113 + 114 + # Sphinx defaults to warning about use of :option: for options not defined 115 + # with "option::" in the document being processed. Turn that off. 116 + suppress_warnings = ["ref.option"] 117 + 118 + # -- Options for HTML output ---------------------------------------------- 119 + 120 + # The theme to use for HTML and HTML Help pages. See the documentation for 121 + # a list of builtin themes. 122 + # 123 + html_theme = 'alabaster' 124 + 125 + # Theme options are theme-specific and customize the look and feel of a theme 126 + # further. For a list of options available for each theme, see the 127 + # documentation. 128 + # We initialize this to empty here, so the per-manual conf.py can just 129 + # add individual key/value entries. 130 + html_theme_options = { 131 + } 132 + 133 + # Add any paths that contain custom static files (such as style sheets) here, 134 + # relative to this directory. They are copied after the builtin static files, 135 + # so a file named "default.css" will overwrite the builtin "default.css". 136 + # QEMU doesn't yet have any static files, so comment this out so we don't 137 + # get a warning about a missing directory. 138 + # If we do ever add this then it would probably be better to call the 139 + # subdirectory sphinx_static, as the Linux kernel does. 140 + # html_static_path = ['_static'] 141 + 142 + # Custom sidebar templates, must be a dictionary that maps document names 143 + # to template names. 144 + # 145 + # This is required for the alabaster theme 146 + # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars 147 + html_sidebars = { 148 + '**': [ 149 + 'about.html', 150 + 'navigation.html', 151 + 'searchbox.html', 152 + ] 153 + } 154 + 155 + # Don't copy the rST source files to the HTML output directory, 156 + # and don't put links to the sources into the output HTML. 157 + html_copy_source = False 158 + 159 + # -- Options for HTMLHelp output ------------------------------------------ 160 + 161 + # Output file base name for HTML help builder. 162 + htmlhelp_basename = 'QEMUdoc' 163 + 164 + 165 + # -- Options for LaTeX output --------------------------------------------- 166 + 167 + latex_elements = { 168 + # The paper size ('letterpaper' or 'a4paper'). 169 + # 170 + # 'papersize': 'letterpaper', 171 + 172 + # The font size ('10pt', '11pt' or '12pt'). 173 + # 174 + # 'pointsize': '10pt', 175 + 176 + # Additional stuff for the LaTeX preamble. 177 + # 178 + # 'preamble': '', 179 + 180 + # Latex figure (float) alignment 181 + # 182 + # 'figure_align': 'htbp', 183 + } 184 + 185 + # Grouping the document tree into LaTeX files. List of tuples 186 + # (source start file, target name, title, 187 + # author, documentclass [howto, manual, or own class]). 188 + latex_documents = [ 189 + (master_doc, 'QEMU.tex', u'QEMU Documentation', 190 + u'The QEMU Project Developers', 'manual'), 191 + ] 192 + 193 + 194 + # -- Options for manual page output --------------------------------------- 195 + 196 + # One entry per manual page. List of tuples 197 + # (source start file, name, description, authors, manual section). 198 + man_pages = [ 199 + (master_doc, 'qemu', u'QEMU Documentation', 200 + [author], 1) 201 + ] 202 + 203 + 204 + # -- Options for Texinfo output ------------------------------------------- 205 + 206 + # Grouping the document tree into Texinfo files. List of tuples 207 + # (source start file, target name, title, author, 208 + # dir menu entry, description, category) 209 + texinfo_documents = [ 210 + (master_doc, 'QEMU', u'QEMU Documentation', 211 + author, 'QEMU', 'One line description of project.', 212 + 'Miscellaneous'), 213 + ] 214 + 215 + 216 +
+1 -1
docs/cpu-hotplug.rst
··· 60 60 hot-plugged (no "qom-path" member). From its output in step (3), we 61 61 can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, 62 62 while hot-plugging a CPU into socket 1 requires passing the listed 63 - properties to QMP ``device_add``: 63 + properties to QMP ``device_add``:: 64 64 65 65 (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0 66 66 {
+15
docs/devel/conf.py
··· 1 + # -*- coding: utf-8 -*- 2 + # 3 + # QEMU documentation build configuration file for the 'devel' manual. 4 + # 5 + # This includes the top level conf file and then makes any necessary tweaks. 6 + import sys 7 + import os 8 + 9 + qemu_docdir = os.path.abspath("..") 10 + parent_config = os.path.join(qemu_docdir, "conf.py") 11 + exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) 12 + 13 + # This slightly misuses the 'description', but is the best way to get 14 + # the manual title to appear in the sidebar. 15 + html_theme_options['description'] = u'Developer''s Guide'
+21
docs/devel/index.rst
··· 1 + .. This is the top level page for the 'devel' manual. 2 + 3 + 4 + QEMU Developer's Guide 5 + ====================== 6 + 7 + This manual documents various parts of the internals of QEMU. 8 + You only need to read it if you are interested in reading or 9 + modifying QEMU's source code. 10 + 11 + Contents: 12 + 13 + .. toctree:: 14 + :maxdepth: 2 15 + 16 + loads-stores 17 + memory 18 + migration 19 + stable-process 20 + testing 21 +
+70 -58
docs/devel/memory.txt docs/devel/memory.rst
··· 1 + ============== 1 2 The memory API 2 3 ============== 3 4 4 5 The memory API models the memory and I/O buses and controllers of a QEMU 5 6 machine. It attempts to allow modelling of: 6 7 7 - - ordinary RAM 8 - - memory-mapped I/O (MMIO) 9 - - memory controllers that can dynamically reroute physical memory regions 10 - to different destinations 8 + - ordinary RAM 9 + - memory-mapped I/O (MMIO) 10 + - memory controllers that can dynamically reroute physical memory regions 11 + to different destinations 11 12 12 13 The memory model provides support for 13 14 14 - - tracking RAM changes by the guest 15 - - setting up coalesced memory for kvm 16 - - setting up ioeventfd regions for kvm 15 + - tracking RAM changes by the guest 16 + - setting up coalesced memory for kvm 17 + - setting up ioeventfd regions for kvm 17 18 18 19 Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks 19 20 (leaves) are RAM and MMIO regions, while other nodes represent ··· 98 99 copied to the destination on migration. These APIs which allocate 99 100 the host memory for you will also register the memory so it is 100 101 migrated: 101 - - memory_region_init_ram() 102 - - memory_region_init_rom() 103 - - memory_region_init_rom_device() 102 + 103 + - memory_region_init_ram() 104 + - memory_region_init_rom() 105 + - memory_region_init_rom_device() 104 106 105 107 For most devices and boards this is the correct thing. If you 106 108 have a special case where you need to manage the migration of 107 109 the backing memory yourself, you can call the functions: 108 - - memory_region_init_ram_nomigrate() 109 - - memory_region_init_rom_nomigrate() 110 - - memory_region_init_rom_device_nomigrate() 110 + 111 + - memory_region_init_ram_nomigrate() 112 + - memory_region_init_rom_nomigrate() 113 + - memory_region_init_rom_device_nomigrate() 114 + 111 115 which only initialize the MemoryRegion and leave handling 112 116 migration to the caller. 113 117 114 118 The functions: 115 - - memory_region_init_resizeable_ram() 116 - - memory_region_init_ram_from_file() 117 - - memory_region_init_ram_from_fd() 118 - - memory_region_init_ram_ptr() 119 - - memory_region_init_ram_device_ptr() 119 + 120 + - memory_region_init_resizeable_ram() 121 + - memory_region_init_ram_from_file() 122 + - memory_region_init_ram_from_fd() 123 + - memory_region_init_ram_ptr() 124 + - memory_region_init_ram_device_ptr() 125 + 120 126 are for special cases only, and so they do not automatically 121 127 register the backing memory for migration; the caller must 122 128 manage migration if necessary. ··· 218 224 B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is 219 225 an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two 220 226 of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at 221 - offset 0x2000. As a diagram: 227 + offset 0x2000. As a diagram:: 222 228 223 229 0 1000 2000 3000 4000 5000 6000 7000 8000 224 230 |------|------|------|------|------|------|------|------| ··· 228 234 D: [DDDDD] 229 235 E: [EEEEE] 230 236 231 - The regions that will be seen within this address range then are: 232 - [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] 237 + The regions that will be seen within this address range then are:: 238 + 239 + [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] 233 240 234 241 Since B has higher priority than C, its subregions appear in the flat map 235 242 even where they overlap with C. In ranges where B has not mapped anything ··· 237 244 238 245 If B had provided its own MMIO operations (ie it was not a pure container) 239 246 then these would be used for any addresses in its range not handled by 240 - D or E, and the result would be: 241 - [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] 247 + D or E, and the result would be:: 248 + 249 + [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] 242 250 243 251 Priority values are local to a container, because the priorities of two 244 252 regions are only compared when they are both children of the same container. ··· 257 265 258 266 - all direct subregions of the root region are matched against the address, in 259 267 descending priority order 268 + 260 269 - if the address lies outside the region offset/size, the subregion is 261 270 discarded 262 271 - if the subregion is a leaf (RAM or MMIO), the search terminates, returning ··· 270 279 address range), then if this is a container with its own MMIO or RAM 271 280 backing the search terminates, returning the container itself. Otherwise 272 281 we continue with the next subregion in priority order 282 + 273 283 - if none of the subregions match the address then the search terminates 274 284 with no match found 275 285 276 286 Example memory map 277 287 ------------------ 278 288 279 - system_memory: container@0-2^48-1 280 - | 281 - +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) 282 - | 283 - +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) 284 - | 285 - +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) 286 - | (prio 1) 287 - | 288 - +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) 289 + :: 289 290 290 - pci (0-2^32-1) 291 - | 292 - +--- vga-area: container@0xa0000-0xbffff 293 - | | 294 - | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) 295 - | | 296 - | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) 297 - | 298 - +---- vram: ram@0xe1000000-0xe1ffffff 299 - | 300 - +---- vga-mmio: mmio@0xe2000000-0xe200ffff 291 + system_memory: container@0-2^48-1 292 + | 293 + +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) 294 + | 295 + +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) 296 + | 297 + +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) 298 + | (prio 1) 299 + | 300 + +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) 301 301 302 - ram: ram@0x00000000-0xffffffff 302 + pci (0-2^32-1) 303 + | 304 + +--- vga-area: container@0xa0000-0xbffff 305 + | | 306 + | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) 307 + | | 308 + | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) 309 + | 310 + +---- vram: ram@0xe1000000-0xe1ffffff 311 + | 312 + +---- vga-mmio: mmio@0xe2000000-0xe200ffff 313 + 314 + ram: ram@0x00000000-0xffffffff 303 315 304 316 This is a (simplified) PC memory map. The 4GB RAM block is mapped into the 305 317 system address space via two aliases: "lomem" is a 1:1 mapping of the first ··· 336 348 In addition various constraints can be supplied to control how these 337 349 callbacks are called: 338 350 339 - - .valid.min_access_size, .valid.max_access_size define the access sizes 340 - (in bytes) which the device accepts; accesses outside this range will 341 - have device and bus specific behaviour (ignored, or machine check) 342 - - .valid.unaligned specifies that the *device being modelled* supports 343 - unaligned accesses; if false, unaligned accesses will invoke the 344 - appropriate bus or CPU specific behaviour. 345 - - .impl.min_access_size, .impl.max_access_size define the access sizes 346 - (in bytes) supported by the *implementation*; other access sizes will be 347 - emulated using the ones available. For example a 4-byte write will be 348 - emulated using four 1-byte writes, if .impl.max_access_size = 1. 349 - - .impl.unaligned specifies that the *implementation* supports unaligned 350 - accesses; if false, unaligned accesses will be emulated by two aligned 351 - accesses. 351 + - .valid.min_access_size, .valid.max_access_size define the access sizes 352 + (in bytes) which the device accepts; accesses outside this range will 353 + have device and bus specific behaviour (ignored, or machine check) 354 + - .valid.unaligned specifies that the *device being modelled* supports 355 + unaligned accesses; if false, unaligned accesses will invoke the 356 + appropriate bus or CPU specific behaviour. 357 + - .impl.min_access_size, .impl.max_access_size define the access sizes 358 + (in bytes) supported by the *implementation*; other access sizes will be 359 + emulated using the ones available. For example a 4-byte write will be 360 + emulated using four 1-byte writes, if .impl.max_access_size = 1. 361 + - .impl.unaligned specifies that the *implementation* supports unaligned 362 + accesses; if false, unaligned accesses will be emulated by two aligned 363 + accesses.
+15
docs/index.rst
··· 1 + .. QEMU documentation master file, created by 2 + sphinx-quickstart on Thu Jan 31 16:40:14 2019. 3 + You can adapt this file completely to your liking, but it should at least 4 + contain the root `toctree` directive. 5 + 6 + Welcome to QEMU's documentation! 7 + ================================ 8 + 9 + .. toctree:: 10 + :maxdepth: 2 11 + :caption: Contents: 12 + 13 + interop/index 14 + devel/index 15 +
+15
docs/interop/conf.py
··· 1 + # -*- coding: utf-8 -*- 2 + # 3 + # QEMU documentation build configuration file for the 'interop' manual. 4 + # 5 + # This includes the top level conf file and then makes any necessary tweaks. 6 + import sys 7 + import os 8 + 9 + qemu_docdir = os.path.abspath("..") 10 + parent_config = os.path.join(qemu_docdir, "conf.py") 11 + exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) 12 + 13 + # This slightly misuses the 'description', but is the best way to get 14 + # the manual title to appear in the sidebar. 15 + html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'
+18
docs/interop/index.rst
··· 1 + .. This is the top level page for the 'interop' manual. 2 + 3 + 4 + QEMU System Emulation Management and Interoperability Guide 5 + =========================================================== 6 + 7 + This manual contains documents and specifications that are useful 8 + for making QEMU interoperate with other software. 9 + 10 + Contents: 11 + 12 + .. toctree:: 13 + :maxdepth: 2 14 + 15 + bitmaps 16 + live-block-operations 17 + pr-helper 18 +