Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-01-16' into staging (23eb9e6b) · Commits · SUMMER2020 / students / proj-2021291

.gitignore

+10 −1

Original line number	Diff line number	Diff line
		@@ -40,6 +40,7 @@
		/qmp-marshal.c
		/qemu-doc.html
		/qemu-doc.info
		/qemu-doc.txt
		/qemu-img
		/qemu-nbd
		/qemu-options.def
		@@ -60,7 +61,6 @@
		*.a
		*.aux
		*.cp
		*.dvi
		*.exe
		*.msi
		*.dll
		@@ -105,6 +105,15 @@
		/pc-bios/optionrom/kvmvapic.img
		/pc-bios/s390-ccw/s390-ccw.elf
		/pc-bios/s390-ccw/s390-ccw.img
		/docs/qemu-ga-ref.html
		/docs/qemu-ga-ref.txt
		/docs/qemu-qmp-ref.html
		/docs/qemu-qmp-ref.txt
		docs/qemu-ga-ref.info*
		docs/qemu-qmp-ref.info*
		/qemu-ga-qapi.texi
		/qemu-qapi.texi
		*.tps
		.stgit-*
		cscope.*
		tags

Makefile

+50 −44

Original line number	Diff line number	Diff line
		@@ -80,8 +80,8 @@ GENERATED_HEADERS += module_block.h
		Makefile: ;
		configure: ;

		.PHONY: all clean cscope distclean dvi html info install install-doc \
		pdf recurse-all speed test dist msi FORCE
		.PHONY: all clean cscope distclean html info install install-doc \
		pdf txt recurse-all speed test dist msi FORCE

		$(call set-vpath, $(SRC_PATH))

		@@ -90,7 +90,9 @@ LIBS+=-lz $(LIBS_TOOLS)
		HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)

		ifdef BUILD_DOCS
		DOCS=qemu-doc.html qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
		DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
		DOCS+=docs/qemu-qmp-ref.html docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7
		DOCS+=docs/qemu-ga-ref.html docs/qemu-ga-ref.txt docs/qemu-ga-ref.7
		ifdef CONFIG_VIRTFS
		DOCS+=fsdev/virtfs-proxy-helper.1
		endif
		@@ -265,6 +267,7 @@ qemu-ga$(EXESUF): QEMU_CFLAGS += -I qga/qapi-generated
		gen-out-type = $(subst .,-,$(suffix $@))

		qapi-py = $(SRC_PATH)/scripts/qapi.py $(SRC_PATH)/scripts/ordereddict.py
		qapi-py += $(SRC_PATH)/scripts/qapi2texi.py

		qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h :\
		$(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-types.py $(qapi-py)
		@@ -387,12 +390,17 @@ distclean: clean
		rm -f config-all-devices.mak config-all-disas.mak config.status
		rm -f po/*.mo tests/qemu-iotests/common.env
		rm -f roms/seabios/config.mak roms/vgabios/config.mak
		rm -f qemu-doc.info qemu-doc.aux qemu-doc.cp qemu-doc.cps qemu-doc.dvi
		rm -f qemu-doc.info qemu-doc.aux qemu-doc.cp qemu-doc.cps
		rm -f qemu-doc.fn qemu-doc.fns qemu-doc.info qemu-doc.ky qemu-doc.kys
		rm -f qemu-doc.log qemu-doc.pdf qemu-doc.pg qemu-doc.toc qemu-doc.tp
		rm -f qemu-doc.vr
		rm -f config.log
		rm -f linux-headers/asm
		rm -f qemu-ga-qapi.texi qemu-qapi.texi
		rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7
		rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt
		rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
		rm -f docs/qemu-qmp-ref.html docs/qemu-ga-ref.html
		for d in $(TARGET_DIRS); do \
		rm -rf $$d \|\| exit 1 ; \
		done
		@@ -429,10 +437,14 @@ endif
		install-doc: $(DOCS)
		$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) $(SRC_PATH)/docs/qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) docs/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) docs/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
		ifdef CONFIG_POSIX
		$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
		$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
		$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
		$(INSTALL_DATA) docs/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
		ifneq ($(TOOLS),)
		$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
		$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
		@@ -440,6 +452,9 @@ ifneq ($(TOOLS),)
		endif
		ifneq (,$(findstring qemu-ga,$(TOOLS)))
		$(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
		$(INSTALL_DATA) docs/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) docs/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) docs/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
		endif
		endif
		ifdef CONFIG_VIRTFS
		@@ -527,21 +542,23 @@ ui/console-gl.o: $(SRC_PATH)/ui/console-gl.c \
		ui/shader/texture-blit-vert.h ui/shader/texture-blit-frag.h

		# documentation
		MAKEINFO=makeinfo
		MAKEINFOFLAGS=--no-headers --no-split --number-sections
		TEXIFLAG=$(if $(V),,--quiet)
		%.dvi: %.texi
		$(call quiet-command,texi2dvi $(TEXIFLAG) -I . $<,"GEN","$@")
		MAKEINFO=makeinfo -D 'VERSION $(VERSION)'
		MAKEINFOFLAGS=--no-split --number-sections
		TEXIFLAG=$(if $(V),,--quiet) --command='@set VERSION $(VERSION)'

		%.html: %.texi
		$(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --html $< -o $@, \
		"GEN","$@")
		$(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers \
		--html $< -o $@,"GEN","$@")

		%.info: %.texi
		$(call quiet-command,$(MAKEINFO) $< -o $@,"GEN","$@")
		$(call quiet-command,$(MAKEINFO) $(MAKEINFOFLAGS) $< -o $@,"GEN","$@")

		%.txt: %.texi
		$(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers \
		--plaintext $< -o $@,"GEN","$@")

		%.pdf: %.texi
		$(call quiet-command,texi2pdf $(TEXIFLAG) -I . $<,"GEN","$@")
		$(call quiet-command,texi2pdf $(TEXIFLAG) -I $(SRC_PATH) -I . $< -o $@,"GEN","$@")

		qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
		$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
		@@ -555,47 +572,36 @@ qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxt
		qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool
		$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")

		qemu-qapi.texi: $(qapi-modules) $(qapi-py)
		$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > $@,"GEN" "$@")

		qemu-ga-qapi.texi: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py)
		$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > $@,"GEN","$@")

		qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
		$(call quiet-command, \
		perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
		$(POD2MAN) --section=1 --center=" " --release=" " qemu.pod > $@, \
		"GEN","$@")
		qemu.1: qemu-option-trace.texi

		qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
		$(call quiet-command, \
		perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-img.pod && \
		$(POD2MAN) --section=1 --center=" " --release=" " qemu-img.pod > $@, \
		"GEN","$@")

		fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
		$(call quiet-command, \
		perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< fsdev/virtfs-proxy-helper.pod && \
		$(POD2MAN) --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
		"GEN","$@")

		qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
		$(call quiet-command, \
		perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-nbd.pod && \
		$(POD2MAN) --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
		"GEN","$@")

		qemu-ga.8: qemu-ga.texi
		$(call quiet-command, \
		perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-ga.pod && \
		$(POD2MAN) --section=8 --center=" " --release=" " qemu-ga.pod > $@, \
		"GEN","$@")

		dvi: qemu-doc.dvi
		html: qemu-doc.html
		info: qemu-doc.info
		pdf: qemu-doc.pdf
		html: qemu-doc.html docs/qemu-qmp-ref.html docs/qemu-ga-ref.html
		info: qemu-doc.info docs/qemu-qmp-ref.info docs/qemu-ga-ref.info
		pdf: qemu-doc.pdf docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
		txt: qemu-doc.txt docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt

		qemu-doc.dvi qemu-doc.html qemu-doc.info qemu-doc.pdf: \
		qemu-doc.html qemu-doc.info qemu-doc.pdf: \
		qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
		qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
		qemu-monitor-info.texi

		docs/qemu-ga-ref.dvi docs/qemu-ga-ref.html docs/qemu-ga-ref.info docs/qemu-ga-ref.pdf docs/qemu-ga-ref.txt docs/qemu-ga-ref.7: \
		docs/qemu-ga-ref.texi qemu-ga-qapi.texi

		docs/qemu-qmp-ref.dvi docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7: \
		docs/qemu-qmp-ref.texi qemu-qapi.texi


		ifdef CONFIG_WIN32

		INSTALLER = qemu-setup-$(VERSION)$(EXESUF)
		@@ -688,7 +694,7 @@ help:
		@echo ' docker - Help about targets running tests inside Docker containers'
		@echo ''
		@echo 'Documentation targets:'
		@echo ' dvi html info pdf'
		@echo ' html info pdf txt'
		@echo ' - Build documentation in specified format'
		@echo ''
		ifdef CONFIG_WIN32

configure

+1 −1

Original line number	Diff line number	Diff line
		@@ -6198,7 +6198,7 @@ fi

		# build tree in object directory in case the source is not in the current directory
		DIRS="tests tests/tcg tests/tcg/cris tests/tcg/lm32 tests/libqos tests/qapi-schema tests/tcg/xtensa tests/qemu-iotests"
		DIRS="$DIRS fsdev"
		DIRS="$DIRS docs fsdev"
		DIRS="$DIRS pc-bios/optionrom pc-bios/spapr-rtas pc-bios/s390-ccw"
		DIRS="$DIRS roms/seabios roms/vgabios"
		DIRS="$DIRS qapi-generated"

docs/qapi-code-gen.txt

+147 −33

Original line number	Diff line number	Diff line
		@@ -44,18 +44,103 @@ Input must be ASCII (although QMP supports full Unicode strings, the
		QAPI parser does not). At present, there is no place where a QAPI
		schema requires the use of JSON numbers or null.


		=== Comments ===

		Comments are allowed; anything between an unquoted # and the following
		newline is ignored. Although there is not yet a documentation
		generator, a form of stylized comments has developed for consistently
		documenting details about an expression and when it was added to the
		schema. The documentation is delimited between two lines of ##, then
		the first line names the expression, an optional overview is provided,
		then individual documentation about each member of 'data' is provided,
		and finally, a 'Since: x.y.z' tag lists the release that introduced
		the expression. Optional members are tagged with the phrase
		'#optional', often with their default value; and extensions added
		after the expression was first released are also given a '(since
		x.y.z)' comment. For example:
		newline is ignored.

		A multi-line comment that starts and ends with a '##' line is a
		documentation comment. These are parsed by the documentation
		generator, which recognizes certain markup detailed below.


		==== Documentation markup ====

		Comment text starting with '=' is a section title:

		# = Section title

		Double the '=' for a subsection title:

		# == Subection title

		'\|' denotes examples:

		# \| Text of the example, may span
		# \| multiple lines

		'*' starts an itemized list:

		# * First item, may span
		# multiple lines
		# * Second item

		You can also use '-' instead of '*'.

		A decimal number followed by '.' starts a numbered list:

		# 1. First item, may span
		# multiple lines
		# 2. Second item

		The actual number doesn't matter. You could even use '*' instead of
		'2.' for the second item.

		Lists can't be nested. Blank lines are currently not supported within
		lists.

		Additional whitespace between the initial '#' and the comment text is
		permitted.

		foo and _foo_ are for strong and emphasis styles respectively (they
		do not work over multiple lines). @foo is used to reference a name in
		the schema.

		Example:

		##
		# = Section
		# == Subsection
		#
		# Some text foo with strong and _emphasis_
		# 1. with a list
		# 2. like that
		#
		# And some code:
		# \| $ echo foo
		# \| -> do this
		# \| <- get that
		#
		##


		==== Expression documentation ====

		Each expression that isn't an include directive must be preceded by a
		documentation block. Such blocks are called expression documentation
		blocks.

		The documentation block consists of a first line naming the
		expression, an optional overview, a description of each argument (for
		commands and events) or member (for structs, unions and alternates),
		and optional tagged sections.

		FIXME: the parser accepts these things in almost any order.

		Optional arguments / members are tagged with the phrase '#optional',
		often with their default value; and extensions added after the
		expression was first released are also given a '(since x.y.z)'
		comment.

		A tagged section starts with one of the following words:
		"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
		The section ends with the start of a new section.

		A 'Since: x.y.z' tagged section lists the release that introduced the
		expression.

		For example:

		##
		# @BlockStats:
		@@ -65,19 +150,48 @@ x.y.z)' comment. For example:
		# @device: #optional If the stats are for a virtual block device, the name
		# corresponding to the virtual block device.
		#
		# @stats: A @BlockDeviceStats for the device.
		# @node-name: #optional The node name of the device. (since 2.3)
		#
		# @parent: #optional This describes the file block device if it has one.
		#
		# @backing: #optional This describes the backing block device if it has one.
		# (Since 2.0)
		# ... more members ...
		#
		# Since: 0.14.0
		##
		{ 'struct': 'BlockStats',
		'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
		'*parent': 'BlockStats',
		'*backing': 'BlockStats'} }
		'data': {'device': 'str', 'node-name': 'str',
		... more members ... } }

		##
		# @query-blockstats:
		#
		# Query the @BlockStats for all virtual block devices.
		#
		# @query-nodes: #optional If true, the command will query all the
		# block nodes ... explain, explain ... (since 2.3)
		#
		# Returns: A list of @BlockStats for each virtual block devices.
		#
		# Since: 0.14.0
		#
		# Example:
		#
		# -> { "execute": "query-blockstats" }
		# <- {
		# ... lots of output ...
		# }
		#
		##
		{ 'command': 'query-blockstats',
		'data': { '*query-nodes': 'bool' },
		'returns': ['BlockStats'] }

		==== Free-form documentation ====

		A documentation block that isn't an expression documentation block is
		a free-form documentation block. These may be used to provide
		additional text and structuring content.


		=== Schema overview ===

		The schema sets up a series of types, as well as commands and events
		that will use those types. Forward references are allowed: the parser

docs/qemu-ga-ref.texi

0 → 100644

+78 −0

Original line number	Diff line number	Diff line
		\input texinfo
		@setfilename qemu-ga-ref.info

		@exampleindent 0
		@paragraphindent 0

		@settitle QEMU Guest Agent Protocol Reference

		@iftex
		@center @image{docs/qemu_logo}
		@end iftex

		@copying
		This is the QEMU Guest Agent Protocol reference manual.

		Copyright @copyright{} 2016 The QEMU Project developers

		@quotation
		This manual is free documentation: you can redistribute it and/or
		modify it under the terms of the GNU General Public License as
		published by the Free Software Foundation, either version 2 of the
		License, or (at your option) any later version.

		This manual is distributed in the hope that it will be useful, but
		WITHOUT ANY WARRANTY; without even the implied warranty of
		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
		General Public License for more details.

		You should have received a copy of the GNU General Public License
		along with this manual. If not, see http://www.gnu.org/licenses/.
		@end quotation
		@end copying

		@dircategory QEMU
		@direntry
		* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference
		@end direntry

		@titlepage
		@title Guest Agent Protocol Reference Manual
		@subtitle QEMU version @value{VERSION}
		@page
		@vskip 0pt plus 1filll
		@insertcopying
		@end titlepage

		@contents

		@ifnottex
		@node Top
		@top QEMU Guest Agent protocol reference
		@end ifnottex

		@menu
		* API Reference::
		* Commands and Events Index::
		* Data Types Index::
		@end menu

		@node API Reference
		@chapter API Reference

		@c for texi2pod:
		@c man begin DESCRIPTION

		@include qemu-ga-qapi.texi

		@c man end

		@node Commands and Events Index
		@unnumbered Commands and Events Index
		@printindex fn

		@node Data Types Index
		@unnumbered Data Types Index
		@printindex tp

		@bye