← Back to branch summary

~ubuntu-branches/ubuntu/trusty/qemu/trusty

« back to all changes in this revision

Viewing changes to docs/qapi-code-gen.txt

  • Committer: Package Import Robot
  • Author(s): Serge Hallyn
  • Date: 2013-10-22 22:47:07 UTC
  • mfrom: (1.8.3) (10.1.42 sid)
  • Revision ID: package-import@ubuntu.com-20131022224707-1lya34fw3k3f24tv
Tags: 1.6.0+dfsg-2ubuntu1
http://bugs.debian.org/709241
* Merge 1.6.0~rc0+dfsg-2exp from debian experimental.  Remaining changes:
  - debian/control
    * update maintainer
    * remove libiscsi, usb-redir, vde, vnc-jpeg, and libssh2-1-dev
      from build-deps
    * enable rbd
    * add qemu-system and qemu-common B/R to qemu-keymaps
    * add D:udev, R:qemu, R:qemu-common and B:qemu-common to
      qemu-system-common
    * qemu-system-arm, qemu-system-ppc, qemu-system-sparc:
      - add qemu-kvm to Provides
      - add qemu-common, qemu-kvm, kvm to B/R
      - remove openbios-sparc from qemu-system-sparc D
      - drop openbios-ppc and openhackware Depends to Suggests (for now)
    * qemu-system-x86:
      - add qemu-common to Breaks/Replaces.
      - add cpu-checker to Recommends.
    * qemu-user: add B/R:qemu-kvm
    * qemu-kvm:
      - add armhf armel powerpc sparc to Architecture
      - C/R/P: qemu-kvm-spice
    * add qemu-common package
    * drop qemu-slof which is not packaged in ubuntu
  - add qemu-system-common.links for tap ifup/down scripts and OVMF link.
  - qemu-system-x86.links:
    * remove pxe rom links which are in kvm-ipxe
    * add symlink for kvm.1 manpage
  - debian/rules
    * add kvm-spice symlink to qemu-kvm
    * call dh_installmodules for qemu-system-x86
    * update dh_installinit to install upstart script
    * run dh_installman (Closes: #709241) (cherrypicked from 1.5.0+dfsg-2)
  - Add qemu-utils.links for kvm-* symlinks.
  - Add qemu-system-x86.qemu-kvm.upstart and .default
  - Add qemu-system-x86.modprobe to set nesting=1
  - Add qemu-system-common.preinst to add kvm group
  - qemu-system-common.postinst: remove bad group acl if there, then have
    udev relabel /dev/kvm.
  - New linaro patches from qemu-linaro rebasing branch
  - Dropped patches:
    * xen-simplify-xen_enabled.patch
    * sparc-linux-user-fix-missing-symbols-in-.rel-.rela.plt-sections.patch
    * main_loop-do-not-set-nonblocking-if-xen_enabled.patch
    * xen_machine_pv-do-not-create-a-dummy-CPU-in-machine-.patch
    * virtio-rng-fix-crash
  - Kept patches:
    * expose_vms_qemu64cpu.patch - updated
    * linaro arm patches from qemu-linaro rebasing branch
  - New patches:
    * fix-pci-add: change CONFIG variable in ifdef to make sure that
      pci_add is defined.
* Add linaro patches
* Add experimental mach-virt patches for arm virtualization.
* qemu-system-common.install: add debian/tmp/usr/lib to install the
  qemu-bridge-helper

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/qapi-code-gen.txt
34
34
There are two basic syntaxes used, type definitions and command definitions.
35
35
 
36
36
The first syntax defines a type and is represented by a dictionary.  There are
37
 
two kinds of types that are supported: complex user-defined types, and enums.
38
 
 
39
 
A complex type is a dictionary containing a single key who's value is a
 
37
three kinds of user-defined types that are supported: complex types,
 
38
enumeration types and union types.
 
39
 
 
40
Generally speaking, types definitions should always use CamelCase for the type
 
41
names. Command names should be all lower case with words separated by a hyphen.
 
42
 
 
43
=== Complex types ===
 
44
 
 
45
A complex type is a dictionary containing a single key whose value is a
40
46
dictionary.  This corresponds to a struct in C or an Object in JSON.  An
41
47
example of a complex type is:
42
48
 
47
53
members should always be added to the end of the dictionary to preserve
48
54
backwards compatibility.
49
55
 
50
 
An enumeration type is a dictionary containing a single key who's value is a
 
56
=== Enumeration types ===
 
57
 
 
58
An enumeration type is a dictionary containing a single key whose value is a
51
59
list of strings.  An example enumeration is:
52
60
 
53
61
 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
54
62
 
55
 
Generally speaking, complex types and enums should always use CamelCase for
56
 
the type names.
 
63
=== Union types ===
 
64
 
 
65
Union types are used to let the user choose between several different data
 
66
types.  A union type is defined using a dictionary as explained in the
 
67
following paragraphs.
 
68
 
 
69
 
 
70
A simple union type defines a mapping from discriminator values to data types
 
71
like in this example:
 
72
 
 
73
 { 'type': 'FileOptions', 'data': { 'filename': 'str' } }
 
74
 { 'type': 'Qcow2Options',
 
75
   'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
 
76
 
 
77
 { 'union': 'BlockdevOptions',
 
78
   'data': { 'file': 'FileOptions',
 
79
             'qcow2': 'Qcow2Options' } }
 
80
 
 
81
In the QMP wire format, a simple union is represented by a dictionary that
 
82
contains the 'type' field as a discriminator, and a 'data' field that is of the
 
83
specified data type corresponding to the discriminator value:
 
84
 
 
85
 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
 
86
                               "lazy-refcounts": true } }
 
