[Qemu-devel] [PATCH v6 05/17] docs: add master qapi texi files

[Marc-André Lureau]

The qapi2texi script generates a file to be included in a texi file. Add
"QEMU QMP Reference Manual" and "QEMU Guest Agent Protocol Reference"
master texi files.

Signed-off-by: Marc-André Lureau <address@hidden>
---
 docs/qapi-syntax.texi  | 175 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/qemu-ga-ref.texi  |  85 ++++++++++++++++++++++++
 docs/qemu-qmp-ref.texi |  85 ++++++++++++++++++++++++
 3 files changed, 345 insertions(+)
 create mode 100644 docs/qapi-syntax.texi
 create mode 100644 docs/qemu-ga-ref.texi
 create mode 100644 docs/qemu-qmp-ref.texi

diff --git a/docs/qapi-syntax.texi b/docs/qapi-syntax.texi
new file mode 100644
index 0000000000..117d6272d6
--- /dev/null
+++ b/docs/qapi-syntax.texi
@@ -0,0 +1,175 @@
+See QEMU @file{docs/qapi-code-gen.txt} for details about the ``Client
+JSON Protocol'' wire format. Many @b{Example} illustrate the usage of
+the various types.
+
+This reference document uses a simplified syntax for the different
+JSON expressions, of the following general form:
+
address@hidden {Type} TypeName @
address@hidden 'member': @t{type}, ['optional-member: @t{some-type}], ... @}}
+
address@hidden @asis
address@hidden @code{'member'}
+Member description
address@hidden @code{'optional-member'} *
+Optional member description
address@hidden table
address@hidden Since
+A tagged section
address@hidden quotation
address@hidden Example
address@hidden
+<- @{ "return": @{ "member": "foo", ... @} @}
address@hidden example
address@hidden quotation
address@hidden deftp
+
+The [] in the declaration and the * name prefix in the member
+description means the member is optional.
+
+A type name inside [] refers to a single-dimension array of that type.
+
address@hidden Enum documentation
+
+Enumerations are strings over the Client JSON Protocol.
+
+Example of an API documentation:
+
address@hidden Enum Enumeration
+
address@hidden @asis
address@hidden @code{'auto'}
+Description auto
address@hidden @code{'on'}
+Description on
address@hidden @code{'off'}
+Description off
address@hidden table
+An enumeration of three options: on, off, and auto
address@hidden deftp
+
address@hidden Struct documentation
+
+A struct is an Object in the Client JSON protocol, whose members are
+listed in the declaration. It may have a base structure: the members
+of the base structure are merged in the same top-level Object over the
+client protocol.
+
+The API documentation uses the following syntax for a struct:
+
address@hidden {Struct} Type @
address@hidden BaseStruct, 'foo': @t{type}, ... @}}
+
address@hidden @asis
address@hidden @code{'foo'}
+Member foo description
address@hidden table
+The type description.
address@hidden deftp
+
address@hidden Union documentation
+
+Union types are used to let the user choose between several different
+variants for an object.  There are two flavors: simple (no
+discriminator or base), and flat (both discriminator and base).
+
+In the Client JSON Protocol, a simple union is represented by a
+dictionary that contains the @t{'type'} member as a discriminator, and
+a @t{'data'} member that is of the specified data type corresponding
+to the discriminator value.
+
+The API documentation uses the following syntax for simple union:
+
address@hidden {Simple Union} SimpleUnionType @
address@hidden 'type': @t{str}, 'data': [ 'type' = 't1': @t{Type1}, 't2: 
@t{Type2}, ... ] @}}
+
+Simple union description
address@hidden deftp
+
+A flat union definition avoids nesting on the wire, and specifies a
+set of common members that occur in all variants of the union. The
+top-level members of the union dictionary on the wire will be
+combination of members from both the base type and the appropriate
+discriminated branch type.  The @t{'discriminator'} member is the name
+of a non-optional enum-typed member of the base struct.
+
+The documentation uses the following syntax for a flat union:
+
address@hidden {Flat Union} FlatUnionType @
address@hidden UnionBase, [ 'discriminator' = 'd1': @t{Type1}, 'd2': @t{Type2} 
] @}}
+
+Flat union description
address@hidden deftp
+
address@hidden Alternate documentation
+
+An alternate type is one that allows a choice between two or more JSON
+data types (string, integer, number, or object, but currently not
+array) on the wire.
+
address@hidden {Alternate} AlternateType @
+{[ 't1': @t{Type1}, 't2': @t{Type2}, ... ]}
+
address@hidden @asis
address@hidden @code{'t1'}
+Either this type
address@hidden @code{'t2'}
+Or this type
address@hidden table
+AlternateType description
address@hidden deftp
+
address@hidden Command documentation
+
+In the Client JSON Protocol, a command is a dictionary with an
address@hidden'execute'} member (the name of the command as value), and an
address@hidden'arguments'} member for the arguments. The API documentation uses
+the following syntax for a command:
+
address@hidden Command {ReturnType} query-foo @
+{('arg': @t{type}, ...)}
+
address@hidden @asis
address@hidden @code{'arg'}
+If true, the command will query...
address@hidden table
+Query for all bar...
address@hidden Returns
+The @code{ReturnType} for...
address@hidden quotation
address@hidden Example
address@hidden
+-> @{ "execute": "query-foo", "arguments": @{ "arg": ... @} @}
+<- @{
+      "return": @{ "foo": ... @}
+   @}
address@hidden example
address@hidden quotation
address@hidden deftypefn
+
address@hidden Event documentation
+
+An event is a JSON object defined by its name, used as the @t{'event'}
+member value, and a @t{'data'} member for the event members.
+
+The API documentation uses the following syntax for an event:
+
address@hidden Event {} EVENT_NAME @
+{('foo': @t{type}, ...)}
+
address@hidden @asis
address@hidden @code{'foo'}
+An event member
address@hidden table
+Event emitted when ...
address@hidden Note
+This event is rate-limited.
address@hidden quotation
address@hidden Example
address@hidden
+<-   @{ "event": "EVENT_NAME",
+       "data": @{ "param": .. @},
+       "timestamp": @{ "seconds": 1267020223, "microseconds": 435656 @} @}
address@hidden example
address@hidden quotation
address@hidden deftypefn
diff --git a/docs/qemu-ga-ref.texi b/docs/qemu-ga-ref.texi
new file mode 100644
index 0000000000..2c8ad45d49
--- /dev/null
+++ b/docs/qemu-ga-ref.texi
@@ -0,0 +1,85 @@
+\input texinfo
address@hidden qemu-ga-ref.info
+
address@hidden 0
address@hidden 0
+
address@hidden QEMU Guest Agent Protocol Reference
+
address@hidden
+This is the QEMU Guest Agent Protocol reference manual.
+
+Copyright @copyright{} 2016 The QEMU Project developers
+
address@hidden
+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/.
address@hidden quotation
address@hidden copying
+
address@hidden QEMU
address@hidden
+* QEMU-GA-Ref: (qemu-ga-ref).   QEMU Guest Agent Protocol Reference
address@hidden direntry
+
address@hidden
address@hidden Guest Agent Protocol Reference Manual
address@hidden QEMU version @value{VERSION}
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden QEMU Guest Agent protocol reference
address@hidden ifnottex
+
address@hidden
+* API Reference::
+* Documentation syntax::
+* Commands and Events Index::
+* Data Types Index::
address@hidden menu
+
address@hidden API Reference
address@hidden API Reference
+
address@hidden for texi2pod:
address@hidden man begin DESCRIPTION
+
address@hidden qemu-ga-qapi.texi
+
address@hidden man end
+
address@hidden Documentation syntax
address@hidden Documentation syntax
+
address@hidden for texi2pod:
address@hidden man begin NOTES
+
address@hidden qapi-syntax.texi
+
address@hidden man end
+
address@hidden Commands and Events Index
address@hidden Commands and Events Index
address@hidden fn
+
address@hidden Data Types Index
address@hidden Data Types Index
address@hidden tp
+
address@hidden
diff --git a/docs/qemu-qmp-ref.texi b/docs/qemu-qmp-ref.texi
new file mode 100644
index 0000000000..5fa354afa3
--- /dev/null
+++ b/docs/qemu-qmp-ref.texi
@@ -0,0 +1,85 @@
+\input texinfo
address@hidden qemu-qmp-ref.info
+
address@hidden 0
address@hidden 0
+
address@hidden QEMU QMP Reference Manual
+
address@hidden
+This is the QEMU QMP reference manual.
+
+Copyright @copyright{} 2016 The QEMU Project developers
+
address@hidden
+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/.
address@hidden quotation
address@hidden copying
+
address@hidden QEMU
address@hidden
+* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual
address@hidden direntry
+
address@hidden
address@hidden QMP Reference Manual
address@hidden QEMU version @value{VERSION}
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden QEMU QMP reference
address@hidden ifnottex
+
address@hidden
+* API Reference::
+* Documentation syntax::
+* Commands and Events Index::
+* Data Types Index::
address@hidden menu
+
address@hidden API Reference
address@hidden API Reference
+
address@hidden for texi2pod:
address@hidden man begin DESCRIPTION
+
address@hidden qemu-qapi.texi
+
address@hidden man end
+
address@hidden Documentation syntax
address@hidden Documentation syntax
+
address@hidden for texi2pod:
address@hidden man begin NOTES
+
address@hidden qapi-syntax.texi
+
address@hidden man end
+
address@hidden Commands and Events Index
address@hidden Commands and Events Index
address@hidden fn
+
address@hidden Data Types Index
address@hidden Data Types Index
address@hidden tp
+
address@hidden
-- 
2.11.0