block: implement is_allocated for raw
[qemu.git] / qapi-schema-guest.json
1 # *-*- Mode: Python -*-*
2
3 ##
4 #
5 # Echo back a unique integer value, and prepend to response a
6 # leading sentinel byte (0xFF) the client can check scan for.
7 #
8 # This is used by clients talking to the guest agent over the
9 # wire to ensure the stream is in sync and doesn't contain stale
10 # data from previous client. It must be issued upon initial
11 # connection, and after any client-side timeouts (including
12 # timeouts on receiving a response to this command).
13 #
14 # After issuing this request, all guest agent responses should be
15 # ignored until the response containing the unique integer value
16 # the client passed in is returned. Receival of the 0xFF sentinel
17 # byte must be handled as an indication that the client's
18 # lexer/tokenizer/parser state should be flushed/reset in
19 # preparation for reliably receiving the subsequent response. As
20 # an optimization, clients may opt to ignore all data until a
21 # sentinel value is receiving to avoid unnecessary processing of
22 # stale data.
23 #
24 # Similarly, clients should also precede this *request*
25 # with a 0xFF byte to make sure the guest agent flushes any
26 # partially read JSON data from a previous client connection.
27 #
28 # @id: randomly generated 64-bit integer
29 #
30 # Returns: The unique integer id passed in by the client
31 #
32 # Since: 1.1
33 # ##
34 { 'command': 'guest-sync-delimited'
35   'data':    { 'id': 'int' },
36   'returns': 'int' }
37
38 ##
39 # @guest-sync:
40 #
41 # Echo back a unique integer value
42 #
43 # This is used by clients talking to the guest agent over the
44 # wire to ensure the stream is in sync and doesn't contain stale
45 # data from previous client. All guest agent responses should be
46 # ignored until the provided unique integer value is returned,
47 # and it is up to the client to handle stale whole or
48 # partially-delivered JSON text in such a way that this response
49 # can be obtained.
50 #
51 # In cases where a partial stale response was previously
52 # received by the client, this cannot always be done reliably.
53 # One particular scenario being if qemu-ga responses are fed
54 # character-by-character into a JSON parser. In these situations,
55 # using guest-sync-delimited may be optimal.
56 #
57 # For clients that fetch responses line by line and convert them
58 # to JSON objects, guest-sync should be sufficient, but note that
59 # in cases where the channel is dirty some attempts at parsing the
60 # response may result in a parser error.
61 #
62 # Such clients should also precede this command
63 # with a 0xFF byte to make sure the guest agent flushes any
64 # partially read JSON data from a previous session.
65 #
66 # @id: randomly generated 64-bit integer
67 #
68 # Returns: The unique integer id passed in by the client
69 #
70 # Since: 0.15.0
71 ##
72 { 'command': 'guest-sync'
73   'data':    { 'id': 'int' },
74   'returns': 'int' }
75
76 ##
77 # @guest-ping:
78 #
79 # Ping the guest agent, a non-error return implies success
80 #
81 # Since: 0.15.0
82 ##
83 { 'command': 'guest-ping' }
84
85 ##
86 # @GuestAgentCommandInfo:
87 #
88 # Information about guest agent commands.
89 #
90 # @name: name of the command
91 #
92 # @enabled: whether command is currently enabled by guest admin
93 #
94 # Since 1.1.0
95 ##
96 { 'type': 'GuestAgentCommandInfo',
97   'data': { 'name': 'str', 'enabled': 'bool' } }
98
99 ##
100 # @GuestAgentInfo
101 #
102 # Information about guest agent.
103 #
104 # @version: guest agent version
105 #
106 # @supported_commands: Information about guest agent commands
107 #
108 # Since 0.15.0
109 ##
110 { 'type': 'GuestAgentInfo',
111   'data': { 'version': 'str',
112             'supported_commands': ['GuestAgentCommandInfo'] } }
113 ##
114 # @guest-info:
115 #
116 # Get some information about the guest agent.
117 #
118 # Returns: @GuestAgentInfo
119 #
120 # Since: 0.15.0
121 ##
122 { 'command': 'guest-info',
123   'returns': 'GuestAgentInfo' }
124
125 ##
126 # @guest-shutdown:
127 #
128 # Initiate guest-activated shutdown. Note: this is an asynchronous
129 # shutdown request, with no guarantee of successful shutdown.
130 #
131 # @mode: #optional "halt", "powerdown" (default), or "reboot"
132 #
133 # This command does NOT return a response on success. Success condition
134 # is indicated by the VM exiting with a zero exit status or, when
135 # running with --no-shutdown, by issuing the query-status QMP command
136 # to confirm the VM status is "shutdown".
137 #
138 # Since: 0.15.0
139 ##
140 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
141   'success-response': 'no' }
142
143 ##
144 # @guest-file-open:
145 #
146 # Open a file in the guest and retrieve a file handle for it
147 #
148 # @filepath: Full path to the file in the guest to open.
149 #
150 # @mode: #optional open mode, as per fopen(), "r" is the default.
151 #
152 # Returns: Guest file handle on success.
153 #
154 # Since: 0.15.0
155 ##
156 { 'command': 'guest-file-open',
157   'data':    { 'path': 'str', '*mode': 'str' },
158   'returns': 'int' }
159
160 ##
161 # @guest-file-close:
162 #
163 # Close an open file in the guest
164 #
165 # @handle: filehandle returned by guest-file-open
166 #
167 # Returns: Nothing on success.
168 #
169 # Since: 0.15.0
170 ##
171 { 'command': 'guest-file-close',
172   'data': { 'handle': 'int' } }
173
174 ##
175 # @GuestFileRead
176 #
177 # Result of guest agent file-read operation
178 #
179 # @count: number of bytes read (note: count is *before*
180 #         base64-encoding is applied)
181 #
182 # @buf-b64: base64-encoded bytes read
183 #
184 # @eof: whether EOF was encountered during read operation.
185 #
186 # Since: 0.15.0
187 ##
188 { 'type': 'GuestFileRead',
189   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
190
191 ##
192 # @guest-file-read:
193 #
194 # Read from an open file in the guest. Data will be base64-encoded
195 #
196 # @handle: filehandle returned by guest-file-open
197 #
198 # @count: #optional maximum number of bytes to read (default is 4KB)
199 #
200 # Returns: @GuestFileRead on success.
201 #
202 # Since: 0.15.0
203 ##
204 { 'command': 'guest-file-read',
205   'data':    { 'handle': 'int', '*count': 'int' },
206   'returns': 'GuestFileRead' }
207
208 ##
209 # @GuestFileWrite
210 #
211 # Result of guest agent file-write operation
212 #
213 # @count: number of bytes written (note: count is actual bytes
214 #         written, after base64-decoding of provided buffer)
215 #
216 # @eof: whether EOF was encountered during write operation.
217 #
218 # Since: 0.15.0
219 ##
220 { 'type': 'GuestFileWrite',
221   'data': { 'count': 'int', 'eof': 'bool' } }
222
223 ##
224 # @guest-file-write:
225 #
226 # Write to an open file in the guest.
227 #
228 # @handle: filehandle returned by guest-file-open
229 #
230 # @buf-b64: base64-encoded string representing data to be written
231 #
232 # @count: #optional bytes to write (actual bytes, after base64-decode),
233 #         default is all content in buf-b64 buffer after base64 decoding
234 #
235 # Returns: @GuestFileWrite on success.
236 #
237 # Since: 0.15.0
238 ##
239 { 'command': 'guest-file-write',
240   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
241   'returns': 'GuestFileWrite' }
242
243
244 ##
245 # @GuestFileSeek
246 #
247 # Result of guest agent file-seek operation
248 #
249 # @position: current file position
250 #
251 # @eof: whether EOF was encountered during file seek
252 #
253 # Since: 0.15.0
254 ##
255 { 'type': 'GuestFileSeek',
256   'data': { 'position': 'int', 'eof': 'bool' } }
257
258 ##
259 # @guest-file-seek:
260 #
261 # Seek to a position in the file, as with fseek(), and return the
262 # current file position afterward. Also encapsulates ftell()'s
263 # functionality, just Set offset=0, whence=SEEK_CUR.
264 #
265 # @handle: filehandle returned by guest-file-open
266 #
267 # @offset: bytes to skip over in the file stream
268 #
269 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
270 #
271 # Returns: @GuestFileSeek on success.
272 #
273 # Since: 0.15.0
274 ##
275 { 'command': 'guest-file-seek',
276   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
277   'returns': 'GuestFileSeek' }
278
279 ##
280 # @guest-file-flush:
281 #
282 # Write file changes bufferred in userspace to disk/kernel buffers
283 #
284 # @handle: filehandle returned by guest-file-open
285 #
286 # Returns: Nothing on success.
287 #
288 # Since: 0.15.0
289 ##
290 { 'command': 'guest-file-flush',
291   'data': { 'handle': 'int' } }
292
293 ##
294 # @GuestFsFreezeStatus
295 #
296 # An enumation of filesystem freeze states
297 #
298 # @thawed: filesystems thawed/unfrozen
299 #
300 # @frozen: all non-network guest filesystems frozen
301 #
302 # Since: 0.15.0
303 ##
304 { 'enum': 'GuestFsfreezeStatus',
305   'data': [ 'thawed', 'frozen' ] }
306
307 ##
308 # @guest-fsfreeze-status:
309 #
310 # Get guest fsfreeze state. error state indicates
311 #
312 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
313 #
314 # Note: This may fail to properly report the current state as a result of
315 # some other guest processes having issued an fs freeze/thaw.
316 #
317 # Since: 0.15.0
318 ##
319 { 'command': 'guest-fsfreeze-status',
320   'returns': 'GuestFsfreezeStatus' }
321
322 ##
323 # @guest-fsfreeze-freeze:
324 #
325 # Sync and freeze all freezable, local guest filesystems
326 #
327 # Returns: Number of file systems currently frozen. On error, all filesystems
328 # will be thawed.
329 #
330 # Since: 0.15.0
331 ##
332 { 'command': 'guest-fsfreeze-freeze',
333   'returns': 'int' }
334
335 ##
336 # @guest-fsfreeze-thaw:
337 #
338 # Unfreeze all frozen guest filesystems
339 #
340 # Returns: Number of file systems thawed by this call
341 #
342 # Note: if return value does not match the previous call to
343 #       guest-fsfreeze-freeze, this likely means some freezable
344 #       filesystems were unfrozen before this call, and that the
345 #       filesystem state may have changed before issuing this
346 #       command.
347 #
348 # Since: 0.15.0
349 ##
350 { 'command': 'guest-fsfreeze-thaw',
351   'returns': 'int' }
352
353 ##
354 # @guest-suspend-disk
355 #
356 # Suspend guest to disk.
357 #
358 # This command tries to execute the scripts provided by the pm-utils package.
359 # If it's not available, the suspend operation will be performed by manually
360 # writing to a sysfs file.
361 #
362 # For the best results it's strongly recommended to have the pm-utils
363 # package installed in the guest.
364 #
365 # This command does NOT return a response on success. There is a high chance
366 # the command succeeded if the VM exits with a zero exit status or, when
367 # running with --no-shutdown, by issuing the query-status QMP command to
368 # to confirm the VM status is "shutdown". However, the VM could also exit
369 # (or set its status to "shutdown") due to other reasons.
370 #
371 # The following errors may be returned:
372 #          If suspend to disk is not supported, Unsupported
373 #
374 # Notes: It's strongly recommended to issue the guest-sync command before
375 #        sending commands when the guest resumes
376 #
377 # Since: 1.1
378 ##
379 { 'command': 'guest-suspend-disk', 'success-response': 'no' }
380
381 ##
382 # @guest-suspend-ram
383 #
384 # Suspend guest to ram.
385 #
386 # This command tries to execute the scripts provided by the pm-utils package.
387 # If it's not available, the suspend operation will be performed by manually
388 # writing to a sysfs file.
389 #
390 # For the best results it's strongly recommended to have the pm-utils
391 # package installed in the guest.
392 #
393 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
394 # command.  Thus, it's *required* to query QEMU for the presence of the
395 # 'system_wakeup' command before issuing guest-suspend-ram.
396 #
397 # This command does NOT return a response on success. There are two options
398 # to check for success:
399 #   1. Wait for the SUSPEND QMP event from QEMU
400 #   2. Issue the query-status QMP command to confirm the VM status is
401 #      "suspended"
402 #
403 # The following errors may be returned:
404 #          If suspend to ram is not supported, Unsupported
405 #
406 # Notes: It's strongly recommended to issue the guest-sync command before
407 #        sending commands when the guest resumes
408 #
409 # Since: 1.1
410 ##
411 { 'command': 'guest-suspend-ram', 'success-response': 'no' }
412
413 ##
414 # @guest-suspend-hybrid
415 #
416 # Save guest state to disk and suspend to ram.
417 #
418 # This command requires the pm-utils package to be installed in the guest.
419 #
420 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
421 # command.  Thus, it's *required* to query QEMU for the presence of the
422 # 'system_wakeup' command before issuing guest-suspend-hybrid.
423 #
424 # This command does NOT return a response on success. There are two options
425 # to check for success:
426 #   1. Wait for the SUSPEND QMP event from QEMU
427 #   2. Issue the query-status QMP command to confirm the VM status is
428 #      "suspended"
429 #
430 # The following errors may be returned:
431 #          If hybrid suspend is not supported, Unsupported
432 #
433 # Notes: It's strongly recommended to issue the guest-sync command before
434 #        sending commands when the guest resumes
435 #
436 # Since: 1.1
437 ##
438 { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
439
440 ##
441 # @GuestIpAddressType:
442 #
443 # An enumeration of supported IP address types
444 #
445 # @ipv4: IP version 4
446 #
447 # @ipv6: IP version 6
448 #
449 # Since: 1.1
450 ##
451 { 'enum': 'GuestIpAddressType',
452   'data': [ 'ipv4', 'ipv6' ] }
453
454 ##
455 # @GuestIpAddress:
456 #
457 # @ip-address: IP address
458 #
459 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
460 #
461 # @prefix: Network prefix length of @ip-address
462 #
463 # Since: 1.1
464 ##
465 { 'type': 'GuestIpAddress',
466   'data': {'ip-address': 'str',
467            'ip-address-type': 'GuestIpAddressType',
468            'prefix': 'int'} }
469
470 ##
471 # @GuestNetworkInterface:
472 #
473 # @name: The name of interface for which info are being delivered
474 #
475 # @hardware-address: Hardware address of @name
476 #
477 # @ip-addresses: List of addresses assigned to @name
478 #
479 # Since: 1.1
480 ##
481 { 'type': 'GuestNetworkInterface',
482   'data': {'name': 'str',
483            '*hardware-address': 'str',
484            '*ip-addresses': ['GuestIpAddress'] } }
485
486 ##
487 # @guest-network-get-interfaces:
488 #
489 # Get list of guest IP addresses, MAC addresses
490 # and netmasks.
491 #
492 # Returns: List of GuestNetworkInfo on success.
493 #
494 # Since: 1.1
495 ##
496 { 'command': 'guest-network-get-interfaces',
497   'returns': ['GuestNetworkInterface'] }