87
 
 
88
 
 
89
A union definition can specify a complex type as its base. In this case, the
 
90
fields of the complex type are included as top-level fields of the union
 
91
dictionary in the QMP wire format. An example definition is:
 
92
 
 
93
 { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
 
94
 { 'union': 'BlockdevOptions',
 
95
   'base': 'BlockdevCommonOptions',
 
96
   'data': { 'raw': 'RawOptions',
 
97
             'qcow2': 'Qcow2Options' } }
 
98
 
 
99
And it looks like this on the wire:
 
100
 
 
101
 { "type": "qcow2",
 
102
   "readonly": false,
 
103
   "data" : { "backing-file": "/some/place/my-image",
 
104
              "lazy-refcounts": true } }
 
105
 
 
106
 
 
107
Flat union types avoid the nesting on the wire. They are used whenever a
 
108
specific field of the base type is declared as the discriminator ('type' is
 
109
then no longer generated). The discriminator must always be a string field.
 
110
The above example can then be modified as follows:
 
111
 
 
112
 { 'type': 'BlockdevCommonOptions',
 
113
   'data': { 'driver': 'str', 'readonly': 'bool' } }
 
114
 { 'union': 'BlockdevOptions',
 
115
   'base': 'BlockdevCommonOptions',
 
116
   'discriminator': 'driver',
 
117
   'data': { 'raw': 'RawOptions',
 
118
             'qcow2': 'Qcow2Options' } }
 
119
 
 
120
Resulting in this JSON object:
 
121
 
 
122
 { "driver": "qcow2",
 
123
   "readonly": false,
 
124
   "backing-file": "/some/place/my-image",
 
125
   "lazy-refcounts": true }
 
126
 
 
127
 
 
128
A special type of unions are anonymous unions. They don't form a dictionary in
 
129
the wire format but allow the direct use of different types in their place. As
 
130
they aren't structured, they don't have any explicit discriminator but use
 
131
the (QObject) data type of their value as an implicit discriminator. This means
 
132
that they are restricted to using only one discriminator value per QObject
 
133
type. For example, you cannot have two different complex types in an anonymous
 
134
union, or two different integer types.
 
135
 
 
136
Anonymous unions are declared using an empty dictionary as their discriminator.
 
137
The discriminator values never appear on the wire, they are only used in the
 
138
generated C code. Anonymous unions cannot have a base type.
 
139
 
 
140
 { 'union': 'BlockRef',
 
141
   'discriminator': {},
 
142
   'data': { 'definition': 'BlockdevOptions',
 
143
             'reference': 'str' } }
 
144
 
 
145
This example allows using both of the following example objects:
 
146
 
 
147
 { "file": "my_existing_block_device_id" }
 
148
 { "file": { "driver": "file",
 
149
             "readonly": false,
 
150
             'filename': "/tmp/mydisk.qcow2" } }
 
151
 
 
152
 
 
153
=== Commands ===
57
154
 
58
155
Commands are defined by using a list containing three members.  The first
59
156
member is the command name, the second member is a dictionary containing
65
162
   'data': { 'arg1': 'str', '*arg2': 'str' },
66
163
   'returns': 'str' }
67
164
 
68
 
Command names should be all lower case with words separated by a hyphen.
69
 
 
70
165
 
71
166
== Code generation ==
72
167