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 # Notes: Ejecting a device with no media results in success 117 # 118 # Since: 0.14 119 # 120 # 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 # 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 # 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 # 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 # 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 # Examples: 346 # 347 # 1. Change a removable medium 348 # 349 # -> { "execute": "blockdev-change-medium", 350 # "arguments": { "id": "ide0-1-0", 351 # "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", 352 # "format": "raw" } } 353 # <- { "return": {} } 354 # 355 # 2. 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 # 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 # 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 case 458 # 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 # Examples: 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 # -> { "execute": "block_set_io_throttle", 487 # "arguments": { "id": "ide0-1-0", 488 # "bps": 1000000, 489 # "bps_rd": 0, 490 # "bps_wr": 0, 491 # "iops": 0, 492 # "iops_rd": 0, 493 # "iops_wr": 0, 494 # "bps_max": 8000000, 495 # "bps_rd_max": 0, 496 # "bps_wr_max": 0, 497 # "iops_max": 0, 498 # "iops_rd_max": 0, 499 # "iops_wr_max": 0, 500 # "bps_max_length": 60, 501 # "iops_size": 0 } } 502 # <- { "return": {} } 503 ## 504 { 'command': 'block_set_io_throttle', 'boxed': true, 505 'data': 'BlockIOThrottle', 506 'allow-preconfig': true } 507 508 ## 509 # @block-latency-histogram-set: 510 # 511 # Manage read, write and flush latency histograms for the device. 512 # 513 # If only @id parameter is specified, remove all present latency 514 # histograms for the device. Otherwise, add/reset some of (or all) 515 # latency histograms. 516 # 517 # @id: The name or QOM path of the guest device. 518 # 519 # @boundaries: list of interval boundary values (see description in 520 # BlockLatencyHistogramInfo definition). If specified, all latency 521 # histograms are removed, and empty ones created for all io types 522 # with intervals corresponding to @boundaries (except for io 523 # types, for which specific boundaries are set through the 524 # following parameters). 525 # 526 # @boundaries-read: list of interval boundary values for read latency 527 # histogram. If specified, old read latency histogram is removed, 528 # and empty one created with intervals corresponding to 529 # @boundaries-read. The parameter has higher priority then 530 # @boundaries. 531 # 532 # @boundaries-write: list of interval boundary values for write 533 # latency histogram. 534 # 535 # @boundaries-zap: list of interval boundary values for zone append 536 # write latency histogram. 537 # 538 # @boundaries-flush: list of interval boundary values for flush 539 # latency histogram. 540 # 541 # Errors: 542 # - if device is not found or any boundary arrays are invalid. 543 # 544 # Since: 4.0 545 # 546 # Example: 547 # 548 # Set new histograms for all io types with intervals [0, 10), [10, 549 # 50), [50, 100), [100, +inf): 550 # 551 # -> { "execute": "block-latency-histogram-set", 552 # "arguments": { "id": "drive0", 553 # "boundaries": [10, 50, 100] } } 554 # <- { "return": {} } 555 # 556 # Example: 557 # 558 # Set new histogram only for write, other histograms will remain not 559 # changed (or not created): 560 # 561 # -> { "execute": "block-latency-histogram-set", 562 # "arguments": { "id": "drive0", 563 # "boundaries-write": [10, 50, 100] } } 564 # <- { "return": {} } 565 # 566 # Example: 567 # 568 # Set new histograms with the following intervals: read, flush: [0, 569 # 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000, 570 # 5000), [5000, +inf) 571 # 572 # -> { "execute": "block-latency-histogram-set", 573 # "arguments": { "id": "drive0", 574 # "boundaries": [10, 50, 100], 575 # "boundaries-write": [1000, 5000] } } 576 # <- { "return": {} } 577 # 578 # Example: 579 # 580 # Remove all latency histograms: 581 # 582 # -> { "execute": "block-latency-histogram-set", 583 # "arguments": { "id": "drive0" } } 584 # <- { "return": {} } 585 ## 586 { 'command': 'block-latency-histogram-set', 587 'data': {'id': 'str', 588 '*boundaries': ['uint64'], 589 '*boundaries-read': ['uint64'], 590 '*boundaries-write': ['uint64'], 591 '*boundaries-zap': ['uint64'], 592 '*boundaries-flush': ['uint64'] }, 593 'allow-preconfig': true } 594