xref: /openbmc/qemu/qapi/block.json (revision 01bed0ff)
1# -*- Mode: Python -*-
2# vim: filetype=python
3
4##
5# = Block devices
6##
7
8{ 'include': 'block-core.json' }
9
10##
11# == Additional block stuff (VM related)
12##
13
14##
15# @BiosAtaTranslation:
16#
17# Policy that BIOS should use to interpret cylinder/head/sector
18# addresses.  Note that Bochs BIOS and SeaBIOS will not actually
19# translate logical CHS to physical; instead, they will use logical
20# block addressing.
21#
22# @auto: If cylinder/heads/sizes are passed, choose between none and
23#     LBA depending on the size of the disk.  If they are not passed,
24#     choose none if QEMU can guess that the disk had 16 or fewer
25#     heads, large if QEMU can guess that the disk had 131072 or fewer
26#     tracks across all heads (i.e. cylinders*heads<131072), otherwise
27#     LBA.
28#
29# @none: The physical disk geometry is equal to the logical geometry.
30#
31# @lba: Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
32#     heads (if fewer than 255 are enough to cover the whole disk with
33#     1024 cylinders/head).  The number of cylinders/head is then
34#     computed based on the number of sectors and heads.
35#
36# @large: The number of cylinders per head is scaled down to 1024 by
37#     correspondingly scaling up the number of heads.
38#
39# @rechs: Same as @large, but first convert a 16-head geometry to
40#     15-head, by proportionally scaling up the number of
41#     cylinders/head.
42#
43# Since: 2.0
44##
45{ 'enum': 'BiosAtaTranslation',
46  'data': ['auto', 'none', 'lba', 'large', 'rechs']}
47
48##
49# @FloppyDriveType:
50#
51# Type of Floppy drive to be emulated by the Floppy Disk Controller.
52#
53# @144: 1.44MB 3.5" drive
54#
55# @288: 2.88MB 3.5" drive
56#
57# @120: 1.2MB 5.25" drive
58#
59# @none: No drive connected
60#
61# @auto: Automatically determined by inserted media at boot
62#
63# Since: 2.6
64##
65{ 'enum': 'FloppyDriveType',
66  'data': ['144', '288', '120', 'none', 'auto']}
67
68##
69# @PRManagerInfo:
70#
71# Information about a persistent reservation manager
72#
73# @id: the identifier of the persistent reservation manager
74#
75# @connected: true if the persistent reservation manager is connected
76#     to the underlying storage or helper
77#
78# Since: 3.0
79##
80{ 'struct': 'PRManagerInfo',
81  'data': {'id': 'str', 'connected': 'bool'} }
82
83##
84# @query-pr-managers:
85#
86# Returns a list of information about each persistent reservation
87# manager.
88#
89# Returns: a list of @PRManagerInfo for each persistent reservation
90#     manager
91#
92# Since: 3.0
93##
94{ 'command': 'query-pr-managers', 'returns': ['PRManagerInfo'],
95  'allow-preconfig': true }
96
97##
98# @eject:
99#
100# Ejects the medium from a removable drive.
101#
102# @device: Block device name
103#
104# @id: The name or QOM path of the guest device (since: 2.8)
105#
106# @force: If true, eject regardless of whether the drive is locked.
107#     If not specified, the default value is false.
108#
109# Features:
110#
111# @deprecated: Member @device is deprecated.  Use @id instead.
112#
113# Errors:
114#     - If @device is not a valid block device, DeviceNotFound
115#
116# .. note:: Ejecting a device with no media results in success.
117#
118# Since: 0.14
119#
120# .. qmp-example::
121#
122#     -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
123#     <- { "return": {} }
124##
125{ 'command': 'eject',
126  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
127            '*id': 'str',
128            '*force': 'bool' } }
129
130##
131# @blockdev-open-tray:
132#
133# Opens a block device's tray.  If there is a block driver state tree
134# inserted as a medium, it will become inaccessible to the guest (but
135# it will remain associated to the block device, so closing the tray
136# will make it accessible again).
137#
138# If the tray was already open before, this will be a no-op.
139#
140# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted.  There
141# are cases in which no such event will be generated, these include:
142#
143# - if the guest has locked the tray, @force is false and the guest
144#   does not respond to the eject request
145# - if the BlockBackend denoted by @device does not have a guest
146#   device attached to it
147# - if the guest device does not have an actual tray
148#
149# @device: Block device name
150#
151# @id: The name or QOM path of the guest device (since: 2.8)
152#
153# @force: if false (the default), an eject request will be sent to the
154#     guest if it has locked the tray (and the tray will not be opened
155#     immediately); if true, the tray will be opened regardless of
156#     whether it is locked
157#
158# Features:
159#
160# @deprecated: Member @device is deprecated.  Use @id instead.
161#
162# Since: 2.5
163#
164# .. qmp-example::
165#
166#     -> { "execute": "blockdev-open-tray",
167#          "arguments": { "id": "ide0-1-0" } }
168#
169#     <- { "timestamp": { "seconds": 1418751016,
170#                         "microseconds": 716996 },
171#          "event": "DEVICE_TRAY_MOVED",
172#          "data": { "device": "ide1-cd0",
173#                    "id": "ide0-1-0",
174#                    "tray-open": true } }
175#
176#     <- { "return": {} }
177##
178{ 'command': 'blockdev-open-tray',
179  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
180            '*id': 'str',
181            '*force': 'bool' } }
182
183##
184# @blockdev-close-tray:
185#
186# Closes a block device's tray.  If there is a block driver state tree
187# associated with the block device (which is currently ejected), that
188# tree will be loaded as the medium.
189#
190# If the tray was already closed before, this will be a no-op.
191#
192# @device: Block device name
193#
194# @id: The name or QOM path of the guest device (since: 2.8)
195#
196# Features:
197#
198# @deprecated: Member @device is deprecated.  Use @id instead.
199#
200# Since: 2.5
201#
202# .. qmp-example::
203#
204#     -> { "execute": "blockdev-close-tray",
205#          "arguments": { "id": "ide0-1-0" } }
206#
207#     <- { "timestamp": { "seconds": 1418751345,
208#                         "microseconds": 272147 },
209#          "event": "DEVICE_TRAY_MOVED",
210#          "data": { "device": "ide1-cd0",
211#                    "id": "ide0-1-0",
212#                    "tray-open": false } }
213#
214#     <- { "return": {} }
215##
216{ 'command': 'blockdev-close-tray',
217  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
218            '*id': 'str' } }
219
220##
221# @blockdev-remove-medium:
222#
223# Removes a medium (a block driver state tree) from a block device.
224# That block device's tray must currently be open (unless there is no
225# attached guest device).
226#
227# If the tray is open and there is no medium inserted, this will be a
228# no-op.
229#
230# @id: The name or QOM path of the guest device
231#
232# Since: 2.12
233#
234# .. qmp-example::
235#
236#     -> { "execute": "blockdev-remove-medium",
237#          "arguments": { "id": "ide0-1-0" } }
238#
239#     <- { "error": { "class": "GenericError",
240#                     "desc": "Tray of device 'ide0-1-0' is not open" } }
241#
242#     -> { "execute": "blockdev-open-tray",
243#          "arguments": { "id": "ide0-1-0" } }
244#
245#     <- { "timestamp": { "seconds": 1418751627,
246#                         "microseconds": 549958 },
247#          "event": "DEVICE_TRAY_MOVED",
248#          "data": { "device": "ide1-cd0",
249#                    "id": "ide0-1-0",
250#                    "tray-open": true } }
251#
252#     <- { "return": {} }
253#
254#     -> { "execute": "blockdev-remove-medium",
255#          "arguments": { "id": "ide0-1-0" } }
256#
257#     <- { "return": {} }
258##
259{ 'command': 'blockdev-remove-medium',
260  'data': { 'id': 'str' } }
261
262##
263# @blockdev-insert-medium:
264#
265# Inserts a medium (a block driver state tree) into a block device.
266# That block device's tray must currently be open (unless there is no
267# attached guest device) and there must be no medium inserted already.
268#
269# @id: The name or QOM path of the guest device
270#
271# @node-name: name of a node in the block driver state graph
272#
273# Since: 2.12
274#
275# .. qmp-example::
276#
277#     -> { "execute": "blockdev-add",
278#          "arguments": {
279#              "node-name": "node0",
280#              "driver": "raw",
281#              "file": { "driver": "file",
282#                        "filename": "fedora.iso" } } }
283#     <- { "return": {} }
284#
285#     -> { "execute": "blockdev-insert-medium",
286#          "arguments": { "id": "ide0-1-0",
287#                         "node-name": "node0" } }
288#
289#     <- { "return": {} }
290##
291{ 'command': 'blockdev-insert-medium',
292  'data': { 'id': 'str',
293            'node-name': 'str'} }
294
295##
296# @BlockdevChangeReadOnlyMode:
297#
298# Specifies the new read-only mode of a block device subject to the
299# @blockdev-change-medium command.
300#
301# @retain: Retains the current read-only mode
302#
303# @read-only: Makes the device read-only
304#
305# @read-write: Makes the device writable
306#
307# Since: 2.3
308##
309{ 'enum': 'BlockdevChangeReadOnlyMode',
310  'data': ['retain', 'read-only', 'read-write'] }
311
312##
313# @blockdev-change-medium:
314#
315# Changes the medium inserted into a block device by ejecting the
316# current medium and loading a new image file which is inserted as the
317# new medium (this command combines blockdev-open-tray,
318# blockdev-remove-medium, blockdev-insert-medium and
319# blockdev-close-tray).
320#
321# @device: Block device name
322#
323# @id: The name or QOM path of the guest device (since: 2.8)
324#
325# @filename: filename of the new image to be loaded
326#
327# @format: format to open the new image with (defaults to the probed
328#     format)
329#
330# @read-only-mode: change the read-only mode of the device; defaults
331#     to 'retain'
332#
333# @force: if false (the default), an eject request through
334#     blockdev-open-tray will be sent to the guest if it has locked
335#     the tray (and the tray will not be opened immediately); if true,
336#     the tray will be opened regardless of whether it is locked.
337#     (since 7.1)
338#
339# Features:
340#
341# @deprecated: Member @device is deprecated.  Use @id instead.
342#
343# Since: 2.5
344#
345# .. qmp-example::
346#    :title: Change a removable medium
347#
348#     -> { "execute": "blockdev-change-medium",
349#          "arguments": { "id": "ide0-1-0",
350#                         "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
351#                         "format": "raw" } }
352#     <- { "return": {} }
353#
354# .. qmp-example::
355#    :title: Load a read-only medium into a writable drive
356#
357#     -> { "execute": "blockdev-change-medium",
358#          "arguments": { "id": "floppyA",
359#                         "filename": "/srv/images/ro.img",
360#                         "format": "raw",
361#                         "read-only-mode": "retain" } }
362#
363#     <- { "error":
364#          { "class": "GenericError",
365#            "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
366#
367#     -> { "execute": "blockdev-change-medium",
368#          "arguments": { "id": "floppyA",
369#                         "filename": "/srv/images/ro.img",
370#                         "format": "raw",
371#                         "read-only-mode": "read-only" } }
372#
373#     <- { "return": {} }
374##
375{ 'command': 'blockdev-change-medium',
376  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
377            '*id': 'str',
378            'filename': 'str',
379            '*format': 'str',
380            '*force': 'bool',
381            '*read-only-mode': 'BlockdevChangeReadOnlyMode' } }
382
383##
384# @DEVICE_TRAY_MOVED:
385#
386# Emitted whenever the tray of a removable device is moved by the
387# guest or by HMP/QMP commands
388#
389# @device: Block device name.  This is always present for
390#     compatibility reasons, but it can be empty ("") if the image
391#     does not have a device name associated.
392#
393# @id: The name or QOM path of the guest device (since 2.8)
394#
395# @tray-open: true if the tray has been opened or false if it has been
396#     closed
397#
398# Since: 1.1
399#
400# .. qmp-example::
401#
402#     <- { "event": "DEVICE_TRAY_MOVED",
403#          "data": { "device": "ide1-cd0",
404#                    "id": "/machine/unattached/device[22]",
405#                    "tray-open": true
406#          },
407#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
408##
409{ 'event': 'DEVICE_TRAY_MOVED',
410  'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } }
411
412##
413# @PR_MANAGER_STATUS_CHANGED:
414#
415# Emitted whenever the connected status of a persistent reservation
416# manager changes.
417#
418# @id: The id of the PR manager object
419#
420# @connected: true if the PR manager is connected to a backend
421#
422# Since: 3.0
423#
424# .. qmp-example::
425#
426#     <- { "event": "PR_MANAGER_STATUS_CHANGED",
427#          "data": { "id": "pr-helper0",
428#                    "connected": true
429#          },
430#          "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
431##
432{ 'event': 'PR_MANAGER_STATUS_CHANGED',
433  'data': { 'id': 'str', 'connected': 'bool' } }
434
435##
436# @block_set_io_throttle:
437#
438# Change I/O throttle limits for a block drive.
439#
440# Since QEMU 2.4, each device with I/O limits is member of a throttle
441# group.
442#
443# If two or more devices are members of the same group, the limits
444# will apply to the combined I/O of the whole group in a round-robin
445# fashion.  Therefore, setting new I/O limits to a device will affect
446# the whole group.
447#
448# The name of the group can be specified using the 'group' parameter.
449# If the parameter is unset, it is assumed to be the current group of
450# that device.  If it's not in any group yet, the name of the device
451# will be used as the name for its group.
452#
453# The 'group' parameter can also be used to move a device to a
454# different group.  In this case the limits specified in the
455# parameters will be applied to the new group only.
456#
457# I/O limits can be disabled by setting all of them to 0.  In this
458# case the device will be removed from its group and the rest of its
459# members will not be affected.  The 'group' parameter is ignored.
460#
461# Errors:
462#     - If @device is not a valid block device, DeviceNotFound
463#
464# Since: 1.1
465#
466# .. qmp-example::
467#
468#     -> { "execute": "block_set_io_throttle",
469#          "arguments": { "id": "virtio-blk-pci0/virtio-backend",
470#                         "bps": 0,
471#                         "bps_rd": 0,
472#                         "bps_wr": 0,
473#                         "iops": 512,
474#                         "iops_rd": 0,
475#                         "iops_wr": 0,
476#                         "bps_max": 0,
477#                         "bps_rd_max": 0,
478#                         "bps_wr_max": 0,
479#                         "iops_max": 0,
480#                         "iops_rd_max": 0,
481#                         "iops_wr_max": 0,
482#                         "bps_max_length": 0,
483#                         "iops_size": 0 } }
484#     <- { "return": {} }
485#
486# .. qmp-example::
487#
488#     -> { "execute": "block_set_io_throttle",
489#          "arguments": { "id": "ide0-1-0",
490#                         "bps": 1000000,
491#                         "bps_rd": 0,
492#                         "bps_wr": 0,
493#                         "iops": 0,
494#                         "iops_rd": 0,
495#                         "iops_wr": 0,
496#                         "bps_max": 8000000,
497#                         "bps_rd_max": 0,
498#                         "bps_wr_max": 0,
499#                         "iops_max": 0,
500#                         "iops_rd_max": 0,
501#                         "iops_wr_max": 0,
502#                         "bps_max_length": 60,
503#                         "iops_size": 0 } }
504#     <- { "return": {} }
505##
506{ 'command': 'block_set_io_throttle', 'boxed': true,
507  'data': 'BlockIOThrottle',
508  'allow-preconfig': true }
509
510##
511# @block-latency-histogram-set:
512#
513# Manage read, write and flush latency histograms for the device.
514#
515# If only @id parameter is specified, remove all present latency
516# histograms for the device.  Otherwise, add/reset some of (or all)
517# latency histograms.
518#
519# @id: The name or QOM path of the guest device.
520#
521# @boundaries: list of interval boundary values (see description in
522#     BlockLatencyHistogramInfo definition).  If specified, all
523#     latency histograms are removed, and empty ones created for all
524#     io types with intervals corresponding to @boundaries (except for
525#     io types, for which specific boundaries are set through the
526#     following parameters).
527#
528# @boundaries-read: list of interval boundary values for read latency
529#     histogram.  If specified, old read latency histogram is removed,
530#     and empty one created with intervals corresponding to
531#     @boundaries-read.  The parameter has higher priority then
532#     @boundaries.
533#
534# @boundaries-write: list of interval boundary values for write
535#     latency histogram.
536#
537# @boundaries-zap: list of interval boundary values for zone append
538#     write latency histogram.
539#
540# @boundaries-flush: list of interval boundary values for flush
541#     latency histogram.
542#
543# Errors:
544#     - if device is not found or any boundary arrays are invalid.
545#
546# Since: 4.0
547#
548# .. qmp-example::
549#    :annotated:
550#
551#    Set new histograms for all io types with intervals
552#    [0, 10), [10, 50), [50, 100), [100, +inf)::
553#
554#     -> { "execute": "block-latency-histogram-set",
555#          "arguments": { "id": "drive0",
556#                         "boundaries": [10, 50, 100] } }
557#     <- { "return": {} }
558#
559# .. qmp-example::
560#    :annotated:
561#
562#    Set new histogram only for write, other histograms will remain
563#    not changed (or not created)::
564#
565#     -> { "execute": "block-latency-histogram-set",
566#          "arguments": { "id": "drive0",
567#                         "boundaries-write": [10, 50, 100] } }
568#     <- { "return": {} }
569#
570# .. qmp-example::
571#    :annotated:
572#
573#    Set new histograms with the following intervals:
574#
575#    - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
576#    - write: [0, 1000), [1000, 5000), [5000, +inf)
577#
578#    ::
579#
580#     -> { "execute": "block-latency-histogram-set",
581#          "arguments": { "id": "drive0",
582#                         "boundaries": [10, 50, 100],
583#                         "boundaries-write": [1000, 5000] } }
584#     <- { "return": {} }
585#
586# .. qmp-example::
587#    :annotated:
588#
589#    Remove all latency histograms::
590#
591#     -> { "execute": "block-latency-histogram-set",
592#          "arguments": { "id": "drive0" } }
593#     <- { "return": {} }
594##
595{ 'command': 'block-latency-histogram-set',
596  'data': {'id': 'str',
597           '*boundaries': ['uint64'],
598           '*boundaries-read': ['uint64'],
599           '*boundaries-write': ['uint64'],
600           '*boundaries-zap': ['uint64'],
601           '*boundaries-flush': ['uint64'] },
602  'allow-preconfig': true }
603