Import QEMU upstream snapshot d2e570c
Upstream: https://gitlab.com/qemu-project/qemu.git Upstream-Commit: d2e570cc0f97b936902a5b1b86b73c0f5998b475
This commit is contained in:
Yaya48 committed
commit
cf256aa081
11315 files changed
+3598369
No files matched your search
@@ -0,0 +1,426 @@
|
||||
Barrier client protocol
|
||||
=======================
|
||||
|
||||
QEMU's ``input-barrier`` device implements the client end of
|
||||
the KVM (Keyboard-Video-Mouse) software
|
||||
`Barrier <https://github.com/debauchee/barrier>`__.
|
||||
|
||||
This document briefly describes the protocol as we implement it.
|
||||
|
||||
Message format
|
||||
--------------
|
||||
|
||||
Message format between the server and client is in two parts:
|
||||
|
||||
#. the payload length, a 32bit integer in network endianness
|
||||
#. the payload
|
||||
|
||||
The payload starts with a 4byte string (without NUL) which is the
|
||||
command. The first command between the server and the client
|
||||
is the only command not encoded on 4 bytes ("Barrier").
|
||||
The remaining part of the payload is decoded according to the command.
|
||||
|
||||
Protocol Description
|
||||
--------------------
|
||||
|
||||
This comes from ``barrier/src/lib/barrier/protocol_types.h``.
|
||||
|
||||
barrierCmdHello "Barrier"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t minor, int16_t major }``
|
||||
Description:
|
||||
Say hello to client
|
||||
|
||||
``minor`` = protocol major version number supported by server
|
||||
|
||||
``major`` = protocol minor version number supported by server
|
||||
|
||||
barrierCmdHelloBack "Barrier"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
client ->server
|
||||
Parameters:
|
||||
``{ int16_t minor, int16_t major, char *name}``
|
||||
Description:
|
||||
Respond to hello from server
|
||||
|
||||
``minor`` = protocol major version number supported by client
|
||||
|
||||
``major`` = protocol minor version number supported by client
|
||||
|
||||
``name`` = client name
|
||||
|
||||
barrierCmdDInfo "DINF"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
client ->server
|
||||
Parameters:
|
||||
``{ int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}``
|
||||
Description:
|
||||
The client screen must send this message in response to the
|
||||
barrierCmdQInfo message. It must also send this message when the
|
||||
screen's resolution changes. In this case, the client screen should
|
||||
ignore any barrierCmdDMouseMove messages until it receives a
|
||||
barrierCmdCInfoAck in order to prevent attempts to move the mouse off
|
||||
the new screen area.
|
||||
|
||||
barrierCmdCNoop "CNOP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
client -> server
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
No operation
|
||||
|
||||
barrierCmdCClose "CBYE"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Close connection
|
||||
|
||||
barrierCmdCEnter "CINN"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t x, int16_t y, int32_t seq, int16_t modifier }``
|
||||
Description:
|
||||
Enter screen.
|
||||
|
||||
``x``, ``y`` = entering screen absolute coordinates
|
||||
|
||||
``seq`` = sequence number, which is used to order messages between
|
||||
screens. the secondary screen must return this number
|
||||
with some messages
|
||||
|
||||
``modifier`` = modifier key mask. this will have bits set for each
|
||||
toggle modifier key that is activated on entry to the
|
||||
screen. the secondary screen should adjust its toggle
|
||||
modifiers to reflect that state.
|
||||
|
||||
barrierCmdCLeave "COUT"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Leaving screen. the secondary screen should send clipboard data in
|
||||
response to this message for those clipboards that it has grabbed
|
||||
(i.e. has sent a barrierCmdCClipboard for and has not received a
|
||||
barrierCmdCClipboard for with a greater sequence number) and that
|
||||
were grabbed or have changed since the last leave.
|
||||
|
||||
barrierCmdCClipboard "CCLP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t id, int32_t seq }``
|
||||
Description:
|
||||
Grab clipboard. Sent by screen when some other app on that screen
|
||||
grabs a clipboard.
|
||||
|
||||
``id`` = the clipboard identifier
|
||||
|
||||
``seq`` = sequence number. Client must use the sequence number passed in
|
||||
the most recent barrierCmdCEnter. the server always sends 0.
|
||||
|
||||
barrierCmdCScreenSaver "CSEC"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t started }``
|
||||
Description:
|
||||
Screensaver change.
|
||||
|
||||
``started`` = Screensaver on primary has started (1) or closed (0)
|
||||
|
||||
barrierCmdCResetOptions "CROP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Reset options. Client should reset all of its options to their
|
||||
defaults.
|
||||
|
||||
barrierCmdCInfoAck "CIAK"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Resolution change acknowledgment. Sent by server in response to a
|
||||
client screen's barrierCmdDInfo. This is sent for every
|
||||
barrierCmdDInfo, whether or not the server had sent a barrierCmdQInfo.
|
||||
|
||||
barrierCmdCKeepAlive "CALV"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Keep connection alive. Sent by the server periodically to verify
|
||||
that connections are still up and running. clients must reply in
|
||||
kind on receipt. if the server gets an error sending the message or
|
||||
does not receive a reply within a reasonable time then the server
|
||||
disconnects the client. if the client doesn't receive these (or any
|
||||
message) periodically then it should disconnect from the server. the
|
||||
appropriate interval is defined by an option.
|
||||
|
||||
barrierCmdDKeyDown "DKDN"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t keyid, int16_t modifier [,int16_t button] }``
|
||||
Description:
|
||||
Key pressed.
|
||||
|
||||
``keyid`` = X11 key id
|
||||
|
||||
``modified`` = modified mask
|
||||
|
||||
``button`` = X11 Xkb keycode (optional)
|
||||
|
||||
barrierCmdDKeyRepeat "DKRP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }``
|
||||
Description:
|
||||
Key auto-repeat.
|
||||
|
||||
``keyid`` = X11 key id
|
||||
|
||||
``modified`` = modified mask
|
||||
|
||||
``repeat`` = number of repeats
|
||||
|
||||
``button`` = X11 Xkb keycode (optional)
|
||||
|
||||
barrierCmdDKeyUp "DKUP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t keyid, int16_t modifier [,int16_t button] }``
|
||||
Description:
|
||||
Key released.
|
||||
|
||||
``keyid`` = X11 key id
|
||||
|
||||
``modified`` = modified mask
|
||||
|
||||
``button`` = X11 Xkb keycode (optional)
|
||||
|
||||
barrierCmdDMouseDown "DMDN"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t button }``
|
||||
Description:
|
||||
Mouse button pressed.
|
||||
|
||||
``button`` = button id
|
||||
|
||||
barrierCmdDMouseUp "DMUP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t button }``
|
||||
Description:
|
||||
Mouse button release.
|
||||
|
||||
``button`` = button id
|
||||
|
||||
barrierCmdDMouseMove "DMMV"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t x, int16_t y }``
|
||||
Description:
|
||||
Absolute mouse moved.
|
||||
|
||||
``x``, ``y`` = absolute screen coordinates
|
||||
|
||||
barrierCmdDMouseRelMove "DMRM"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t x, int16_t y }``
|
||||
Description:
|
||||
Relative mouse moved.
|
||||
|
||||
``x``, ``y`` = r relative screen coordinates
|
||||
|
||||
barrierCmdDMouseWheel "DMWM"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t x , int16_t y }`` or ``{ int16_t y }``
|
||||
Description:
|
||||
Mouse scroll. The delta should be +120 for one tick forward (away
|
||||
from the user) or right and -120 for one tick backward (toward the
|
||||
user) or left.
|
||||
|
||||
``x`` = x delta
|
||||
|
||||
``y`` = y delta
|
||||
|
||||
barrierCmdDClipboard "DCLP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t id, int32_t seq, int8_t mark, char *data }``
|
||||
Description:
|
||||
Clipboard data.
|
||||
|
||||
``id`` = clipboard id
|
||||
|
||||
``seq`` = sequence number. The sequence number is 0 when sent by the
|
||||
server. Client screens should use the/ sequence number from
|
||||
the most recent barrierCmdCEnter.
|
||||
|
||||
barrierCmdDSetOptions "DSOP"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int32 t nb, { int32_t id, int32_t val }[] }``
|
||||
Description:
|
||||
Set options. Client should set the given option/value pairs.
|
||||
|
||||
``nb`` = numbers of ``{ id, val }`` entries
|
||||
|
||||
``id`` = option id
|
||||
|
||||
``val`` = option new value
|
||||
|
||||
barrierCmdDFileTransfer "DFTR"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int8_t mark, char *content }``
|
||||
Description:
|
||||
Transfer file data.
|
||||
|
||||
* ``mark`` = 0 means the content followed is the file size
|
||||
* 1 means the content followed is the chunk data
|
||||
* 2 means the file transfer is finished
|
||||
|
||||
barrierCmdDDragInfo "DDRG"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t nb, char *content }``
|
||||
Description:
|
||||
Drag information.
|
||||
|
||||
``nb`` = number of dragging objects
|
||||
|
||||
``content`` = object's directory
|
||||
|
||||
barrierCmdQInfo "QINF"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Query screen info
|
||||
|
||||
Client should reply with a barrierCmdDInfo
|
||||
|
||||
barrierCmdEIncompatible "EICV"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
``{ int16_t nb, major *minor }``
|
||||
Description:
|
||||
Incompatible version.
|
||||
|
||||
``major`` = major version
|
||||
|
||||
``minor`` = minor version
|
||||
|
||||
barrierCmdEBusy "EBSY"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Name provided when connecting is already in use.
|
||||
|
||||
barrierCmdEUnknown "EUNK"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Unknown client. Name provided when connecting is not in primary's
|
||||
screen configuration map.
|
||||
|
||||
barrierCmdEBad "EBAD"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Direction:
|
||||
server -> client
|
||||
Parameters:
|
||||
None
|
||||
Description:
|
||||
Protocol violation. Server should disconnect after sending this
|
||||
message.
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,33 @@
|
||||
.. _dbus-display:
|
||||
|
||||
D-Bus display
|
||||
=============
|
||||
|
||||
QEMU can export the VM display through D-Bus (when started with ``-display
|
||||
dbus``), to allow out-of-process UIs, remote protocol servers or other
|
||||
interactive display usages.
|
||||
|
||||
Various specialized D-Bus interfaces are available on different object paths
|
||||
under ``/org/qemu/Display1/``, depending on the VM configuration.
|
||||
|
||||
QEMU also implements the standard interfaces, such as
|
||||
`org.freedesktop.DBus.Introspectable
|
||||
<https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces>`_.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
.. only:: sphinx4
|
||||
|
||||
.. dbus-doc:: ui/dbus-display1.xml
|
||||
|
||||
.. only:: not sphinx4
|
||||
|
||||
.. warning::
|
||||
Sphinx 4 is required to build D-Bus documentation.
|
||||
|
||||
This is the content of ``ui/dbus-display1.xml``:
|
||||
|
||||
.. literalinclude:: ../../ui/dbus-display1.xml
|
||||
:language: xml
|
||||
@@ -0,0 +1,38 @@
|
||||
=============
|
||||
D-Bus VMState
|
||||
=============
|
||||
|
||||
The QEMU dbus-vmstate object's aim is to migrate helpers' data running
|
||||
on a QEMU D-Bus bus. (refer to the :doc:`dbus` document for
|
||||
some recommendations on D-Bus usage)
|
||||
|
||||
Upon migration, QEMU will go through the queue of
|
||||
``org.qemu.VMState1`` D-Bus name owners and query their ``Id``. It
|
||||
must be unique among the helpers.
|
||||
|
||||
It will then save arbitrary data of each Id to be transferred in the
|
||||
migration stream and restored/loaded at the corresponding destination
|
||||
helper.
|
||||
|
||||
For now, the data amount to be transferred is arbitrarily limited to
|
||||
1Mb. The state must be saved quickly (a fraction of a second). (D-Bus
|
||||
imposes a time limit on reply anyway, and migration would fail if data
|
||||
isn't given quickly enough.)
|
||||
|
||||
dbus-vmstate object can be configured with the expected list of
|
||||
helpers by setting its ``id-list`` property, with a comma-separated
|
||||
``Id`` list.
|
||||
|
||||
.. only:: sphinx4
|
||||
|
||||
.. dbus-doc:: backends/dbus-vmstate1.xml
|
||||
|
||||
.. only:: not sphinx4
|
||||
|
||||
.. warning::
|
||||
Sphinx 4 is required to build D-Bus documentation.
|
||||
|
||||
This is the content of ``backends/dbus-vmstate1.xml``:
|
||||
|
||||
.. literalinclude:: ../../backends/dbus-vmstate1.xml
|
||||
:language: xml
|
||||
@@ -0,0 +1,26 @@
|
||||
D-Bus VNC
|
||||
=========
|
||||
|
||||
The ``qemu-vnc`` standalone VNC server exposes a D-Bus interface for management
|
||||
and monitoring of VNC connections.
|
||||
|
||||
The service is available on the bus under the well-known name ``org.qemu.vnc``.
|
||||
Objects are exported under ``/org/qemu/Vnc1/``.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
.. only:: sphinx4
|
||||
|
||||
.. dbus-doc:: tools/qemu-vnc/qemu-vnc1.xml
|
||||
|
||||
.. only:: not sphinx4
|
||||
|
||||
.. warning::
|
||||
Sphinx 4 is required to build D-Bus documentation.
|
||||
|
||||
This is the content of ``tools/qemu-vnc/qemu-vnc1.xml``:
|
||||
|
||||
.. literalinclude:: ../../tools/qemu-vnc/qemu-vnc1.xml
|
||||
:language: xml
|
||||
@@ -0,0 +1,112 @@
|
||||
=====
|
||||
D-Bus
|
||||
=====
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
QEMU may be running with various helper processes involved:
|
||||
- vhost-user* processes (gpu, virtfs, input, etc...)
|
||||
- TPM emulation (or other devices)
|
||||
- user networking (slirp)
|
||||
- network services (DHCP/DNS, samba/ftp etc)
|
||||
- background tasks (compression, streaming etc)
|
||||
- client UI
|
||||
- admin & cli
|
||||
|
||||
Having several processes allows stricter security rules, as well as
|
||||
greater modularity.
|
||||
|
||||
While QEMU itself uses QMP as primary IPC (and Spice/VNC for remote
|
||||
display), D-Bus is the de facto IPC of choice on Unix systems. The
|
||||
wire format is machine friendly, good bindings exist for various
|
||||
languages, and there are various tools available.
|
||||
|
||||
Using a bus, helper processes can discover and communicate with each
|
||||
other easily, without going through QEMU. The bus topology is also
|
||||
easier to apprehend and debug than a mesh. However, it is wise to
|
||||
consider the security aspects of it.
|
||||
|
||||
Security
|
||||
========
|
||||
|
||||
A QEMU D-Bus bus should be private to a single VM. Thus, only
|
||||
cooperative tasks are running on the same bus to serve the VM.
|
||||
|
||||
D-Bus, the protocol and standard, doesn't have mechanisms to enforce
|
||||
security between peers once the connection is established. Peers may
|
||||
have additional mechanisms to enforce security rules, based for
|
||||
example on UNIX credentials.
|
||||
|
||||
The daemon can control which peers can send/recv messages using
|
||||
various metadata attributes, however, this is alone is not generally
|
||||
sufficient to make the deployment secure. The semantics of the actual
|
||||
methods implemented using D-Bus are just as critical. Peers need to
|
||||
carefully validate any information they received from a peer with a
|
||||
different trust level.
|
||||
|
||||
dbus-daemon policy
|
||||
------------------
|
||||
|
||||
dbus-daemon can enforce various policies based on the UID/GID of the
|
||||
processes that are connected to it. It is thus a good idea to run
|
||||
helpers as different UID from QEMU and set appropriate policies.
|
||||
|
||||
Depending on the use case, you may choose different scenarios:
|
||||
|
||||
- Everything the same UID
|
||||
|
||||
- Convenient for developers
|
||||
- Improved reliability - crash of one part doesn't take
|
||||
out entire VM
|
||||
- No security benefit over traditional QEMU, unless additional
|
||||
unless additional controls such as SELinux or AppArmor are
|
||||
applied
|
||||
|
||||
- Two UIDs, one for QEMU, one for dbus & helpers
|
||||
|
||||
- Moderately improved user based security isolation
|
||||
|
||||
- Many UIDs, one for QEMU one for dbus and one for each helpers
|
||||
|
||||
- Best user based security isolation
|
||||
- Complex to manager distinct UIDs needed for each VM
|
||||
|
||||
For example, to allow only ``qemu`` user to talk to ``qemu-helper``
|
||||
``org.qemu.Helper1`` service, a dbus-daemon policy may contain:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<policy user="qemu">
|
||||
<allow send_destination="org.qemu.Helper1"/>
|
||||
<allow receive_sender="org.qemu.Helper1"/>
|
||||
</policy>
|
||||
|
||||
<policy user="qemu-helper">
|
||||
<allow own="org.qemu.Helper1"/>
|
||||
</policy>
|
||||
|
||||
|
||||
dbus-daemon can also perform SELinux checks based on the security
|
||||
context of the source and the target. For example, ``virtiofs_t``
|
||||
could be allowed to send a message to ``svirt_t``, but ``virtiofs_t``
|
||||
wouldn't be allowed to send a message to ``virtiofs_t``.
|
||||
|
||||
See dbus-daemon man page for details.
|
||||
|
||||
Guidelines
|
||||
==========
|
||||
|
||||
When implementing new D-Bus interfaces, it is recommended to follow
|
||||
the "D-Bus API Design Guidelines":
|
||||
https://dbus.freedesktop.org/doc/dbus-api-design.html
|
||||
|
||||
The "org.qemu.*" prefix is reserved for services implemented &
|
||||
distributed by the QEMU project.
|
||||
|
||||
QEMU Interfaces
|
||||
===============
|
||||
|
||||
:doc:`dbus-vmstate`
|
||||
|
||||
:doc:`dbus-display`
|
||||
@@ -0,0 +1,762 @@
|
||||
# -*- Mode: Python -*-
|
||||
# vim: filetype=python
|
||||
#
|
||||
# Copyright (C) 2018 Red Hat, Inc.
|
||||
#
|
||||
# Authors:
|
||||
# Daniel P. Berrange <berrange@redhat.com>
|
||||
# Laszlo Ersek <lersek@redhat.com>
|
||||
#
|
||||
# This work is licensed under the terms of the GNU GPL, version 2 or
|
||||
# later. See the COPYING file in the top-level directory.
|
||||
|
||||
##
|
||||
# ********
|
||||
# Firmware
|
||||
# ********
|
||||
##
|
||||
|
||||
{ 'pragma': {
|
||||
'member-name-exceptions': [
|
||||
'FirmwareArchitecture' # x86_64
|
||||
] } }
|
||||
|
||||
##
|
||||
# @FirmwareOSInterface:
|
||||
#
|
||||
# Lists the firmware-OS interface types provided by various firmware
|
||||
# that is commonly used with QEMU virtual machines.
|
||||
#
|
||||
# @bios: Traditional x86 BIOS interface. For example, firmware built
|
||||
# from the SeaBIOS project usually provides this interface.
|
||||
#
|
||||
# @openfirmware: The interface is defined by the (historical) IEEE
|
||||
# 1275-1994 standard. Examples for firmware projects that provide
|
||||
# this interface are: OpenBIOS and SLOF.
|
||||
#
|
||||
# @uboot: Firmware interface defined by the U-Boot project.
|
||||
#
|
||||
# @uefi: Firmware interface defined by the UEFI specification. For
|
||||
# example, firmware built from the edk2 (EFI Development Kit II)
|
||||
# project usually provides this interface.
|
||||
#
|
||||
# @svsm: AMD SEV-SNP Secure VM Service Module (SVSM) guest protocol.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'enum' : 'FirmwareOSInterface',
|
||||
'data' : [ 'bios', 'openfirmware', 'svsm', 'uboot', 'uefi' ] }
|
||||
|
||||
##
|
||||
# @FirmwareDevice:
|
||||
#
|
||||
# Defines the device types that firmware can be mapped into.
|
||||
#
|
||||
# @flash: The firmware executable and its accompanying NVRAM file are
|
||||
# to be mapped into a pflash chip each.
|
||||
#
|
||||
# @kernel: The firmware is to be loaded like a Linux kernel. This is
|
||||
# similar to @memory but may imply additional processing that is
|
||||
# specific to the target architecture and machine type.
|
||||
#
|
||||
# @memory: The firmware is to be mapped into memory.
|
||||
#
|
||||
# @igvm: The firmware is defined by a file conforming to the IGVM
|
||||
# specification and mapped into memory according to directives
|
||||
# defined in the file. This is similar to @memory but may include
|
||||
# additional processing defined by the IGVM file including initial
|
||||
# CPU state or population of metadata into the guest address
|
||||
# space. Since: 10.1
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'enum' : 'FirmwareDevice',
|
||||
'data' : [ 'flash', 'kernel', 'memory', 'igvm' ] }
|
||||
|
||||
##
|
||||
# @FirmwareArchitecture:
|
||||
#
|
||||
# Enumeration of architectures for which Qemu uses additional firmware
|
||||
# files.
|
||||
#
|
||||
# @aarch64: 64-bit Arm.
|
||||
#
|
||||
# @arm: 32-bit Arm.
|
||||
#
|
||||
# @i386: 32-bit x86.
|
||||
#
|
||||
# @loongarch64: 64-bit LoongArch. (since: 7.1)
|
||||
#
|
||||
# @riscv64: 64-bit RISC-V.
|
||||
#
|
||||
# @x86_64: 64-bit x86.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'enum' : 'FirmwareArchitecture',
|
||||
'data' : [ 'aarch64', 'arm', 'i386', 'loongarch64', 'riscv64', 'x86_64' ] }
|
||||
|
||||
##
|
||||
# @FirmwareTarget:
|
||||
#
|
||||
# Defines the machine types that firmware may execute on.
|
||||
#
|
||||
# @architecture: Determines the emulation target (the QEMU system
|
||||
# emulator) that can execute the firmware.
|
||||
#
|
||||
# @machines: Lists the machine types (known by the emulator that is
|
||||
# specified through @architecture) that can execute the firmware.
|
||||
# Elements of @machines are supposed to be concrete machine types,
|
||||
# not aliases. Glob patterns are understood, which is especially
|
||||
# useful for versioned machine types. (For example, the glob
|
||||
# pattern "pc-i440fx-*" matches "pc-i440fx-2.12".) On the QEMU
|
||||
# command line, "-machine type=..." specifies the requested
|
||||
# machine type (but that option does not accept glob patterns).
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareTarget',
|
||||
'data' : { 'architecture' : 'FirmwareArchitecture',
|
||||
'machines' : [ 'str' ] } }
|
||||
|
||||
##
|
||||
# @FirmwareFeature:
|
||||
#
|
||||
# Defines the features that firmware may support, and the platform
|
||||
# requirements that firmware may present.
|
||||
#
|
||||
# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as
|
||||
# defined in the ACPI specification. On the "pc-i440fx-*" machine
|
||||
# types of the @i386 and @x86_64 emulation targets, S3 can be
|
||||
# enabled with "-global PIIX4_PM.disable_s3=0" and disabled with
|
||||
# "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*" machine
|
||||
# types of the @i386 and @x86_64 emulation targets, S3 can be
|
||||
# enabled with "-global ICH9-LPC.disable_s3=0" and disabled with
|
||||
# "-global ICH9-LPC.disable_s3=1".
|
||||
#
|
||||
# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
|
||||
# defined in the ACPI specification. On the "pc-i440fx-*" machine
|
||||
# types of the @i386 and @x86_64 emulation targets, S4 can be
|
||||
# enabled with "-global PIIX4_PM.disable_s4=0" and disabled with
|
||||
# "-global PIIX4_PM.disable_s4=1". On the "pc-q35-*" machine
|
||||
# types of the @i386 and @x86_64 emulation targets, S4 can be
|
||||
# enabled with "-global ICH9-LPC.disable_s4=0" and disabled with
|
||||
# "-global ICH9-LPC.disable_s4=1".
|
||||
#
|
||||
# @amd-sev: The firmware supports running under AMD Secure Encrypted
|
||||
# Virtualization, as specified in the AMD64 Architecture
|
||||
# Programmer's Manual. QEMU command line options related to this
|
||||
# feature are documented in
|
||||
# "docs/system/i386/amd-memory-encryption.rst".
|
||||
#
|
||||
# @amd-sev-es: The firmware supports running under AMD Secure
|
||||
# Encrypted Virtualization - Encrypted State, as specified in the
|
||||
# AMD64 Architecture Programmer's Manual. QEMU command line
|
||||
# options related to this feature are documented in
|
||||
# "docs/system/i386/amd-memory-encryption.rst".
|
||||
#
|
||||
# @amd-sev-snp: The firmware supports running under AMD Secure
|
||||
# Encrypted Virtualization - Secure Nested Paging, as specified in
|
||||
# the AMD64 Architecture Programmer's Manual. QEMU command line
|
||||
# options related to this feature are documented in
|
||||
# "docs/system/i386/amd-memory-encryption.rst".
|
||||
#
|
||||
# @intel-tdx: The firmware supports running under Intel Trust Domain
|
||||
# Extensions (TDX).
|
||||
#
|
||||
# @enrolled-keys: The variable store (NVRAM) template associated with
|
||||
# the firmware binary has the UEFI Secure Boot operational mode
|
||||
# turned on, with certificates enrolled.
|
||||
#
|
||||
# @requires-smm: The firmware requires the platform to emulate SMM
|
||||
# (System Management Mode), as defined in the AMD64 Architecture
|
||||
# Programmer's Manual, and in the Intel(R)64 and IA-32
|
||||
# Architectures Software Developer's Manual. On the "pc-q35-*"
|
||||
# machine types of the @i386 and @x86_64 emulation targets, SMM
|
||||
# emulation can be enabled with "-machine smm=on". (On the
|
||||
# "pc-q35-*" machine types of the @i386 emulation target,
|
||||
# @requires-smm presents further CPU requirements; one combination
|
||||
# known to work is "-cpu coreduo,nx=off".) If the firmware is
|
||||
# marked as both @secure-boot and @requires-smm, then write
|
||||
# accesses to the pflash chip (NVRAM) that holds the UEFI variable
|
||||
# store must be restricted to code that executes in SMM, using the
|
||||
# additional option "-global
|
||||
# driver=cfi.pflash01,property=secure,value=on". Furthermore, a
|
||||
# large guest-physical address space (comprising guest RAM, memory
|
||||
# hotplug range, and 64-bit PCI MMIO aperture), and/or a high VCPU
|
||||
# count, may present high SMRAM requirements from the firmware.
|
||||
# On the "pc-q35-*" machine types of the @i386 and @x86_64
|
||||
# emulation targets, the SMRAM size may be increased above the
|
||||
# default 16MB with the "-global mch.extended-tseg-mbytes=uint16"
|
||||
# option. As a rule of thumb, the default 16MB size suffices for
|
||||
# 1TB of guest-phys address space and a few tens of VCPUs; for
|
||||
# every further TB of guest-phys address space, add 8MB of SMRAM.
|
||||
# 48MB should suffice for 4TB of guest-phys address space and 2-3
|
||||
# hundred VCPUs.
|
||||
#
|
||||
# @secure-boot: The firmware implements the software interfaces for
|
||||
# UEFI Secure Boot, as defined in the UEFI specification. Note
|
||||
# that without @requires-smm, guest code running with kernel
|
||||
# privileges can undermine the security of Secure Boot.
|
||||
#
|
||||
# @verbose-dynamic: When firmware log capture is enabled, the firmware
|
||||
# logs a large amount of debug messages, which may impact boot
|
||||
# performance. With log capture disabled, there is no boot
|
||||
# performance impact. On the "pc-i440fx-*" and "pc-q35-*" machine
|
||||
# types of the @i386 and @x86_64 emulation targets, firmware log
|
||||
# capture can be enabled with the QEMU command line options
|
||||
# "-chardev file,id=fwdebug,path=LOGFILEPATH -device
|
||||
# isa-debugcon,iobase=0x402,chardev=fwdebug". @verbose-dynamic is
|
||||
# mutually exclusive with @verbose-static.
|
||||
#
|
||||
# @verbose-static: The firmware unconditionally produces a large
|
||||
# amount of debug messages, which may impact boot performance.
|
||||
# This feature may typically be carried by certain UEFI firmware
|
||||
# for the "virt-*" machine types of the @arm and @aarch64
|
||||
# emulation targets, where the debug messages are written to the
|
||||
# first (always present) PL011 UART. @verbose-static is mutually
|
||||
# exclusive with @verbose-dynamic.
|
||||
#
|
||||
# @host-uefi-vars: The firmware expects the host to provide an uefi
|
||||
# variable store. qemu supports that via "uefi-vars-sysbus"
|
||||
# (aarch64, riscv64, loongarch64) or "uefi-vars-x64" (x86_64)
|
||||
# devices. The firmware will not use flash for nvram. When
|
||||
# loading the firmware into flash the 'stateless' setup should be
|
||||
# used. It is recommened to load the firmware into memory though.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'enum' : 'FirmwareFeature',
|
||||
'data' : [ 'acpi-s3', 'acpi-s4',
|
||||
'amd-sev', 'amd-sev-es', 'amd-sev-snp',
|
||||
'intel-tdx',
|
||||
'enrolled-keys', 'requires-smm',
|
||||
'secure-boot', 'host-uefi-vars',
|
||||
'verbose-dynamic', 'verbose-static' ] }
|
||||
|
||||
##
|
||||
# @FirmwareFormat:
|
||||
#
|
||||
# Formats that are supported for firmware images.
|
||||
#
|
||||
# @raw: Raw disk image format.
|
||||
#
|
||||
# @qcow2: The QCOW2 image format.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'enum': 'FirmwareFormat',
|
||||
'data': [ 'raw', 'qcow2' ] }
|
||||
|
||||
##
|
||||
# @FirmwareFlashFile:
|
||||
#
|
||||
# Defines common properties that are necessary for loading a firmware
|
||||
# file into a pflash chip. The corresponding QEMU command line option
|
||||
# is "-drive file=@filename,format=@format". Note however that the
|
||||
# option-argument shown here is incomplete; it is completed under
|
||||
# @FirmwareMappingFlash.
|
||||
#
|
||||
# @filename: Specifies the filename on the host filesystem where the
|
||||
# firmware file can be found.
|
||||
#
|
||||
# @format: Specifies the block format of the file pointed-to by
|
||||
# @filename, such as @raw or @qcow2.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareFlashFile',
|
||||
'data' : { 'filename' : 'str',
|
||||
'format' : 'FirmwareFormat' } }
|
||||
|
||||
|
||||
##
|
||||
# @FirmwareFlashMode:
|
||||
#
|
||||
# Describes how the firmware build handles code versus variable
|
||||
# persistence.
|
||||
#
|
||||
# @split: the executable file contains code while the NVRAM template
|
||||
# provides variable storage. The executable must be configured
|
||||
# read-only and can be shared between multiple guests. The NVRAM
|
||||
# template must be cloned for each new guest and configured
|
||||
# read-write.
|
||||
#
|
||||
# @combined: the executable file contains both code and variable
|
||||
# storage. The executable must be cloned for each new guest and
|
||||
# configured read-write. No NVRAM template will be specified.
|
||||
#
|
||||
# @stateless: the executable file contains code and variable storage
|
||||
# is not persisted. The executable must be configured read-only
|
||||
# and can be shared between multiple guests. No NVRAM template
|
||||
# will be specified.
|
||||
#
|
||||
# Since: 7.0.0
|
||||
##
|
||||
{ 'enum': 'FirmwareFlashMode',
|
||||
'data': [ 'split', 'combined', 'stateless' ] }
|
||||
|
||||
##
|
||||
# @FirmwareMappingFlash:
|
||||
#
|
||||
# Describes loading and mapping properties for the firmware executable
|
||||
# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
|
||||
#
|
||||
# @mode: Describes how the firmware build handles code versus variable
|
||||
# storage. If not present, it must be treated as if it was
|
||||
# configured with value @split. Since: 7.0.0
|
||||
#
|
||||
# @executable: Identifies the firmware executable. The @mode
|
||||
# indicates whether there will be an associated NVRAM template
|
||||
# present. The preferred corresponding QEMU command line options
|
||||
# are
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
|
||||
# -machine pflash0=pflash0
|
||||
#
|
||||
# or equivalent -blockdev instead of -drive. When @mode is
|
||||
# @combined the executable must be cloned before use and
|
||||
# configured with readonly=off. With QEMU versions older than
|
||||
# 4.0, you have to use
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
|
||||
#
|
||||
# @nvram-template: Identifies the NVRAM template compatible with
|
||||
# @executable, when @mode is set to @split, otherwise it should
|
||||
# not be present. Management software instantiates an individual
|
||||
# copy -- a specific NVRAM file -- from @nvram-template.@filename
|
||||
# for each new virtual machine definition created.
|
||||
# @nvram-template.@filename itself is never mapped into virtual
|
||||
# machines, only individual copies of it are. An NVRAM file is
|
||||
# typically used for persistently storing the non-volatile UEFI
|
||||
# variables of a virtual machine definition. The preferred
|
||||
# corresponding QEMU command line options are
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
|
||||
# -machine pflash1=pflash1
|
||||
#
|
||||
# or equivalent -blockdev instead of -drive. With QEMU versions
|
||||
# older than 4.0, you have to use
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareMappingFlash',
|
||||
'data' : { '*mode': 'FirmwareFlashMode',
|
||||
'executable' : 'FirmwareFlashFile',
|
||||
'*nvram-template' : 'FirmwareFlashFile' } }
|
||||
|
||||
##
|
||||
# @FirmwareMappingKernel:
|
||||
#
|
||||
# Describes loading and mapping properties for the firmware
|
||||
# executable, when @FirmwareDevice is @kernel.
|
||||
#
|
||||
# @filename: Identifies the firmware executable. The firmware
|
||||
# executable may be shared by multiple virtual machine
|
||||
# definitions. The corresponding QEMU command line option is
|
||||
# "-kernel @filename".
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareMappingKernel',
|
||||
'data' : { 'filename' : 'str' } }
|
||||
|
||||
##
|
||||
# @FirmwareMemoryUefiVars:
|
||||
#
|
||||
# Contains information needed to set up the "uefi-vars" device
|
||||
# to provide UEFI variable store access to the firmware.
|
||||
#
|
||||
# @template: The path to the UEFI JSON variable store template
|
||||
# compatible with the firmware. Management software instantiates
|
||||
# an individual copy -- a specific UEFI variable store file --
|
||||
# from @template for each new virtual machine definition created.
|
||||
# @template itself is never mapped into virtual machines, only
|
||||
# individual copies of it are. The file created by copying
|
||||
# @template is used for persistently storing the non-volatile
|
||||
# UEFI variables of a virtual machine definition. The
|
||||
# corresponding QEMU command line options are
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -device uefi-vars-x64,jsonfile=PATH_TO_PRIVATE_FILE
|
||||
#
|
||||
# for x86_64 virtual machines, or
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# -device uefi-vars-sysbus,jsonfile=PATH_TO_PRIVATE_FILE
|
||||
#
|
||||
# for other UEFI architectures (aarch64, riscv64, loongarch64).
|
||||
#
|
||||
# Since: 11.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareMemoryUefiVars',
|
||||
'data' : { 'template' : 'str' }}
|
||||
|
||||
##
|
||||
# @FirmwareMappingMemory:
|
||||
#
|
||||
# Describes loading and mapping properties for the firmware
|
||||
# executable, when @FirmwareDevice is @memory.
|
||||
#
|
||||
# @filename: Identifies the firmware executable. The firmware
|
||||
# executable may be shared by multiple virtual machine
|
||||
# definitions. The corresponding QEMU command line option is
|
||||
# "-bios @filename".
|
||||
#
|
||||
# @uefi-vars: Information specific to firmware builds that expect the
|
||||
# "uefi-vars" device to be used to provide access to the UEFI
|
||||
# variable store. If the mapping contains this member, the
|
||||
# firmware descriptor must advertise both the @uefi interface
|
||||
# from @FirmwareOSInterface and the @host-uefi-vars feature from
|
||||
# @FirmwareFeature. (Since 11.0)
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'struct' : 'FirmwareMappingMemory',
|
||||
'data' : { 'filename' : 'str',
|
||||
'*uefi-vars' : 'FirmwareMemoryUefiVars' } }
|
||||
|
||||
##
|
||||
# @FirmwareMappingIgvm:
|
||||
#
|
||||
# Describes loading and mapping properties for the firmware
|
||||
# executable, when @FirmwareDevice is @igvm.
|
||||
#
|
||||
# @filename: Identifies the IGVM file containing the firmware
|
||||
# executable along with other information used to configure the
|
||||
# initial state of the guest. The IGVM file may be shared by
|
||||
# multiple virtual machine definitions. This corresponds to
|
||||
# creating an object on the command line with "-object igvm-cfg,
|
||||
# file=@filename".
|
||||
#
|
||||
# Since: 10.1
|
||||
##
|
||||
{ 'struct' : 'FirmwareMappingIgvm',
|
||||
'data' : { 'filename' : 'str' } }
|
||||
|
||||
##
|
||||
# @FirmwareMapping:
|
||||
#
|
||||
# Provides a discriminated structure for firmware to describe its
|
||||
# loading / mapping properties.
|
||||
#
|
||||
# @device: Selects the device type that the firmware must be mapped
|
||||
# into.
|
||||
#
|
||||
# Since: 3.0
|
||||
##
|
||||
{ 'union' : 'FirmwareMapping',
|
||||
'base' : { 'device' : 'FirmwareDevice' },
|
||||
'discriminator' : 'device',
|
||||
'data' : { 'flash' : 'FirmwareMappingFlash',
|
||||
'kernel' : 'FirmwareMappingKernel',
|
||||
'memory' : 'FirmwareMappingMemory',
|
||||
'igvm' : 'FirmwareMappingIgvm' } }
|
||||
|
||||
##
|
||||
# @Firmware:
|
||||
#
|
||||
# Describes a firmware (or a firmware use case) to management
|
||||
# software.
|
||||
#
|
||||
# It is possible for multiple @Firmware elements to match the search
|
||||
# criteria of management software. Applications thus need rules to
|
||||
# pick one of the many matches, and users need the ability to override
|
||||
# distro defaults.
|
||||
#
|
||||
# It is recommended to create firmware JSON files (each containing a
|
||||
# single @Firmware root element) with a double-digit prefix, for
|
||||
# example "50-ovmf.json", "50-seabios-256k.json", etc, so they can be
|
||||
# sorted in predictable order. The firmware JSON files should be
|
||||
# searched for in three directories:
|
||||
#
|
||||
# - /usr/share/qemu/firmware -- populated by distro-provided firmware
|
||||
# packages (XDG_DATA_DIRS covers
|
||||
# /usr/share by default),
|
||||
#
|
||||
# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
|
||||
#
|
||||
# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
|
||||
# additions (XDG_CONFIG_HOME
|
||||
# defaults to $HOME/.config).
|
||||
#
|
||||
# Top-down, the list of directories goes from general to specific.
|
||||
#
|
||||
# Management software should build a list of files from all three
|
||||
# locations, then sort the list by filename (i.e., last pathname
|
||||
# component). Management software should choose the first JSON file
|
||||
# on the sorted list that matches the search criteria. If a more
|
||||
# specific directory has a file with same name as a less specific
|
||||
# directory, then the file in the more specific directory takes
|
||||
# effect. If the more specific file is zero length, it hides the less
|
||||
# specific one.
|
||||
#
|
||||
# For example, if a distro ships
|
||||
#
|
||||
# - /usr/share/qemu/firmware/50-ovmf.json
|
||||
#
|
||||
# - /usr/share/qemu/firmware/50-seabios-256k.json
|
||||
#
|
||||
# then the sysadmin can prevent the default OVMF being used at all
|
||||
# with
|
||||
#
|
||||
# $ touch /etc/qemu/firmware/50-ovmf.json
|
||||
#
|
||||
# The sysadmin can replace/alter the distro default OVMF with
|
||||
#
|
||||
# $ vim /etc/qemu/firmware/50-ovmf.json
|
||||
#
|
||||
# or they can provide a parallel OVMF with higher priority
|
||||
#
|
||||
# $ vim /etc/qemu/firmware/10-ovmf.json
|
||||
#
|
||||
# or they can provide a parallel OVMF with lower priority
|
||||
#
|
||||
# $ vim /etc/qemu/firmware/99-ovmf.json
|
||||
#
|
||||
# @description: Provides a human-readable description of the firmware.
|
||||
# Management software may or may not display @description.
|
||||
#
|
||||
# @interface-types: Lists the types of interfaces that the firmware
|
||||
# can expose to the guest OS. This is a non-empty, ordered list;
|
||||
# entries near the beginning of @interface-types are considered
|
||||
# more native to the firmware, and/or to have a higher quality
|
||||
# implementation in the firmware, than entries near the end of
|
||||
# @interface-types.
|
||||
#
|
||||
# @mapping: Describes the loading / mapping properties of the
|
||||
# firmware.
|
||||
#
|
||||
# @targets: Collects the target architectures (QEMU system emulators)
|
||||
# and their machine types that may execute the firmware.
|
||||
#
|
||||
# @features: Lists the features that the firmware supports, and the
|
||||
# platform requirements it presents.
|
||||
#
|
||||
# @tags: A list of auxiliary strings associated with the firmware for
|
||||
# which @description is not appropriate, due to the latter's
|
||||
# possible exposure to the end-user. @tags serves development and
|
||||
# debugging purposes only, and management software shall
|
||||
# explicitly ignore it.
|
||||
#
|
||||
# Since: 3.0
|
||||
#
|
||||
# .. qmp-example::
|
||||
#
|
||||
# {
|
||||
# "description": "SeaBIOS",
|
||||
# "interface-types": [
|
||||
# "bios"
|
||||
# ],
|
||||
# "mapping": {
|
||||
# "device": "memory",
|
||||
# "filename": "/usr/share/seabios/bios-256k.bin"
|
||||
# },
|
||||
# "targets": [
|
||||
# {
|
||||
# "architecture": "i386",
|
||||
# "machines": [
|
||||
# "pc-i440fx-*",
|
||||
# "pc-q35-*"
|
||||
# ]
|
||||
# },
|
||||
# {
|
||||
# "architecture": "x86_64",
|
||||
# "machines": [
|
||||
# "pc-i440fx-*",
|
||||
# "pc-q35-*"
|
||||
# ]
|
||||
# }
|
||||
# ],
|
||||
# "features": [
|
||||
# "acpi-s3",
|
||||
# "acpi-s4"
|
||||
# ],
|
||||
# "tags": [
|
||||
# "CONFIG_BOOTSPLASH=n",
|
||||
# "CONFIG_ROM_SIZE=256",
|
||||
# "CONFIG_USE_SMM=n"
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
# {
|
||||
# "description": "OVMF with SB+SMM, empty varstore",
|
||||
# "interface-types": [
|
||||
# "uefi"
|
||||
# ],
|
||||
# "mapping": {
|
||||
# "device": "flash",
|
||||
# "executable": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
|
||||
# "format": "raw"
|
||||
# },
|
||||
# "nvram-template": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_VARS.fd",
|
||||
# "format": "raw"
|
||||
# }
|
||||
# },
|
||||
# "targets": [
|
||||
# {
|
||||
# "architecture": "x86_64",
|
||||
# "machines": [
|
||||
# "pc-q35-*"
|
||||
# ]
|
||||
# }
|
||||
# ],
|
||||
# "features": [
|
||||
# "acpi-s3",
|
||||
# "amd-sev",
|
||||
# "requires-smm",
|
||||
# "secure-boot",
|
||||
# "verbose-dynamic"
|
||||
# ],
|
||||
# "tags": [
|
||||
# "-a IA32",
|
||||
# "-a X64",
|
||||
# "-p OvmfPkg/OvmfPkgIa32X64.dsc",
|
||||
# "-t GCC48",
|
||||
# "-b DEBUG",
|
||||
# "-D SMM_REQUIRE",
|
||||
# "-D SECURE_BOOT_ENABLE",
|
||||
# "-D FD_SIZE_4MB"
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
# {
|
||||
# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
|
||||
# "interface-types": [
|
||||
# "uefi"
|
||||
# ],
|
||||
# "mapping": {
|
||||
# "device": "flash",
|
||||
# "executable": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
|
||||
# "format": "raw"
|
||||
# },
|
||||
# "nvram-template": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
|
||||
# "format": "raw"
|
||||
# }
|
||||
# },
|
||||
# "targets": [
|
||||
# {
|
||||
# "architecture": "x86_64",
|
||||
# "machines": [
|
||||
# "pc-q35-*"
|
||||
# ]
|
||||
# }
|
||||
# ],
|
||||
# "features": [
|
||||
# "acpi-s3",
|
||||
# "amd-sev",
|
||||
# "enrolled-keys",
|
||||
# "requires-smm",
|
||||
# "secure-boot",
|
||||
# "verbose-dynamic"
|
||||
# ],
|
||||
# "tags": [
|
||||
# "-a IA32",
|
||||
# "-a X64",
|
||||
# "-p OvmfPkg/OvmfPkgIa32X64.dsc",
|
||||
# "-t GCC48",
|
||||
# "-b DEBUG",
|
||||
# "-D SMM_REQUIRE",
|
||||
# "-D SECURE_BOOT_ENABLE",
|
||||
# "-D FD_SIZE_4MB"
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
# {
|
||||
# "description": "OVMF with SEV-ES support",
|
||||
# "interface-types": [
|
||||
# "uefi"
|
||||
# ],
|
||||
# "mapping": {
|
||||
# "device": "flash",
|
||||
# "executable": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_CODE.fd",
|
||||
# "format": "raw"
|
||||
# },
|
||||
# "nvram-template": {
|
||||
# "filename": "/usr/share/OVMF/OVMF_VARS.fd",
|
||||
# "format": "raw"
|
||||
# }
|
||||
# },
|
||||
# "targets": [
|
||||
# {
|
||||
# "architecture": "x86_64",
|
||||
# "machines": [
|
||||
# "pc-q35-*"
|
||||
# ]
|
||||
# }
|
||||
# ],
|
||||
# "features": [
|
||||
# "acpi-s3",
|
||||
# "amd-sev",
|
||||
# "amd-sev-es",
|
||||
# "verbose-dynamic"
|
||||
# ],
|
||||
# "tags": [
|
||||
# "-a X64",
|
||||
# "-p OvmfPkg/OvmfPkgX64.dsc",
|
||||
# "-t GCC48",
|
||||
# "-b DEBUG",
|
||||
# "-D FD_SIZE_4MB"
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
# {
|
||||
# "description": "UEFI firmware for ARM64 virtual machines",
|
||||
# "interface-types": [
|
||||
# "uefi"
|
||||
# ],
|
||||
# "mapping": {
|
||||
# "device": "flash",
|
||||
# "executable": {
|
||||
# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
|
||||
# "format": "raw"
|
||||
# },
|
||||
# "nvram-template": {
|
||||
# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
|
||||
# "format": "raw"
|
||||
# }
|
||||
# },
|
||||
# "targets": [
|
||||
# {
|
||||
# "architecture": "aarch64",
|
||||
# "machines": [
|
||||
# "virt-*"
|
||||
# ]
|
||||
# }
|
||||
# ],
|
||||
# "features": [
|
||||
#
|
||||
# ],
|
||||
# "tags": [
|
||||
# "-a AARCH64",
|
||||
# "-p ArmVirtPkg/ArmVirtQemu.dsc",
|
||||
# "-t GCC48",
|
||||
# "-b DEBUG",
|
||||
# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
|
||||
# ]
|
||||
# }
|
||||
##
|
||||
{ 'struct' : 'Firmware',
|
||||
'data' : { 'description' : 'str',
|
||||
'interface-types' : [ 'FirmwareOSInterface' ],
|
||||
'mapping' : 'FirmwareMapping',
|
||||
'targets' : [ 'FirmwareTarget' ],
|
||||
'features' : [ 'FirmwareFeature' ],
|
||||
'tags' : [ 'str' ] } }
|
||||
@@ -0,0 +1,34 @@
|
||||
------------------------------------------------
|
||||
System Emulation Management and Interoperability
|
||||
------------------------------------------------
|
||||
|
||||
This section of the manual contains documents and specifications that
|
||||
are useful for making QEMU interoperate with other software.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
barrier
|
||||
bitmaps
|
||||
dbus
|
||||
dbus-vmstate
|
||||
dbus-display
|
||||
dbus-vnc
|
||||
live-block-operations
|
||||
nbd
|
||||
parallels
|
||||
prl-xml
|
||||
qcow2
|
||||
qed_spec
|
||||
pr-helper
|
||||
qmp-spec
|
||||
qemu-ga
|
||||
qemu-ga-ref
|
||||
qemu-qmp-ref
|
||||
qemu-storage-daemon-qmp-ref
|
||||
vfio-user
|
||||
vhost-user
|
||||
vhost-user-gpu
|
||||
vhost-vdpa
|
||||
virtio-balloon-stats
|
||||
vnc-ledstate-pseudo-encoding
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,89 @@
|
||||
QEMU NBD protocol support
|
||||
=========================
|
||||
|
||||
QEMU supports the NBD protocol, and has an internal NBD client (see
|
||||
``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an
|
||||
external NBD server tool (see ``qemu-nbd.c``). The common code is placed
|
||||
in ``nbd/*``.
|
||||
|
||||
The NBD protocol is specified here:
|
||||
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
|
||||
|
||||
The following paragraphs describe some specific properties of NBD
|
||||
protocol realization in QEMU.
|
||||
|
||||
Metadata namespaces
|
||||
-------------------
|
||||
|
||||
QEMU supports the ``base:allocation`` metadata context as defined in the
|
||||
NBD protocol specification, and also defines an additional metadata
|
||||
namespace ``qemu``.
|
||||
|
||||
``qemu`` namespace
|
||||
------------------
|
||||
|
||||
The ``qemu`` namespace currently contains two available metadata context
|
||||
types. The first is related to exposing the contents of a dirty
|
||||
bitmap alongside the associated disk contents. That metadata context
|
||||
is named with the following form::
|
||||
|
||||
qemu:dirty-bitmap:<dirty-bitmap-export-name>
|
||||
|
||||
Each dirty-bitmap metadata context defines only one flag for extents
|
||||
in reply for ``NBD_CMD_BLOCK_STATUS``:
|
||||
|
||||
bit 0:
|
||||
``NBD_STATE_DIRTY``, set when the extent is "dirty"
|
||||
|
||||
The second is related to exposing the source of various extents within
|
||||
the image, with a single metadata context named::
|
||||
|
||||
qemu:allocation-depth
|
||||
|
||||
In the allocation depth context, the entire 32-bit value represents a
|
||||
depth of which layer in a thin-provisioned backing chain provided the
|
||||
data (0 for unallocated, 1 for the active layer, 2 for the first
|
||||
backing layer, and so forth).
|
||||
|
||||
For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported
|
||||
in addition to the specific ``qemu:allocation-depth`` and
|
||||
``qemu:dirty-bitmap:<dirty-bitmap-export-name>``:
|
||||
|
||||
``qemu:``
|
||||
returns list of all available metadata contexts in the namespace
|
||||
``qemu:dirty-bitmap:``
|
||||
returns list of all available dirty-bitmap metadata contexts
|
||||
|
||||
Features by version
|
||||
-------------------
|
||||
|
||||
The following list documents which qemu version first implemented
|
||||
various features (both as a server exposing the feature, and as a
|
||||
client taking advantage of the feature when present), to make it
|
||||
easier to plan for cross-version interoperability. Note that in
|
||||
several cases, the initial release containing a feature may require
|
||||
additional patches from the corresponding stable branch to fix bugs in
|
||||
the operation of that feature.
|
||||
|
||||
2.6
|
||||
``NBD_OPT_STARTTLS`` with TLS X.509 Certificates
|
||||
2.8
|
||||
``NBD_CMD_WRITE_ZEROES``
|
||||
2.10
|
||||
``NBD_OPT_GO``, ``NBD_INFO_BLOCK``
|
||||
2.11
|
||||
``NBD_OPT_STRUCTURED_REPLY``
|
||||
2.12
|
||||
``NBD_CMD_BLOCK_STATUS`` for ``base:allocation``
|
||||
3.0
|
||||
``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK),
|
||||
``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE``
|
||||
4.2
|
||||
``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports,
|
||||
``NBD_CMD_FLAG_FAST_ZERO``
|
||||
5.2
|
||||
``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth``
|
||||
7.1
|
||||
``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports
|
||||
8.2
|
||||
``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD``
|
||||
@@ -0,0 +1,240 @@
|
||||
Parallels Expandable Image File Format
|
||||
======================================
|
||||
|
||||
..
|
||||
Copyright (c) 2015 Denis Lunev
|
||||
Copyright (c) 2015 Vladimir Sementsov-Ogievskiy
|
||||
|
||||
This work is licensed under the terms of the GNU GPL, version 2 or later.
|
||||
See the COPYING file in the top-level directory.
|
||||
|
||||
|
||||
A Parallels expandable image file consists of three consecutive parts:
|
||||
|
||||
* header
|
||||
* BAT
|
||||
* data area
|
||||
|
||||
All numbers in a Parallels expandable image are stored in little-endian byte
|
||||
order.
|
||||
|
||||
|
||||
Definitions
|
||||
-----------
|
||||
|
||||
Sector
|
||||
A 512-byte data chunk.
|
||||
|
||||
Cluster
|
||||
A data chunk of the size specified in the image header.
|
||||
Currently, the default size is 1MiB (2048 sectors). In previous
|
||||
versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were used.
|
||||
|
||||
BAT
|
||||
Block Allocation Table, an entity that contains information for
|
||||
guest-to-host I/O data address translation.
|
||||
|
||||
Header
|
||||
------
|
||||
|
||||
The header is placed at the start of an image and contains the following
|
||||
fields::
|
||||
|
||||
Bytes:
|
||||
0 - 15: magic
|
||||
Must contain "WithoutFreeSpace" or "WithouFreSpacExt".
|
||||
|
||||
16 - 19: version
|
||||
Must be 2.
|
||||
|
||||
20 - 23: heads
|
||||
Disk geometry parameter for guest.
|
||||
|
||||
24 - 27: cylinders
|
||||
Disk geometry parameter for guest.
|
||||
|
||||
28 - 31: tracks
|
||||
Cluster size, in sectors.
|
||||
|
||||
32 - 35: nb_bat_entries
|
||||
Disk size, in clusters (BAT size).
|
||||
|
||||
36 - 43: nb_sectors
|
||||
Disk size, in sectors.
|
||||
|
||||
For "WithoutFreeSpace" images:
|
||||
Only the lowest 4 bytes are used. The highest 4 bytes must be
|
||||
cleared in this case.
|
||||
|
||||
For "WithouFreSpacExt" images, there are no such
|
||||
restrictions.
|
||||
|
||||
44 - 47: in_use
|
||||
Set to 0x746F6E59 when the image is opened by software in R/W
|
||||
mode; set to 0x312e3276 when the image is closed.
|
||||
|
||||
A zero in this field means that the image was opened by an old
|
||||
version of the software that doesn't support Format Extension
|
||||
(see below).
|
||||
|
||||
Other values are not allowed.
|
||||
|
||||
48 - 51: data_off
|
||||
An offset, in sectors, from the start of the file to the start of
|
||||
the data area.
|
||||
|
||||
For "WithoutFreeSpace" images:
|
||||
- If data_off is zero, the offset is calculated as the end of BAT
|
||||
table plus some padding to ensure sector size alignment.
|
||||
- If data_off is non-zero, the offset should be aligned to sector
|
||||
size. However it is recommended to align it to cluster size for
|
||||
newly created images.
|
||||
|
||||
For "WithouFreSpacExt" images:
|
||||
data_off must be non-zero and aligned to cluster size.
|
||||
|
||||
52 - 55: flags
|
||||
Miscellaneous flags.
|
||||
|
||||
Bit 0: Empty Image bit. If set, the image should be
|
||||
considered clear.
|
||||
|
||||
Bits 1-31: Unused.
|
||||
|
||||
56 - 63: ext_off
|
||||
Format Extension offset, an offset, in sectors, from the start of
|
||||
the file to the start of the Format Extension Cluster.
|
||||
|
||||
ext_off must meet the same requirements as cluster offsets
|
||||
defined by BAT entries (see below).
|
||||
|
||||
BAT
|
||||
---
|
||||
|
||||
BAT is placed immediately after the image header. In the file, BAT is a
|
||||
contiguous array of 32-bit unsigned little-endian integers with
|
||||
``(bat_entries * 4)`` bytes size.
|
||||
|
||||
Each BAT entry contains an offset from the start of the file to the
|
||||
corresponding cluster. The offset set in clusters for ``WithouFreSpacExt``
|
||||
images and in sectors for ``WithoutFreeSpace`` images.
|
||||
|
||||
If a BAT entry is zero, the corresponding cluster is not allocated and should
|
||||
be considered as filled with zeroes.
|
||||
|
||||
Cluster offsets specified by BAT entries must meet the following requirements:
|
||||
|
||||
- the value must not be lower than data offset (provided by ``header.data_off``
|
||||
or calculated as specified above)
|
||||
- the value must be lower than the desired file size
|
||||
- the value must be unique among all BAT entries
|
||||
- the result of ``(cluster offset - data offset)`` must be aligned to
|
||||
cluster size
|
||||
|
||||
Data Area
|
||||
---------
|
||||
|
||||
The data area is an area from the data offset (provided by ``header.data_off``
|
||||
or calculated as specified above) to the end of the file. It represents a
|
||||
contiguous array of clusters. Most of them are allocated by the BAT, some may
|
||||
be allocated by the ``ext_off`` field in the header while other may be
|
||||
allocated by extensions. All clusters allocated by ``ext_off`` and extensions
|
||||
should meet the same requirements as clusters specified by BAT entries.
|
||||
|
||||
|
||||
Format Extension
|
||||
----------------
|
||||
|
||||
The Format Extension is an area 1 cluster in size that provides additional
|
||||
format features. This cluster is addressed by the ext_off field in the header.
|
||||
The format of the Format Extension area is the following::
|
||||
|
||||
0 - 7: magic
|
||||
Must be 0xAB234CEF23DCEA87
|
||||
|
||||
8 - 23: m_CheckSum
|
||||
The MD5 checksum of the entire Header Extension cluster except
|
||||
the first 24 bytes.
|
||||
|
||||
The above are followed by feature sections or "extensions". The last
|
||||
extension must be "End of features" (see below).
|
||||
|
||||
Each feature section has the following format::
|
||||
|
||||
0 - 7: magic
|
||||
The identifier of the feature:
|
||||
0x0000000000000000 - End of features
|
||||
0x20385FAE252CB34A - Dirty bitmap
|
||||
|
||||
8 - 15: flags
|
||||
External flags for extension:
|
||||
|
||||
Bit 0: NECESSARY
|
||||
If the software cannot load the extension (due to an
|
||||
unknown magic number or error), the file should not be
|
||||
changed. If this flag is unset and there is an error on
|
||||
loading the extension, said extension should be dropped.
|
||||
|
||||
Bit 1: TRANSIT
|
||||
If there is an unknown extension with this flag set,
|
||||
said extension should be left as is.
|
||||
|
||||
If neither NECESSARY nor TRANSIT are set, the extension should be
|
||||
dropped.
|
||||
|
||||
16 - 19: data_size
|
||||
The size of the following feature data, in bytes.
|
||||
|
||||
20 - 23: unused32
|
||||
Align header to 8 bytes boundary.
|
||||
|
||||
variable: data (data_size bytes)
|
||||
|
||||
The above is followed by padding to the next 8 bytes boundary, then the
|
||||
next extension starts.
|
||||
|
||||
The last extension must be "End of features" with all the fields set to 0.
|
||||
|
||||
|
||||
Dirty bitmaps feature
|
||||
---------------------
|
||||
|
||||
This feature provides a way of storing dirty bitmaps in the image. The fields
|
||||
of its data area are::
|
||||
|
||||
0 - 7: size
|
||||
The bitmap size, should be equal to disk size in sectors.
|
||||
|
||||
8 - 23: id
|
||||
An identifier for backup consistency checking.
|
||||
|
||||
24 - 27: granularity
|
||||
Bitmap granularity, in sectors. I.e., the number of sectors
|
||||
corresponding to one bit of the bitmap. Granularity must be
|
||||
a power of 2.
|
||||
|
||||
28 - 31: l1_size
|
||||
The number of entries in the L1 table of the bitmap.
|
||||
|
||||
variable: L1 offset table (l1_table), size: 8 * l1_size bytes
|
||||
|
||||
The dirty bitmap described by this feature extension is stored in a set of
|
||||
clusters inside the Parallels image file. The offsets of these clusters are
|
||||
saved in the L1 offset table specified by the feature extension. Each L1 table
|
||||
entry is a 64 bit integer as described below:
|
||||
|
||||
Given an offset in bytes into the bitmap data, corresponding L1 entry is::
|
||||
|
||||
l1_table[offset / cluster_size]
|
||||
|
||||
If an L1 table entry is 0, all bits in the corresponding cluster of the bitmap
|
||||
are assumed to be 0.
|
||||
|
||||
If an L1 table entry is 1, all bits in the corresponding cluster of the bitmap
|
||||
are assumed to be 1.
|
||||
|
||||
If an L1 table entry is not 0 or 1, it contains the corresponding cluster
|
||||
offset (in 512b sectors). Given an offset in bytes into the bitmap data the
|
||||
offset in bytes into the image file can be obtained as follows::
|
||||
|
||||
offset = l1_table[offset / cluster_size] * 512 + (offset % cluster_size)
|
||||
@@ -0,0 +1,83 @@
|
||||
..
|
||||
|
||||
======================================
|
||||
Persistent reservation helper protocol
|
||||
======================================
|
||||
|
||||
QEMU's SCSI passthrough devices, ``scsi-block`` and ``scsi-generic``,
|
||||
can delegate implementation of persistent reservations to an external
|
||||
(and typically privileged) program. Persistent Reservations allow
|
||||
restricting access to block devices to specific initiators in a shared
|
||||
storage setup.
|
||||
|
||||
For a more detailed reference please refer to the SCSI Primary
|
||||
Commands standard, specifically the section on Reservations and the
|
||||
"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands.
|
||||
|
||||
This document describes the socket protocol used between QEMU's
|
||||
``pr-manager-helper`` object and the external program.
|
||||
|
||||
.. contents::
|
||||
|
||||
Connection and initialization
|
||||
-----------------------------
|
||||
|
||||
All data transmitted on the socket is big-endian.
|
||||
|
||||
After connecting to the helper program's socket, the helper starts a simple
|
||||
feature negotiation process by writing four bytes corresponding to
|
||||
the features it exposes (``supported_features``). QEMU reads it,
|
||||
then writes four bytes corresponding to the desired features of the
|
||||
helper program (``requested_features``).
|
||||
|
||||
If a bit is 1 in ``requested_features`` and 0 in ``supported_features``,
|
||||
the corresponding feature is not supported by the helper and the connection
|
||||
is closed. On the other hand, it is acceptable for a bit to be 0 in
|
||||
``requested_features`` and 1 in ``supported_features``; in this case,
|
||||
the helper will not enable the feature.
|
||||
|
||||
Right now no feature is defined, so the two parties always write four
|
||||
zero bytes.
|
||||
|
||||
Command format
|
||||
--------------
|
||||
|
||||
It is invalid to send multiple commands concurrently on the same
|
||||
socket. It is however possible to connect multiple sockets to the
|
||||
helper and send multiple commands to the helper for one or more
|
||||
file descriptors.
|
||||
|
||||
A command consists of a request and a response. A request consists
|
||||
of a 16-byte SCSI CDB. A file descriptor must be passed to the helper
|
||||
together with the SCSI CDB using ancillary data.
|
||||
|
||||
The CDB has the following limitations:
|
||||
|
||||
- the command (stored in the first byte) must be one of 0x5E
|
||||
(PERSISTENT RESERVE IN) or 0x5F (PERSISTENT RESERVE OUT).
|
||||
|
||||
- the allocation length (stored in bytes 7-8 of the CDB for PERSISTENT
|
||||
RESERVE IN) or parameter list length (stored in bytes 5-8 of the CDB
|
||||
for PERSISTENT RESERVE OUT) is limited to 8 KiB.
|
||||
|
||||
For PERSISTENT RESERVE OUT, the parameter list is sent right after the
|
||||
CDB. The length of the parameter list is taken from the CDB itself.
|
||||
|
||||
The helper's reply has the following structure:
|
||||
|
||||
- 4 bytes for the SCSI status
|
||||
|
||||
- 4 bytes for the payload size (nonzero only for PERSISTENT RESERVE IN
|
||||
and only if the SCSI status is 0x00, i.e. GOOD)
|
||||
|
||||
- 96 bytes for the SCSI sense data
|
||||
|
||||
- if the size is nonzero, the payload follows
|
||||
|
||||
The sense data is always sent to keep the protocol simple, even though
|
||||
it is only valid if the SCSI status is CHECK CONDITION (0x02).
|
||||
|
||||
The payload size is always less than or equal to the allocation length
|
||||
specified in the CDB for the PERSISTENT RESERVE IN command.
|
||||
|
||||
If the protocol is violated, the helper closes the socket.
|
||||
@@ -0,0 +1,192 @@
|
||||
Parallels Disk Format
|
||||
=====================
|
||||
|
||||
..
|
||||
Copyright (c) 2015-2017, Virtuozzo, Inc.
|
||||
Authors:
|
||||
2015 Denis Lunev <[email protected]>
|
||||
2015 Vladimir Sementsov-Ogievskiy <[email protected]>
|
||||
2016-2017 Klim Kireev <[email protected]>
|
||||
2016-2017 Edgar Kaziakhmedov <[email protected]>
|
||||
|
||||
This work is licensed under the terms of the GNU GPL, version 2 or later.
|
||||
See the COPYING file in the top-level directory.
|
||||
|
||||
This specification contains minimal information about Parallels Disk Format,
|
||||
which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server
|
||||
and Parallels Desktop are able to add some unspecified nodes to the xml and use
|
||||
them, but they are for internal work and don't affect functionality. Also it
|
||||
uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot
|
||||
information, but this doesn't influence open/read/write functionality. QEMU and
|
||||
other software should not use fields not covered in this document or the
|
||||
``Snapshot.xml`` file, and must leave them as is.
|
||||
|
||||
A Parallels disk consists of two parts: the set of snapshots and the disk
|
||||
descriptor file, which stores information about all files and snapshots.
|
||||
|
||||
Definitions
|
||||
-----------
|
||||
|
||||
Snapshot
|
||||
a record of the contents captured at a particular time, capable
|
||||
of storing current state. A snapshot has a UUID and a parent UUID.
|
||||
|
||||
Snapshot image
|
||||
an overlay representing the difference between this
|
||||
snapshot and some earlier snapshot.
|
||||
|
||||
Overlay
|
||||
an image storing the different sectors between two captured states.
|
||||
|
||||
Root image
|
||||
a snapshot image with no parent, the root of the snapshot tree.
|
||||
|
||||
Storage
|
||||
the backing storage for a subset of the virtual disk. When
|
||||
there is more than one storage in a Parallels disk then that
|
||||
is referred to as a split image. In this case every storage
|
||||
covers a specific address space area of the disk and has its
|
||||
particular root image. Split images are not considered here
|
||||
and are not supported. Each storage consists of disk
|
||||
parameters and a list of images. The list of images always
|
||||
contains a root image and may also contain overlays. The
|
||||
root image can be an expandable Parallels image file or
|
||||
plain. Overlays must be expandable.
|
||||
|
||||
Description file
|
||||
``DiskDescriptor.xml`` stores information about disk parameters,
|
||||
snapshots, and storages.
|
||||
|
||||
Top Snapshot
|
||||
The overlay between actual state and some previous snapshot.
|
||||
It is not a snapshot in the classical sense because it
|
||||
serves as the active image that the guest writes to.
|
||||
|
||||
Sector
|
||||
a 512-byte data chunk.
|
||||
|
||||
Description file
|
||||
----------------
|
||||
|
||||
All information is placed in a single XML element
|
||||
``Parallels_disk_image``.
|
||||
The element has only one attribute, ``Version``, which must be ``1.0``.
|
||||
|
||||
The schema of ``DiskDescriptor.xml``::
|
||||
|
||||
<Parallels_disk_image Version="1.0">
|
||||
<Disk_Parameters>
|
||||
...
|
||||
</Disk_Parameters>
|
||||
<StorageData>
|
||||
...
|
||||
</StorageData>
|
||||
<Snapshots>
|
||||
...
|
||||
</Snapshots>
|
||||
</Parallels_disk_image>
|
||||
|
||||
``Disk_Parameters`` element
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``Disk_Parameters`` element describes the physical layout of the
|
||||
virtual disk and some general settings.
|
||||
|
||||
The ``Disk_Parameters`` element MUST contain the following child elements:
|
||||
|
||||
* ``Disk_size`` - number of sectors in the disk,
|
||||
desired size of the disk.
|
||||
* ``Cylinders`` - number of the disk cylinders.
|
||||
* ``Heads`` - number of the disk heads.
|
||||
* ``Sectors`` - number of the disk sectors per cylinder
|
||||
(sector size is 512 bytes)
|
||||
Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders``
|
||||
values MUST be equal to the value of the Disk_size parameter.
|
||||
* ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may
|
||||
use padding set to 1; however this case is not covered
|
||||
by this specification. QEMU and other software should not open
|
||||
such disks and should not create them.
|
||||
|
||||
``StorageData`` element
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This element of the file describes the root image and all snapshot images.
|
||||
|
||||
The ``StorageData`` element consists of the ``Storage`` child element,
|
||||
as shown below::
|
||||
|
||||
<StorageData>
|
||||
<Storage>
|
||||
...
|
||||
</Storage>
|
||||
</StorageData>
|
||||
|
||||
A ``Storage`` element has the following child elements:
|
||||
|
||||
* ``Start`` - start sector of the storage, in case of non split storage
|
||||
equals to 0.
|
||||
* ``End`` - number of sector following the last sector, in case of non
|
||||
split storage equals to ``Disk_size``.
|
||||
* ``Blocksize`` - storage cluster size, number of sectors per one cluster.
|
||||
The cluster size for each "Compressed" (see below) image in
|
||||
a parallels disk must be equal to this field. Note: the cluster
|
||||
size for a Parallels Expandable Image is in the ``tracks`` field of
|
||||
its header (see :doc:`parallels`).
|
||||
* Several ``Image`` child elements.
|
||||
|
||||
Each ``Image`` element has the following child elements:
|
||||
|
||||
* ``GUID`` - image identifier, UUID in curly brackets.
|
||||
For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.``
|
||||
The GUID is used by the Snapshots element to reference images
|
||||
(see below)
|
||||
* ``Type`` - image type of the element. It can be:
|
||||
|
||||
* ``Plain`` for raw files.
|
||||
* ``Compressed`` for expanding disks.
|
||||
|
||||
* ``File`` - path to image file. The path can be relative to
|
||||
``DiskDescriptor.xml`` or absolute.
|
||||
|
||||
``Snapshots`` element
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``Snapshots`` element describes the snapshot relations with the snapshot tree.
|
||||
|
||||
The element contains the set of ``Shot`` child elements, as shown below::
|
||||
|
||||
<Snapshots>
|
||||
<TopGUID> ... </TopGUID> /* Optional child element */
|
||||
<Shot>
|
||||
...
|
||||
</Shot>
|
||||
<Shot>
|
||||
...
|
||||
</Shot>
|
||||
...
|
||||
</Snapshots>
|
||||
|
||||
Each ``Shot`` element contains the following child elements:
|
||||
|
||||
* ``GUID`` - an image GUID.
|
||||
* ``ParentGUID`` - GUID of the image of the parent snapshot.
|
||||
|
||||
The software may traverse snapshots from child to parent using the
|
||||
``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root
|
||||
snapshot is ``{00000000-0000-0000-0000-000000000000}``.
|
||||
There should be only one root snapshot.
|
||||
|
||||
The Top snapshot could be
|
||||
described via two ways: via the ``TopGUID`` child
|
||||
element of the ``Snapshots`` element, or via the predefined GUID
|
||||
``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined,
|
||||
the predefined GUID is interpreted as a normal GUID. All snapshot images
|
||||
(except the Top Snapshot) should be
|
||||
opened read-only.
|
||||
|
||||
There is another predefined GUID,
|
||||
``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by
|
||||
original and some third-party software for backup. QEMU and other
|
||||
software may operate with images with ``GUID = BackupID`` as usual.
|
||||
However, it is not recommended to use this
|
||||
GUID for new disks. The Top snapshot cannot have this GUID.
|
||||
@@ -0,0 +1,937 @@
|
||||
=======================
|
||||
Qcow2 Image File Format
|
||||
=======================
|
||||
|
||||
A ``qcow2`` image file is organized in units of constant size, which are called
|
||||
(host) clusters. A cluster is the unit in which all allocations are done,
|
||||
both for actual guest data and for image metadata.
|
||||
|
||||
Likewise, the virtual disk as seen by the guest is divided into (guest)
|
||||
clusters of the same size.
|
||||
|
||||
All numbers in qcow2 are stored in Big Endian byte order.
|
||||
|
||||
Header
|
||||
------
|
||||
|
||||
The first cluster of a qcow2 image contains the file header::
|
||||
|
||||
Byte 0 - 3: magic
|
||||
QCOW magic string ("QFI\xfb")
|
||||
|
||||
4 - 7: version
|
||||
Version number (valid values are 2 and 3)
|
||||
|
||||
8 - 15: backing_file_offset
|
||||
Offset into the image file at which the backing file name
|
||||
is stored (NB: The string is not null terminated). 0 if the
|
||||
image doesn't have a backing file.
|
||||
|
||||
Note: backing files are incompatible with raw external data
|
||||
files (auto-clear feature bit 1).
|
||||
|
||||
16 - 19: backing_file_size
|
||||
Length of the backing file name in bytes. Must not be
|
||||
longer than 1023 bytes. Undefined if the image doesn't have
|
||||
a backing file.
|
||||
|
||||
20 - 23: cluster_bits
|
||||
Number of bits that are used for addressing an offset
|
||||
within a cluster (1 << cluster_bits is the cluster size).
|
||||
Must not be less than 9 (i.e. 512 byte clusters).
|
||||
|
||||
Note: QEMU as of today has an implementation limit of 2 MB
|
||||
as the maximum cluster size and won't be able to open images
|
||||
with larger cluster sizes.
|
||||
|
||||
Note: if the image has Extended L2 Entries then cluster_bits
|
||||
must be at least 14 (i.e. 16384 byte clusters).
|
||||
|
||||
24 - 31: size
|
||||
Virtual disk size in bytes.
|
||||
|
||||
Note: QEMU has an implementation limit of 32 MB as
|
||||
the maximum L1 table size. With a 2 MB cluster
|
||||
size, it is unable to populate a virtual cluster
|
||||
beyond 2 EB (61 bits); with a 512 byte cluster
|
||||
size, it is unable to populate a virtual size
|
||||
larger than 128 GB (37 bits). Meanwhile, L1/L2
|
||||
table layouts limit an image to no more than 64 PB
|
||||
(56 bits) of populated clusters, and an image may
|
||||
hit other limits first (such as a file system's
|
||||
maximum size).
|
||||
|
||||
32 - 35: crypt_method
|
||||
0 for no encryption
|
||||
1 for AES encryption
|
||||
2 for LUKS encryption
|
||||
|
||||
36 - 39: l1_size
|
||||
Number of entries in the active L1 table
|
||||
|
||||
40 - 47: l1_table_offset
|
||||
Offset into the image file at which the active L1 table
|
||||
starts. Must be aligned to a cluster boundary.
|
||||
|
||||
48 - 55: refcount_table_offset
|
||||
Offset into the image file at which the refcount table
|
||||
starts. Must be aligned to a cluster boundary.
|
||||
|
||||
56 - 59: refcount_table_clusters
|
||||
Number of clusters that the refcount table occupies
|
||||
|
||||
60 - 63: nb_snapshots
|
||||
Number of snapshots contained in the image
|
||||
|
||||
64 - 71: snapshots_offset
|
||||
Offset into the image file at which the snapshot table
|
||||
starts. Must be aligned to a cluster boundary.
|
||||
|
||||
For version 2, the header is exactly 72 bytes in length, and finishes here.
|
||||
For version 3 or higher, the header length is at least 104 bytes, including
|
||||
the next fields through ``header_length``.
|
||||
::
|
||||
|
||||
72 - 79: incompatible_features
|
||||
Bitmask of incompatible features. An implementation must
|
||||
fail to open an image if an unknown bit is set.
|
||||
|
||||
Bit 0: Dirty bit. If this bit is set then refcounts
|
||||
may be inconsistent, make sure to scan L1/L2
|
||||
tables to repair refcounts before accessing the
|
||||
image.
|
||||
|
||||
Bit 1: Corrupt bit. If this bit is set then any data
|
||||
structure may be corrupt and the image must not
|
||||
be written to (unless for regaining
|
||||
consistency).
|
||||
|
||||
Bit 2: External data file bit. If this bit is set, an
|
||||
external data file is used. Guest clusters are
|
||||
then stored in the external data file. For such
|
||||
images, clusters in the external data file are
|
||||
not refcounted. The offset field in the
|
||||
Standard Cluster Descriptor must match the
|
||||
guest offset and neither compressed clusters
|
||||
nor internal snapshots are supported.
|
||||
|
||||
An External Data File Name header extension may
|
||||
be present if this bit is set.
|
||||
|
||||
Bit 3: Compression type bit. If this bit is set,
|
||||
a non-default compression is used for compressed
|
||||
clusters. The compression_type field must be
|
||||
present and not zero.
|
||||
|
||||
Bit 4: Extended L2 Entries. If this bit is set then
|
||||
L2 table entries use an extended format that
|
||||
allows subcluster-based allocation. See the
|
||||
Extended L2 Entries section for more details.
|
||||
|
||||
Bits 5-63: Reserved (set to 0)
|
||||
|
||||
80 - 87: compatible_features
|
||||
Bitmask of compatible features. An implementation can
|
||||
safely ignore any unknown bits that are set.
|
||||
|
||||
Bit 0: Lazy refcounts bit. If this bit is set then
|
||||
lazy refcount updates can be used. This means
|
||||
marking the image file dirty and postponing
|
||||
refcount metadata updates.
|
||||
|
||||
Bits 1-63: Reserved (set to 0)
|
||||
|
||||
88 - 95: autoclear_features
|
||||
Bitmask of auto-clear features. An implementation may only
|
||||
write to an image with unknown auto-clear features if it
|
||||
clears the respective bits from this field first.
|
||||
|
||||
Bit 0: Bitmaps extension bit
|
||||
This bit indicates consistency for the bitmaps
|
||||
extension data.
|
||||
|
||||
It is an error if this bit is set without the
|
||||
bitmaps extension present.
|
||||
|
||||
If the bitmaps extension is present but this
|
||||
bit is unset, the bitmaps extension data must be
|
||||
considered inconsistent.
|
||||
|
||||
Bit 1: Raw external data bit
|
||||
If this bit is set, the external data file can
|
||||
be read as a consistent standalone raw image
|
||||
without looking at the qcow2 metadata.
|
||||
|
||||
Setting this bit has a performance impact for
|
||||
some operations on the image (e.g. writing
|
||||
zeros requires writing to the data file instead
|
||||
of only setting the zero flag in the L2 table
|
||||
entry) and conflicts with backing files.
|
||||
|
||||
This bit may only be set if the External Data
|
||||
File bit (incompatible feature bit 1) is also
|
||||
set.
|
||||
|
||||
Bits 2-63: Reserved (set to 0)
|
||||
|
||||
96 - 99: refcount_order
|
||||
Describes the width of a reference count block entry (width
|
||||
in bits: refcount_bits = 1 << refcount_order). For version 2
|
||||
images, the order is always assumed to be 4
|
||||
(i.e. refcount_bits = 16).
|
||||
This value may not exceed 6 (i.e. refcount_bits = 64).
|
||||
|
||||
100 - 103: header_length
|
||||
Length of the header structure in bytes. For version 2
|
||||
images, the length is always assumed to be 72 bytes.
|
||||
For version 3 it's at least 104 bytes and must be a multiple
|
||||
of 8.
|
||||
|
||||
|
||||
Additional fields (version 3 and higher)
|
||||
----------------------------------------
|
||||
|
||||
In general, these fields are optional and may be safely ignored by the software,
|
||||
as well as filled by zeros (which is equal to field absence), if software needs
|
||||
to set field B, but does not care about field A which precedes B. More
|
||||
formally, additional fields have the following compatibility rules:
|
||||
|
||||
1. If the value of the additional field must not be ignored for correct
|
||||
handling of the file, it will be accompanied by a corresponding incompatible
|
||||
feature bit.
|
||||
|
||||
2. If there are no unrecognized incompatible feature bits set, an unknown
|
||||
additional field may be safely ignored other than preserving its value when
|
||||
rewriting the image header.
|
||||
|
||||
.. _ref_rules_3:
|
||||
|
||||
3. An explicit value of 0 will have the same behavior as when the field is not
|
||||
present*, if not altered by a specific incompatible bit.
|
||||
|
||||
(*) A field is considered not present when ``header_length`` is less than or equal
|
||||
to the field's offset. Also, all additional fields are not present for
|
||||
version 2.
|
||||
|
||||
::
|
||||
|
||||
104: compression_type
|
||||
|
||||
Defines the compression method used for compressed clusters.
|
||||
All compressed clusters in an image use the same compression
|
||||
type.
|
||||
|
||||
If the incompatible bit "Compression type" is set: the field
|
||||
must be present and non-zero (which means non-deflate
|
||||
compression type). Otherwise, this field must not be present
|
||||
or must be zero (which means deflate).
|
||||
|
||||
Available compression type values:
|
||||
- 0: deflate <https://www.ietf.org/rfc/rfc1951.txt>
|
||||
- 1: zstd <http://github.com/facebook/zstd>
|
||||
|
||||
The deflate compression type is called "zlib"
|
||||
<https://www.zlib.net/> in QEMU. However, clusters with the
|
||||
deflate compression type do not have zlib headers.
|
||||
|
||||
105 - 111: Padding, contents defined below.
|
||||
|
||||
Header padding
|
||||
--------------
|
||||
|
||||
``header_length`` must be a multiple of 8, which means that if the end of the last
|
||||
additional field is not aligned, some padding is needed. This padding must be
|
||||
zeroed, so that if some existing (or future) additional field will fall into
|
||||
the padding, it will be interpreted accordingly to point `[3.] <#ref_rules_3>`_ of the previous
|
||||
paragraph, i.e. in the same manner as when this field is not present.
|
||||
|
||||
|
||||
Header extensions
|
||||
-----------------
|
||||
|
||||
Directly after the image header, optional sections called header extensions can
|
||||
be stored. Each extension has a structure like the following::
|
||||
|
||||
Byte 0 - 3: Header extension type:
|
||||
0x00000000 - End of the header extension area
|
||||
0xe2792aca - Backing file format name string
|
||||
0x6803f857 - Feature name table
|
||||
0x23852875 - Bitmaps extension
|
||||
0x0537be77 - Full disk encryption header pointer
|
||||
0x44415441 - External data file name string
|
||||
other - Unknown header extension, can be safely
|
||||
ignored
|
||||
|
||||
4 - 7: Length of the header extension data
|
||||
|
||||
8 - n: Header extension data
|
||||
|
||||
n - m: Padding to round up the header extension size to the next
|
||||
multiple of 8.
|
||||
|
||||
Unless stated otherwise, each header extension type shall appear at most once
|
||||
in the same image.
|
||||
|
||||
If the image has a backing file then the backing file name should be stored in
|
||||
the remaining space between the end of the header extension area and the end of
|
||||
the first cluster. It is not allowed to store other data here, so that an
|
||||
implementation can safely modify the header and add extensions without harming
|
||||
data of compatible features that it doesn't support. Compatible features that
|
||||
need space for additional data can use a header extension.
|
||||
|
||||
|
||||
String header extensions
|
||||
------------------------
|
||||
|
||||
Some header extensions (such as the backing file format name and the external
|
||||
data file name) are just a single string. In this case, the header extension
|
||||
length is the string length and the string is not ``\0`` terminated. (The header
|
||||
extension padding can make it look like a string is ``\0`` terminated, but
|
||||
neither is padding always necessary nor is there a guarantee that zero bytes
|
||||
are used for padding.)
|
||||
|
||||
|
||||
Feature name table
|
||||
------------------
|
||||
|
||||
The feature name table is an optional header extension that contains the name
|
||||
for features used by the image. It can be used by applications that don't know
|
||||
the respective feature (e.g. because the feature was introduced only later) to
|
||||
display a useful error message.
|
||||
|
||||
The number of entries in the feature name table is determined by the length of
|
||||
the header extension data. Each entry looks like this::
|
||||
|
||||
Byte 0: Type of feature (select feature bitmap)
|
||||
0: Incompatible feature
|
||||
1: Compatible feature
|
||||
2: Autoclear feature
|
||||
|
||||
1: Bit number within the selected feature bitmap (valid
|
||||
values: 0-63)
|
||||
|
||||
2 - 47: Feature name (padded with zeros, but not necessarily null
|
||||
terminated if it has full length)
|
||||
|
||||
|
||||
Bitmaps extension
|
||||
-----------------
|
||||
|
||||
The bitmaps extension is an optional header extension. It provides the ability
|
||||
to store bitmaps related to a virtual disk. For now, there is only one bitmap
|
||||
type: the dirty tracking bitmap, which tracks virtual disk changes from some
|
||||
point in time.
|
||||
|
||||
The data of the extension should be considered consistent only if the
|
||||
corresponding auto-clear feature bit is set, see ``autoclear_features`` above.
|
||||
|
||||
The fields of the bitmaps extension are::
|
||||
|
||||
Byte 0 - 3: nb_bitmaps
|
||||
The number of bitmaps contained in the image. Must be
|
||||
greater than or equal to 1.
|
||||
|
||||
Note: QEMU currently only supports up to 65535 bitmaps per
|
||||
image.
|
||||
|
||||
4 - 7: Reserved, must be zero.
|
||||
|
||||
8 - 15: bitmap_directory_size
|
||||
Size of the bitmap directory in bytes. It is the cumulative
|
||||
size of all (nb_bitmaps) bitmap directory entries.
|
||||
|
||||
16 - 23: bitmap_directory_offset
|
||||
Offset into the image file at which the bitmap directory
|
||||
starts. Must be aligned to a cluster boundary.
|
||||
|
||||
Full disk encryption header pointer
|
||||
-----------------------------------
|
||||
|
||||
The full disk encryption header must be present if, and only if, the
|
||||
``crypt_method`` header requires metadata. Currently this is only true
|
||||
of the ``LUKS`` crypt method. The header extension must be absent for
|
||||
other methods.
|
||||
|
||||
This header provides the offset at which the crypt method can store
|
||||
its additional data, as well as the length of such data.
|
||||
::
|
||||
|
||||
Byte 0 - 7: Offset into the image file at which the encryption
|
||||
header starts in bytes. Must be aligned to a cluster
|
||||
boundary.
|
||||
Byte 8 - 15: Length of the written encryption header in bytes.
|
||||
Note actual space allocated in the qcow2 file may
|
||||
be larger than this value, since it will be rounded
|
||||
to the nearest multiple of the cluster size. Any
|
||||
unused bytes in the allocated space will be initialized
|
||||
to 0.
|
||||
|
||||
For the LUKS crypt method, the encryption header works as follows.
|
||||
|
||||
The first 592 bytes of the header clusters will contain the LUKS
|
||||
partition header. This is then followed by the key material data areas.
|
||||
The size of the key material data areas is determined by the number of
|
||||
stripes in the key slot and key size. Refer to the LUKS format
|
||||
specification (``docs/on-disk-format.pdf`` in the cryptsetup source
|
||||
package) for details of the LUKS partition header format.
|
||||
|
||||
In the LUKS partition header, the ``payload-offset`` field will be
|
||||
calculated as normal for the LUKS spec. ie the size of the LUKS
|
||||
header, plus key material regions, plus padding, relative to the
|
||||
start of the LUKS header. This offset value is not required to be
|
||||
qcow2 cluster aligned. Its value is currently never used in the
|
||||
context of qcow2, since the qcow2 file format itself defines where
|
||||
the real payload offset is, but none the less a valid payload offset
|
||||
should always be present.
|
||||
|
||||
In the LUKS key slots header, the ``key-material-offset`` is relative
|
||||
to the start of the LUKS header clusters in the qcow2 container,
|
||||
not the start of the qcow2 file.
|
||||
|
||||
Logically the layout looks like
|
||||
::
|
||||
|
||||
+-----------------------------+
|
||||
| QCow2 header |
|
||||
| QCow2 header extension X |
|
||||
| QCow2 header extension FDE |
|
||||
| QCow2 header extension ... |
|
||||
| QCow2 header extension Z |
|
||||
+-----------------------------+
|
||||
| ....other QCow2 tables.... |
|
||||
. .
|
||||
. .
|
||||
+-----------------------------+
|
||||
| +-------------------------+ |
|
||||
| | LUKS partition header | |
|
||||
| +-------------------------+ |
|
||||
| | LUKS key material 1 | |
|
||||
| +-------------------------+ |
|
||||
| | LUKS key material 2 | |
|
||||
| +-------------------------+ |
|
||||
| | LUKS key material ... | |
|
||||
| +-------------------------+ |
|
||||
| | LUKS key material 8 | |
|
||||
| +-------------------------+ |
|
||||
+-----------------------------+
|
||||
| QCow2 cluster payload |
|
||||
. .
|
||||
. .
|
||||
. .
|
||||
| |
|
||||
+-----------------------------+
|
||||
|
||||
Data encryption
|
||||
---------------
|
||||
|
||||
When an encryption method is requested in the header, the image payload
|
||||
data must be encrypted/decrypted on every write/read. The image headers
|
||||
and metadata are never encrypted.
|
||||
|
||||
The algorithms used for encryption vary depending on the method
|
||||
|
||||
- ``AES``:
|
||||
|
||||
The AES cipher, in CBC mode, with 256 bit keys.
|
||||
|
||||
Initialization vectors generated using plain64 method, with
|
||||
the virtual disk sector as the input tweak.
|
||||
|
||||
This format is no longer supported in QEMU system emulators, due
|
||||
to a number of design flaws affecting its security. It is only
|
||||
supported in the command line tools for the sake of back compatibility
|
||||
and data liberation.
|
||||
|
||||
- ``LUKS``:
|
||||
|
||||
The algorithms are specified in the LUKS header.
|
||||
|
||||
Initialization vectors generated using the method specified
|
||||
in the LUKS header, with the physical disk sector as the
|
||||
input tweak.
|
||||
|
||||
Host cluster management
|
||||
-----------------------
|
||||
|
||||
qcow2 manages the allocation of host clusters by maintaining a reference count
|
||||
for each host cluster. A refcount of 0 means that the cluster is free, 1 means
|
||||
that it is used, and >= 2 means that it is used and any write access must
|
||||
perform a COW (copy on write) operation.
|
||||
|
||||
The refcounts are managed in a two-level table. The first level is called
|
||||
refcount table and has a variable size (which is stored in the header). The
|
||||
refcount table can cover multiple clusters, however it needs to be contiguous
|
||||
in the image file.
|
||||
|
||||
It contains pointers to the second level structures which are called refcount
|
||||
blocks and are exactly one cluster in size.
|
||||
|
||||
Although a large enough refcount table can reserve clusters past 64 PB
|
||||
(56 bits) (assuming the underlying protocol can even be sized that
|
||||
large), note that some qcow2 metadata such as L1/L2 tables must point
|
||||
to clusters prior to that point.
|
||||
|
||||
.. note::
|
||||
QEMU has an implementation limit of 8 MB as the maximum refcount
|
||||
table size. With a 2 MB cluster size and a default refcount_order of
|
||||
4, it is unable to reference host resources beyond 2 EB (61 bits); in
|
||||
the worst case, with a 512 cluster size and refcount_order of 6, it is
|
||||
unable to access beyond 32 GB (35 bits).
|
||||
|
||||
Given an offset into the image file, the refcount of its cluster can be
|
||||
obtained as follows::
|
||||
|
||||
refcount_block_entries = (cluster_size * 8 / refcount_bits)
|
||||
|
||||
refcount_block_index = (offset / cluster_size) % refcount_block_entries
|
||||
refcount_table_index = (offset / cluster_size) / refcount_block_entries
|
||||
|
||||
refcount_block = load_cluster(refcount_table[refcount_table_index]);
|
||||
return refcount_block[refcount_block_index];
|
||||
|
||||
Refcount table entry::
|
||||
|
||||
Bit 0 - 8: Reserved (set to 0)
|
||||
|
||||
9 - 63: Bits 9-63 of the offset into the image file at which the
|
||||
refcount block starts. Must be aligned to a cluster
|
||||
boundary.
|
||||
|
||||
If this is 0, the corresponding refcount block has not yet
|
||||
been allocated. All refcounts managed by this refcount block
|
||||
are 0.
|
||||
|
||||
Refcount block entry ``(x = refcount_bits - 1)``::
|
||||
|
||||
Bit 0 - x: Reference count of the cluster. If refcount_bits implies a
|
||||
sub-byte width, note that bit 0 means the least significant
|
||||
bit in this context.
|
||||
|
||||
|
||||
Cluster mapping
|
||||
---------------
|
||||
|
||||
Just as for refcounts, qcow2 uses a two-level structure for the mapping of
|
||||
guest clusters to host clusters. They are called L1 and L2 table.
|
||||
|
||||
The L1 table has a variable size (stored in the header) and may use multiple
|
||||
clusters, however it must be contiguous in the image file. L2 tables are
|
||||
exactly one cluster in size.
|
||||
|
||||
The L1 and L2 tables have implications on the maximum virtual file
|
||||
size; for a given L1 table size, a larger cluster size is required for
|
||||
the guest to have access to more space. Furthermore, a virtual
|
||||
cluster must currently map to a host offset below 64 PB (56 bits)
|
||||
(although this limit could be relaxed by putting reserved bits into
|
||||
use). Additionally, as cluster size increases, the maximum host
|
||||
offset for a compressed cluster is reduced (a 2M cluster size requires
|
||||
compressed clusters to reside below 512 TB (49 bits), and this limit
|
||||
cannot be relaxed without an incompatible layout change).
|
||||
|
||||
Given an offset into the virtual disk, the offset into the image file can be
|
||||
obtained as follows::
|
||||
|
||||
l2_entries = (cluster_size / sizeof(uint64_t)) [*]
|
||||
|
||||
l2_index = (offset / cluster_size) % l2_entries
|
||||
l1_index = (offset / cluster_size) / l2_entries
|
||||
|
||||
l2_table = load_cluster(l1_table[l1_index]);
|
||||
cluster_offset = l2_table[l2_index];
|
||||
|
||||
return cluster_offset + (offset % cluster_size)
|
||||
|
||||
[*] this changes if Extended L2 Entries are enabled, see next section
|
||||
|
||||
L1 table entry::
|
||||
|
||||
Bit 0 - 8: Reserved (set to 0)
|
||||
|
||||
9 - 55: Bits 9-55 of the offset into the image file at which the L2
|
||||
table starts. Must be aligned to a cluster boundary. If the
|
||||
offset is 0, the L2 table and all clusters described by this
|
||||
L2 table are unallocated.
|
||||
|
||||
56 - 62: Reserved (set to 0)
|
||||
|
||||
63: 0 for an L2 table that is unused or requires COW, 1 if its
|
||||
refcount is exactly one. This information is only accurate
|
||||
in the active L1 table.
|
||||
|
||||
L2 table entry::
|
||||
|
||||
Bit 0 - 61: Cluster descriptor
|
||||
|
||||
62: 0 for standard clusters
|
||||
1 for compressed clusters
|
||||
|
||||
63: 0 for clusters that are unused, compressed or require COW.
|
||||
1 for standard clusters whose refcount is exactly one.
|
||||
This information is only accurate in L2 tables
|
||||
that are reachable from the active L1 table.
|
||||
|
||||
With external data files, all guest clusters have an
|
||||
implicit refcount of 1 (because of the fixed host = guest
|
||||
mapping for guest cluster offsets), so this bit should be 1
|
||||
for all allocated clusters.
|
||||
|
||||
Standard Cluster Descriptor::
|
||||
|
||||
Bit 0: If set to 1, the cluster reads as all zeros. The host
|
||||
cluster offset can be used to describe a preallocation,
|
||||
but it won't be used for reading data from this cluster,
|
||||
nor is data read from the backing file if the cluster is
|
||||
unallocated.
|
||||
|
||||
With version 2 or with extended L2 entries (see the next
|
||||
section), this is always 0.
|
||||
|
||||
1 - 8: Reserved (set to 0)
|
||||
|
||||
9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a
|
||||
cluster boundary. If the offset is 0 and bit 63 is clear,
|
||||
the cluster is unallocated. The offset may only be 0 with
|
||||
bit 63 set (indicating a host cluster offset of 0) when an
|
||||
external data file is used.
|
||||
|
||||
56 - 61: Reserved (set to 0)
|
||||
|
||||
|
||||
Compressed Clusters Descriptor ``(x = 62 - (cluster_bits - 8))``::
|
||||
|
||||
Bit 0 - x-1: Host cluster offset. This is usually _not_ aligned to a
|
||||
cluster or sector boundary! If cluster_bits is
|
||||
small enough that this field includes bits beyond
|
||||
55, those upper bits must be set to 0.
|
||||
|
||||
x - 61: Number of additional 512-byte sectors used for the
|
||||
compressed data, beyond the sector containing the offset
|
||||
in the previous field. Some of these sectors may reside
|
||||
in the next contiguous host cluster.
|
||||
|
||||
Note that the compressed data does not necessarily occupy
|
||||
all of the bytes in the final sector; rather, decompression
|
||||
stops when it has produced a cluster of data.
|
||||
|
||||
Another compressed cluster may map to the tail of the final
|
||||
sector used by this compressed cluster.
|
||||
|
||||
If a cluster is unallocated, read requests shall read the data from the backing
|
||||
file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
|
||||
no backing file or the backing file is smaller than the image, they shall read
|
||||
zeros for all parts that are not covered by the backing file.
|
||||
|
||||
Extended L2 Entries
|
||||
-------------------
|
||||
|
||||
An image uses Extended L2 Entries if bit 4 is set on the incompatible_features
|
||||
field of the header.
|
||||
|
||||
In these images standard data clusters are divided into 32 subclusters of the
|
||||
same size. They are contiguous and start from the beginning of the cluster.
|
||||
Subclusters can be allocated independently and the L2 entry contains information
|
||||
indicating the status of each one of them. Compressed data clusters don't have
|
||||
subclusters so they are treated the same as in images without this feature.
|
||||
|
||||
The size of an extended L2 entry is 128 bits so the number of entries per table
|
||||
is calculated using this formula:
|
||||
|
||||
.. code::
|
||||
|
||||
l2_entries = (cluster_size / (2 * sizeof(uint64_t)))
|
||||
|
||||
The first 64 bits have the same format as the standard L2 table entry described
|
||||
in the previous section, with the exception of bit 0 of the standard cluster
|
||||
descriptor.
|
||||
|
||||
The last 64 bits contain a subcluster allocation bitmap with this format:
|
||||
|
||||
Subcluster Allocation Bitmap (for standard clusters)::
|
||||
|
||||
Bit 0 - 31: Allocation status (one bit per subcluster)
|
||||
|
||||
1: the subcluster is allocated. In this case the
|
||||
host cluster offset field must contain a valid
|
||||
offset.
|
||||
0: the subcluster is not allocated. In this case
|
||||
read requests shall go to the backing file or
|
||||
return zeros if there is no backing file data.
|
||||
|
||||
Bits are assigned starting from the least significant
|
||||
one (i.e. bit x is used for subcluster x).
|
||||
|
||||
32 - 63 Subcluster reads as zeros (one bit per subcluster)
|
||||
|
||||
1: the subcluster reads as zeros. In this case the
|
||||
allocation status bit must be unset. The host
|
||||
cluster offset field may or may not be set.
|
||||
0: no effect.
|
||||
|
||||
Bits are assigned starting from the least significant
|
||||
one (i.e. bit x is used for subcluster x - 32).
|
||||
|
||||
Subcluster Allocation Bitmap (for compressed clusters)::
|
||||
|
||||
Bit 0 - 63: Reserved (set to 0)
|
||||
Compressed clusters don't have subclusters,
|
||||
so this field is not used.
|
||||
|
||||
Snapshots
|
||||
---------
|
||||
|
||||
qcow2 supports internal snapshots. Their basic principle of operation is to
|
||||
switch the active L1 table, so that a different set of host clusters are
|
||||
exposed to the guest.
|
||||
|
||||
When creating a snapshot, the L1 table should be copied and the refcount of all
|
||||
L2 tables and clusters reachable from this L1 table must be increased, so that
|
||||
a write causes a COW and isn't visible in other snapshots.
|
||||
|
||||
When loading a snapshot, bit 63 of all entries in the new active L1 table and
|
||||
all L2 tables referenced by it must be reconstructed from the refcount table
|
||||
as it doesn't need to be accurate in inactive L1 tables.
|
||||
|
||||
A directory of all snapshots is stored in the snapshot table, a contiguous area
|
||||
in the image file, whose starting offset and length are given by the header
|
||||
fields snapshots_offset and nb_snapshots. The entries of the snapshot table
|
||||
have variable length, depending on the length of ID, name and extra data.
|
||||
|
||||
Snapshot table entry::
|
||||
|
||||
Byte 0 - 7: Offset into the image file at which the L1 table for the
|
||||
snapshot starts. Must be aligned to a cluster boundary.
|
||||
|
||||
8 - 11: Number of entries in the L1 table of the snapshots
|
||||
|
||||
12 - 13: Length of the unique ID string describing the snapshot
|
||||
|
||||
14 - 15: Length of the name of the snapshot
|
||||
|
||||
16 - 19: Time at which the snapshot was taken in seconds since the
|
||||
Epoch
|
||||
|
||||
20 - 23: Subsecond part of the time at which the snapshot was taken
|
||||
in nanoseconds
|
||||
|
||||
24 - 31: Time that the guest was running until the snapshot was
|
||||
taken in nanoseconds
|
||||
|
||||
32 - 35: Size of the VM state in bytes. 0 if no VM state is saved.
|
||||
If there is VM state, it starts at the first cluster
|
||||
described by first L1 table entry that doesn't describe a
|
||||
regular guest cluster (i.e. VM state is stored like guest
|
||||
disk content, except that it is stored at offsets that are
|
||||
larger than the virtual disk presented to the guest)
|
||||
|
||||
36 - 39: Size of extra data in the table entry (used for future
|
||||
extensions of the format)
|
||||
|
||||
variable: Extra data for future extensions. Unknown fields must be
|
||||
ignored. Currently defined are (offset relative to snapshot
|
||||
table entry):
|
||||
|
||||
Byte 40 - 47: Size of the VM state in bytes. 0 if no VM
|
||||
state is saved. If this field is present,
|
||||
the 32-bit value in bytes 32-35 is ignored.
|
||||
|
||||
Byte 48 - 55: Virtual disk size of the snapshot in bytes
|
||||
|
||||
Byte 56 - 63: icount value which corresponds to
|
||||
the record/replay instruction count
|
||||
when the snapshot was taken. Set to -1
|
||||
if icount was disabled
|
||||
|
||||
Version 3 images must include extra data at least up to
|
||||
byte 55.
|
||||
|
||||
variable: Unique ID string for the snapshot (not null terminated)
|
||||
|
||||
variable: Name of the snapshot (not null terminated)
|
||||
|
||||
variable: Padding to round up the snapshot table entry size to the
|
||||
next multiple of 8.
|
||||
|
||||
|
||||
Bitmaps
|
||||
-------
|
||||
|
||||
As mentioned above, the bitmaps extension provides the ability to store bitmaps
|
||||
related to a virtual disk. This section describes how these bitmaps are stored.
|
||||
|
||||
All stored bitmaps are related to the virtual disk stored in the same image, so
|
||||
each bitmap size is equal to the virtual disk size.
|
||||
|
||||
Each bit of the bitmap is responsible for strictly defined range of the virtual
|
||||
disk. For bit number bit_nr the corresponding range (in bytes) will be:
|
||||
|
||||
.. code::
|
||||
|
||||
[bit_nr * bitmap_granularity .. (bit_nr + 1) * bitmap_granularity - 1]
|
||||
|
||||
Granularity is a property of the concrete bitmap, see below.
|
||||
|
||||
|
||||
Bitmap directory
|
||||
----------------
|
||||
|
||||
Each bitmap saved in the image is described in a bitmap directory entry. The
|
||||
bitmap directory is a contiguous area in the image file, whose starting offset
|
||||
and length are given by the header extension fields ``bitmap_directory_offset`` and
|
||||
``bitmap_directory_size``. The entries of the bitmap directory have variable
|
||||
length, depending on the lengths of the bitmap name and extra data.
|
||||
|
||||
Structure of a bitmap directory entry::
|
||||
|
||||
Byte 0 - 7: bitmap_table_offset
|
||||
Offset into the image file at which the bitmap table
|
||||
(described below) for the bitmap starts. Must be aligned to
|
||||
a cluster boundary.
|
||||
|
||||
8 - 11: bitmap_table_size
|
||||
Number of entries in the bitmap table of the bitmap.
|
||||
|
||||
12 - 15: flags
|
||||
Bit
|
||||
0: in_use
|
||||
The bitmap was not saved correctly and may be
|
||||
inconsistent. Although the bitmap metadata is still
|
||||
well-formed from a qcow2 perspective, the metadata
|
||||
(such as the auto flag or bitmap size) or data
|
||||
contents may be outdated.
|
||||
|
||||
1: auto
|
||||
The bitmap must reflect all changes of the virtual
|
||||
disk by any application that would write to this qcow2
|
||||
file (including writes, snapshot switching, etc.). The
|
||||
type of this bitmap must be 'dirty tracking bitmap'.
|
||||
|
||||
2: extra_data_compatible
|
||||
This flags is meaningful when the extra data is
|
||||
unknown to the software (currently any extra data is
|
||||
unknown to QEMU).
|
||||
If it is set, the bitmap may be used as expected, extra
|
||||
data must be left as is.
|
||||
If it is not set, the bitmap must not be used, but
|
||||
both it and its extra data be left as is.
|
||||
|
||||
Bits 3 - 31 are reserved and must be 0.
|
||||
|
||||
16: type
|
||||
This field describes the sort of the bitmap.
|
||||
Values:
|
||||
1: Dirty tracking bitmap
|
||||
|
||||
Values 0, 2 - 255 are reserved.
|
||||
|
||||
17: granularity_bits
|
||||
Granularity bits. Valid values: 0 - 63.
|
||||
|
||||
Note: QEMU currently supports only values 9 - 31.
|
||||
|
||||
Granularity is calculated as
|
||||
granularity = 1 << granularity_bits
|
||||
|
||||
A bitmap's granularity is how many bytes of the image
|
||||
accounts for one bit of the bitmap.
|
||||
|
||||
18 - 19: name_size
|
||||
Size of the bitmap name. Must be non-zero.
|
||||
|
||||
Note: QEMU currently doesn't support values greater than
|
||||
1023.
|
||||
|
||||
20 - 23: extra_data_size
|
||||
Size of type-specific extra data.
|
||||
|
||||
For now, as no extra data is defined, extra_data_size is
|
||||
reserved and should be zero. If it is non-zero the
|
||||
behavior is defined by extra_data_compatible flag.
|
||||
|
||||
variable: extra_data
|
||||
Extra data for the bitmap, occupying extra_data_size bytes.
|
||||
Extra data must never contain references to clusters or in
|
||||
some other way allocate additional clusters.
|
||||
|
||||
variable: name
|
||||
The name of the bitmap (not null terminated), occupying
|
||||
name_size bytes. Must be unique among all bitmap names
|
||||
within the bitmaps extension.
|
||||
|
||||
variable: Padding to round up the bitmap directory entry size to the
|
||||
next multiple of 8. All bytes of the padding must be zero.
|
||||
|
||||
|
||||
Bitmap table
|
||||
------------
|
||||
|
||||
Each bitmap is stored using a one-level structure (as opposed to two-level
|
||||
structures like for refcounts and guest clusters mapping) for the mapping of
|
||||
bitmap data to host clusters. This structure is called the bitmap table.
|
||||
|
||||
Each bitmap table has a variable size (stored in the bitmap directory entry)
|
||||
and may use multiple clusters, however, it must be contiguous in the image
|
||||
file.
|
||||
|
||||
Structure of a bitmap table entry::
|
||||
|
||||
Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero.
|
||||
If bits 9 - 55 are zero:
|
||||
0: Cluster should be read as all zeros.
|
||||
1: Cluster should be read as all ones.
|
||||
|
||||
1 - 8: Reserved and must be zero.
|
||||
|
||||
9 - 55: Bits 9 - 55 of the host cluster offset. Must be aligned to
|
||||
a cluster boundary. If the offset is 0, the cluster is
|
||||
unallocated; in that case, bit 0 determines how this
|
||||
cluster should be treated during reads.
|
||||
|
||||
56 - 63: Reserved and must be zero.
|
||||
|
||||
|
||||
Bitmap data
|
||||
-----------
|
||||
|
||||
As noted above, bitmap data is stored in separate clusters, described by the
|
||||
bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
|
||||
the image file can be obtained as follows::
|
||||
|
||||
image_offset(bitmap_data_offset) =
|
||||
bitmap_table[bitmap_data_offset / cluster_size] +
|
||||
(bitmap_data_offset % cluster_size)
|
||||
|
||||
This offset is not defined if bits 9 - 55 of bitmap table entry are zero (see
|
||||
above).
|
||||
|
||||
Given an offset byte_nr into the virtual disk and the bitmap's granularity, the
|
||||
bit offset into the image file to the corresponding bit of the bitmap can be
|
||||
calculated like this::
|
||||
|
||||
bit_offset(byte_nr) =
|
||||
image_offset(byte_nr / granularity / 8) * 8 +
|
||||
(byte_nr / granularity) % 8
|
||||
|
||||
If the size of the bitmap data is not a multiple of the cluster size then the
|
||||
last cluster of the bitmap data contains some unused tail bits. These bits must
|
||||
be zero.
|
||||
|
||||
|
||||
Dirty tracking bitmaps
|
||||
----------------------
|
||||
|
||||
Bitmaps with ``type`` field equal to one are dirty tracking bitmaps.
|
||||
|
||||
When the virtual disk is in use dirty tracking bitmap may be ``enabled`` or
|
||||
``disabled``. While the bitmap is ``enabled``, all writes to the virtual disk
|
||||
should be reflected in the bitmap. A set bit in the bitmap means that the
|
||||
corresponding range of the virtual disk (see above) was written to while the
|
||||
bitmap was ``enabled``. An unset bit means that this range was not written to.
|
||||
|
||||
The software doesn't have to sync the bitmap in the image file with its
|
||||
representation in RAM after each write or metadata change. Flag ``in_use``
|
||||
should be set while the bitmap is not synced.
|
||||
|
||||
In the image file the ``enabled`` state is reflected by the ``auto`` flag. If this
|
||||
flag is set, the software must consider the bitmap as ``enabled`` and start
|
||||
tracking virtual disk changes to this bitmap from the first write to the
|
||||
virtual disk. If this flag is not set then the bitmap is disabled.
|
||||
@@ -0,0 +1,219 @@
|
||||
===================================
|
||||
QED Image File Format Specification
|
||||
===================================
|
||||
|
||||
The file format looks like this::
|
||||
|
||||
+----------+----------+----------+-----+
|
||||
| cluster0 | cluster1 | cluster2 | ... |
|
||||
+----------+----------+----------+-----+
|
||||
|
||||
The first cluster begins with the ``header``. The header contains information
|
||||
about where regular clusters start; this allows the header to be extensible and
|
||||
store extra information about the image file. A regular cluster may be
|
||||
a ``data cluster``, an ``L2``, or an ``L1 table``. L1 and L2 tables are composed
|
||||
of one or more contiguous clusters.
|
||||
|
||||
Normally the file size will be a multiple of the cluster size. If the file size
|
||||
is not a multiple, extra information after the last cluster may not be preserved
|
||||
if data is written. Legitimate extra information should use space between the header
|
||||
and the first regular cluster.
|
||||
|
||||
All fields are little-endian.
|
||||
|
||||
Header
|
||||
------
|
||||
|
||||
::
|
||||
|
||||
Header {
|
||||
uint32_t magic; /* QED\0 */
|
||||
|
||||
uint32_t cluster_size; /* in bytes */
|
||||
uint32_t table_size; /* for L1 and L2 tables, in clusters */
|
||||
uint32_t header_size; /* in clusters */
|
||||
|
||||
uint64_t features; /* format feature bits */
|
||||
uint64_t compat_features; /* compat feature bits */
|
||||
uint64_t autoclear_features; /* self-resetting feature bits */
|
||||
|
||||
uint64_t l1_table_offset; /* in bytes */
|
||||
uint64_t image_size; /* total logical image size, in bytes */
|
||||
|
||||
/* if (features & QED_F_BACKING_FILE) */
|
||||
uint32_t backing_filename_offset; /* in bytes from start of header */
|
||||
uint32_t backing_filename_size; /* in bytes */
|
||||
}
|
||||
|
||||
Field descriptions:
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``cluster_size`` must be a power of 2 in range [2^12, 2^26].
|
||||
- ``table_size`` must be a power of 2 in range [1, 16].
|
||||
- ``header_size`` is the number of clusters used by the header and any additional
|
||||
information stored before regular clusters.
|
||||
- ``features``, ``compat_features``, and ``autoclear_features`` are file format
|
||||
extension bitmaps. They work as follows:
|
||||
|
||||
- An image with unknown ``features`` bits enabled must not be opened. File format
|
||||
changes that are not backwards-compatible must use ``features`` bits.
|
||||
- An image with unknown ``compat_features`` bits enabled can be opened safely.
|
||||
The unknown features are simply ignored and represent backwards-compatible
|
||||
changes to the file format.
|
||||
- An image with unknown ``autoclear_features`` bits enable can be opened safely
|
||||
after clearing the unknown bits. This allows for backwards-compatible changes
|
||||
to the file format which degrade gracefully and can be re-enabled again by a
|
||||
new program later.
|
||||
- ``l1_table_offset`` is the offset of the first byte of the L1 table in the image
|
||||
file and must be a multiple of ``cluster_size``.
|
||||
- ``image_size`` is the block device size seen by the guest and must be a multiple
|
||||
of 512 bytes.
|
||||
- ``backing_filename_offset`` and ``backing_filename_size`` describe a string in
|
||||
(byte offset, byte size) form. It is not NUL-terminated and has no alignment constraints.
|
||||
The string must be stored within the first ``header_size`` clusters. The backing filename
|
||||
may be an absolute path or relative to the image file.
|
||||
|
||||
Feature bits:
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
- ``QED_F_BACKING_FILE = 0x01``. The image uses a backing file.
|
||||
- ``QED_F_NEED_CHECK = 0x02``. The image needs a consistency check before use.
|
||||
- ``QED_F_BACKING_FORMAT_NO_PROBE = 0x04``. The backing file is a raw disk image
|
||||
and no file format autodetection should be attempted. This should be used to
|
||||
ensure that raw backing files are never detected as an image format if they happen
|
||||
to contain magic constants.
|
||||
|
||||
There are currently no defined ``compat_features`` or ``autoclear_features`` bits.
|
||||
|
||||
Fields predicated on a feature bit are only used when that feature is set.
|
||||
The fields always take up header space, regardless of whether or not the feature
|
||||
bit is set.
|
||||
|
||||
Tables
|
||||
------
|
||||
|
||||
Tables provide the translation from logical offsets in the block device to cluster
|
||||
offsets in the file.
|
||||
|
||||
::
|
||||
|
||||
#define TABLE_NOFFSETS (table_size * cluster_size / sizeof(uint64_t))
|
||||
|
||||
Table {
|
||||
uint64_t offsets[TABLE_NOFFSETS];
|
||||
}
|
||||
|
||||
The tables are organized as follows::
|
||||
|
||||
+----------+
|
||||
| L1 table |
|
||||
+----------+
|
||||
,------' | '------.
|
||||
+----------+ | +----------+
|
||||
| L2 table | ... | L2 table |
|
||||
+----------+ +----------+
|
||||
,------' | '------.
|
||||
+----------+ | +----------+
|
||||
| Data | ... | Data |
|
||||
+----------+ +----------+
|
||||
|
||||
A table is made up of one or more contiguous clusters. The ``table_size`` header
|
||||
field determines table size for an image file. For example, ``cluster_size=64 KB``
|
||||
and ``table_size=4`` results in 256 KB tables.
|
||||
|
||||
The logical image size must be less than or equal to the maximum possible size of
|
||||
clusters rooted by the L1 table:
|
||||
|
||||
.. code::
|
||||
|
||||
header.image_size <= TABLE_NOFFSETS * TABLE_NOFFSETS * header.cluster_size
|
||||
|
||||
L1, L2, and data cluster offsets must be aligned to ``header.cluster_size``.
|
||||
The following offsets have special meanings:
|
||||
|
||||
L2 table offsets
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
- 0 - unallocated. The L2 table is not yet allocated.
|
||||
|
||||
Data cluster offsets
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- 0 - unallocated. The data cluster is not yet allocated.
|
||||
- 1 - zero. The data cluster contents are all zeroes and no cluster is allocated.
|
||||
|
||||
Future format extensions may wish to store per-offset information. The least
|
||||
significant 12 bits of an offset are reserved for this purpose and must be set
|
||||
to zero. Image files with ``cluster_size`` > 2^12 will have more unused bits
|
||||
which should also be zeroed.
|
||||
|
||||
Unallocated L2 tables and data clusters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Reads to an unallocated area of the image file access the backing file. If there
|
||||
is no backing file, then zeroes are produced. The backing file may be smaller
|
||||
than the image file and reads of unallocated areas beyond the end of the backing
|
||||
file produce zeroes.
|
||||
|
||||
Writes to an unallocated area cause a new data clusters to be allocated, and a new
|
||||
L2 table if that is also unallocated. The new data cluster is populated with data
|
||||
from the backing file (or zeroes if no backing file) and the data being written.
|
||||
|
||||
Zero data clusters
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Zero data clusters are a space-efficient way of storing zeroed regions of the image.
|
||||
|
||||
Reads to a zero data cluster produce zeroes.
|
||||
|
||||
.. note::
|
||||
The difference between an unallocated and a zero data cluster is that zero data
|
||||
clusters stop the reading of contents from the backing file.
|
||||
|
||||
Writes to a zero data cluster cause a new data cluster to be allocated. The new
|
||||
data cluster is populated with zeroes and the data being written.
|
||||
|
||||
Logical offset translation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Logical offsets are translated into cluster offsets as follows::
|
||||
|
||||
table_bits table_bits cluster_bits
|
||||
<--------> <--------> <--------------->
|
||||
+----------+----------+-----------------+
|
||||
| L1 index | L2 index | byte offset |
|
||||
+----------+----------+-----------------+
|
||||
|
||||
Structure of a logical offset
|
||||
|
||||
offset_mask = ~(cluster_size - 1) # mask for the image file byte offset
|
||||
|
||||
def logical_to_cluster_offset(l1_index, l2_index, byte_offset):
|
||||
l2_offset = l1_table[l1_index]
|
||||
l2_table = load_table(l2_offset)
|
||||
cluster_offset = l2_table[l2_index] & offset_mask
|
||||
return cluster_offset + byte_offset
|
||||
|
||||
Consistency checking
|
||||
--------------------
|
||||
|
||||
This section is informational and included to provide background on the use
|
||||
of the ``QED_F_NEED_CHECK features`` bit.
|
||||
|
||||
The ``QED_F_NEED_CHECK`` bit is used to mark an image as dirty before starting
|
||||
an operation that could leave the image in an inconsistent state if interrupted
|
||||
by a crash or power failure. A dirty image must be checked on open because its
|
||||
metadata may not be consistent.
|
||||
|
||||
Consistency check includes the following invariants:
|
||||
|
||||
- Each cluster is referenced once and only once. It is an inconsistency to have
|
||||
a cluster referenced more than once by L1 or L2 tables. A cluster has been leaked
|
||||
if it has no references.
|
||||
- Offsets must be within the image file size and must be ``cluster_size`` aligned.
|
||||
- Table offsets must at least ``table_size`` * ``cluster_size`` bytes from the end
|
||||
of the image file so that there is space for the entire table.
|
||||
|
||||
The consistency check process starts from ``l1_table_offset`` and scans all L2 tables.
|
||||
After the check completes with no other errors besides leaks, the ``QED_F_NEED_CHECK``
|
||||
bit can be cleared and the image can be accessed.
|
||||
@@ -0,0 +1,5 @@
|
||||
QEMU Guest Agent Protocol Reference
|
||||
===================================
|
||||
|
||||
.. qapi-doc:: qga/qapi-schema.json
|
||||
:namespace: QGA
|
||||
@@ -0,0 +1,161 @@
|
||||
.. _qemu-ga:
|
||||
|
||||
QEMU Guest Agent
|
||||
================
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
**qemu-ga** [*OPTIONS*]
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
The QEMU Guest Agent is a daemon intended to be run within virtual
|
||||
machines. It allows the hypervisor host to perform various operations
|
||||
in the guest, such as:
|
||||
|
||||
- get information from the guest
|
||||
- set the guest's system time
|
||||
- read/write a file
|
||||
- sync and freeze the filesystems
|
||||
- suspend the guest
|
||||
- reconfigure guest local processors
|
||||
- set user's password
|
||||
- ...
|
||||
|
||||
qemu-ga will read a system configuration file on startup (located at
|
||||
|CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
|
||||
configuration options on the command line. For the same key, the last
|
||||
option wins, but the lists accumulate (see below for configuration
|
||||
file format).
|
||||
|
||||
If an allowed RPCs list is defined in the configuration, then all
|
||||
RPCs will be blocked by default, except for the allowed list.
|
||||
|
||||
If a blocked RPCs list is defined in the configuration, then all
|
||||
RPCs will be allowed by default, except for the blocked list.
|
||||
|
||||
If both allowed and blocked RPCs lists are defined in the configuration,
|
||||
then all RPCs will be blocked by default, then the allowed list will
|
||||
be applied, followed by the blocked list.
|
||||
|
||||
While filesystems are frozen, all except for a designated safe set
|
||||
of RPCs will blocked, regardless of what the general configuration
|
||||
declares.
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. program:: qemu-ga
|
||||
|
||||
.. option:: -c, --config=PATH
|
||||
|
||||
Configuration file path (the default is |CONFDIR|\ ``/qemu-ga.conf``,
|
||||
unless overridden by the QGA_CONF environment variable)
|
||||
|
||||
.. option:: -m, --method=METHOD
|
||||
|
||||
Transport method: one of ``unix-listen``, ``virtio-serial``, or
|
||||
``isa-serial``, or ``vsock-listen`` (``virtio-serial`` is the default).
|
||||
|
||||
.. option:: -p, --path=PATH
|
||||
|
||||
Device/socket path (the default for virtio-serial is
|
||||
``/dev/virtio-ports/org.qemu.guest_agent.0``,
|
||||
the default for isa-serial is ``/dev/ttyS0``). Socket addresses for
|
||||
vsock-listen are written as ``<cid>:<port>``.
|
||||
|
||||
.. option:: -l, --logfile=PATH
|
||||
|
||||
Set log file path (default is stderr).
|
||||
|
||||
.. option:: -f, --pidfile=PATH
|
||||
|
||||
Specify pid file (default is ``/var/run/qemu-ga.pid``).
|
||||
|
||||
.. option:: -F, --fsfreeze-hook=PATH
|
||||
|
||||
Enable fsfreeze hook. Accepts an optional argument that specifies
|
||||
script to run on freeze/thaw. Script will be called with
|
||||
'freeze'/'thaw' arguments accordingly (default is
|
||||
|CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
|
||||
not follow -F with a space (for example:
|
||||
``-F/var/run/fsfreezehook.sh``).
|
||||
|
||||
.. option:: -t, --statedir=PATH
|
||||
|
||||
Specify the directory to store state information (absolute paths only,
|
||||
default is ``/var/run``).
|
||||
|
||||
.. option:: -v, --verbose
|
||||
|
||||
Log extra debugging information.
|
||||
|
||||
.. option:: -V, --version
|
||||
|
||||
Print version information and exit.
|
||||
|
||||
.. option:: -d, --daemon
|
||||
|
||||
Daemonize after startup (detach from terminal).
|
||||
|
||||
.. option:: -b, --block-rpcs=LIST
|
||||
|
||||
Comma-separated list of RPCs to disable (no spaces, use ``--block-rpcs=help``
|
||||
to list available RPCs).
|
||||
|
||||
.. option:: -a, --allow-rpcs=LIST
|
||||
|
||||
Comma-separated list of RPCs to enable (no spaces, use ``--allow-rpcs=help``
|
||||
to list available RPCs).
|
||||
|
||||
.. option:: -D, --dump-conf
|
||||
|
||||
Dump the configuration in a format compatible with ``qemu-ga.conf``
|
||||
and exit.
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Display this help and exit.
|
||||
|
||||
Files
|
||||
-----
|
||||
|
||||
|
||||
The syntax of the ``qemu-ga.conf`` configuration file follows the
|
||||
Desktop Entry Specification, here is a quick summary: it consists of
|
||||
groups of key-value pairs, interspersed with comments.
|
||||
|
||||
::
|
||||
|
||||
# qemu-ga configuration sample
|
||||
[general]
|
||||
daemonize = 0
|
||||
pidfile = /var/run/qemu-ga.pid
|
||||
verbose = 0
|
||||
method = virtio-serial
|
||||
path = /dev/virtio-ports/org.qemu.guest_agent.0
|
||||
statedir = /var/run
|
||||
|
||||
The list of keys follows the command line options:
|
||||
|
||||
============= ===========
|
||||
Key Key type
|
||||
============= ===========
|
||||
daemon boolean
|
||||
method string
|
||||
path string
|
||||
logfile string
|
||||
pidfile string
|
||||
fsfreeze-hook string
|
||||
statedir string
|
||||
verbose boolean
|
||||
block-rpcs string list
|
||||
allow-rpcs string list
|
||||
============= ===========
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
:manpage:`qemu(1)`
|
||||
@@ -0,0 +1,10 @@
|
||||
.. _QMP Ref:
|
||||
|
||||
QEMU QMP Reference Manual
|
||||
=========================
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. qapi-doc:: qapi/qapi-schema.json
|
||||
:namespace: QMP
|
||||
@@ -0,0 +1,8 @@
|
||||
QEMU Storage Daemon QMP Reference Manual
|
||||
========================================
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
|
||||
:namespace: QSD
|
||||
@@ -0,0 +1,439 @@
|
||||
..
|
||||
Copyright (C) 2009-2016 Red Hat, Inc.
|
||||
|
||||
This work is licensed under the terms of the GNU GPL, version 2 or
|
||||
later. See the COPYING file in the top-level directory.
|
||||
|
||||
|
||||
===================================
|
||||
QEMU Machine Protocol Specification
|
||||
===================================
|
||||
|
||||
The QEMU Machine Protocol (QMP) is a JSON-based
|
||||
protocol which is available for applications to operate QEMU at the
|
||||
machine-level. It is also in use by the QEMU Guest Agent (QGA), which
|
||||
is available for host applications to interact with the guest
|
||||
operating system. This page specifies the general format of
|
||||
the protocol; details of the commands and data structures can
|
||||
be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`.
|
||||
|
||||
.. contents::
|
||||
|
||||
Protocol Specification
|
||||
======================
|
||||
|
||||
This section details the protocol format. For the purpose of this
|
||||
document, "Server" is either QEMU or the QEMU Guest Agent, and
|
||||
"Client" is any application communicating with it via QMP.
|
||||
|
||||
JSON data structures, when mentioned in this document, are always in the
|
||||
following format:
|
||||
|
||||
json-DATA-STRUCTURE-NAME
|
||||
|
||||
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
|
||||
by the `JSON standard <http://www.ietf.org/rfc/rfc8259.txt>`_.
|
||||
|
||||
The server expects its input to be encoded in UTF-8, and sends its
|
||||
output encoded in ASCII.
|
||||
|
||||
For convenience, json-object members mentioned in this document will
|
||||
be in a certain order. However, in real protocol usage they can be in
|
||||
ANY order, thus no particular order should be assumed. On the other
|
||||
hand, use of json-array elements presumes that preserving order is
|
||||
important unless specifically documented otherwise. Repeating a key
|
||||
within a json-object gives unpredictable results.
|
||||
|
||||
Also for convenience, the server will accept an extension of
|
||||
``'single-quoted'`` strings in place of the usual ``"double-quoted"``
|
||||
json-string, and both input forms of strings understand an additional
|
||||
escape sequence of ``\'`` for a single quote. The server will only use
|
||||
double quoting on output.
|
||||
|
||||
General Definitions
|
||||
-------------------
|
||||
|
||||
All interactions transmitted by the Server are json-objects, always
|
||||
terminating with CRLF.
|
||||
|
||||
All json-objects members are mandatory when not specified otherwise.
|
||||
|
||||
Server Greeting
|
||||
---------------
|
||||
|
||||
Right when connected the Server will issue a greeting message, which signals
|
||||
that the connection has been successfully established and that the Server is
|
||||
ready for capabilities negotiation (for more information refer to section
|
||||
`Capabilities Negotiation`_).
|
||||
|
||||
The greeting message format is:
|
||||
|
||||
::
|
||||
|
||||
{ "QMP": { "version": json-object, "capabilities": json-array } }
|
||||
|
||||
Where:
|
||||
|
||||
- The ``version`` member contains the Server's version information (the format
|
||||
is the same as for the query-version command).
|
||||
- The ``capabilities`` member specifies the availability of features beyond the
|
||||
baseline specification; the order of elements in this array has no
|
||||
particular significance.
|
||||
|
||||
Capabilities
|
||||
------------
|
||||
|
||||
Currently supported capabilities are:
|
||||
|
||||
``oob``
|
||||
the QMP server supports "out-of-band" (OOB) command
|
||||
execution, as described in section `Out-of-band execution`_.
|
||||
|
||||
Issuing Commands
|
||||
----------------
|
||||
|
||||
The format for command execution is:
|
||||
|
||||
::
|
||||
|
||||
{ "execute": json-string, "arguments": json-object, "id": json-value }
|
||||
|
||||
or
|
||||
|
||||
::
|
||||
|
||||
{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
|
||||
|
||||
Where:
|
||||
|
||||
- The ``execute`` or ``exec-oob`` member identifies the command to be
|
||||
executed by the server. The latter requests out-of-band execution.
|
||||
- The ``arguments`` member is used to pass any arguments required for the
|
||||
execution of the command, it is optional when no arguments are
|
||||
required. Each command documents what contents will be considered
|
||||
valid when handling the json-argument.
|
||||
- The ``id`` member is a transaction identification associated with the
|
||||
command execution, it is optional and will be part of the response
|
||||
if provided. The ``id`` member can be any json-value. A json-number
|
||||
incremented for each successive command works fine.
|
||||
|
||||
The actual commands are documented in the :doc:`qemu-qmp-ref`.
|
||||
|
||||
Out-of-band execution
|
||||
---------------------
|
||||
|
||||
The server normally reads, executes and responds to one command after
|
||||
the other. The client therefore receives command responses in issue
|
||||
order.
|
||||
|
||||
With out-of-band execution enabled via `capabilities negotiation`_,
|
||||
the server reads and queues commands as they arrive. It executes
|
||||
commands from the queue one after the other. Commands executed
|
||||
out-of-band jump the queue: the command get executed right away,
|
||||
possibly overtaking prior in-band commands. The client may therefore
|
||||
receive such a command's response before responses from prior in-band
|
||||
commands.
|
||||
|
||||
To be able to match responses back to their commands, the client needs
|
||||
to pass ``id`` with out-of-band commands. Passing it with all commands
|
||||
is recommended for clients that accept capability ``oob``.
|
||||
|
||||
If the client sends in-band commands faster than the server can
|
||||
execute them, the server will stop reading requests until the request
|
||||
queue length is reduced to an acceptable range.
|
||||
|
||||
To ensure commands to be executed out-of-band get read and executed,
|
||||
the client should have at most eight in-band commands in flight.
|
||||
|
||||
Only a few commands support out-of-band execution. The ones that do
|
||||
have ``"allow-oob": true`` in the output of ``query-qmp-schema``.
|
||||
|
||||
Commands Responses
|
||||
------------------
|
||||
|
||||
There are two possible responses which the Server will issue as the result
|
||||
of a command execution: success or error.
|
||||
|
||||
As long as the commands were issued with a proper ``id`` field, then the
|
||||
same ``id`` field will be attached in the corresponding response message
|
||||
so that requests and responses can match. Clients should drop all the
|
||||
responses that have an unknown ``id`` field.
|
||||
|
||||
Success
|
||||
-------
|
||||
|
||||
The format of a success response is:
|
||||
|
||||
::
|
||||
|
||||
{ "return": json-value, "id": json-value }
|
||||
|
||||
Where:
|
||||
|
||||
- The ``return`` member contains the data returned by the command, which
|
||||
is defined on a per-command basis (usually a json-object or
|
||||
json-array of json-objects, but sometimes a json-number, json-string,
|
||||
or json-array of json-strings); it is an empty json-object if the
|
||||
command does not return data.
|
||||
- The ``id`` member contains the transaction identification associated
|
||||
with the command execution if issued by the Client.
|
||||
|
||||
Error
|
||||
-----
|
||||
|
||||
The format of an error response is:
|
||||
|
||||
::
|
||||
|
||||
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
|
||||
|
||||
Where:
|
||||
|
||||
- The ``class`` member contains the error class name (eg. ``"GenericError"``).
|
||||
- The ``desc`` member is a human-readable error message. Clients should
|
||||
not attempt to parse this message.
|
||||
- The ``id`` member contains the transaction identification associated with
|
||||
the command execution if issued by the Client.
|
||||
|
||||
NOTE: Some errors can occur before the Server is able to read the ``id`` member;
|
||||
in these cases the ``id`` member will not be part of the error response, even
|
||||
if provided by the client.
|
||||
|
||||
Asynchronous events
|
||||
-------------------
|
||||
|
||||
As a result of state changes, the Server may send messages unilaterally
|
||||
to the Client at any time, when not in the middle of any other
|
||||
response. They are called "asynchronous events".
|
||||
|
||||
The format of asynchronous events is:
|
||||
|
||||
::
|
||||
|
||||
{ "event": json-string, "data": json-object,
|
||||
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
||||
|
||||
Where:
|
||||
|
||||
- The ``event`` member contains the event's name.
|
||||
- The ``data`` member contains event specific data, which is defined in a
|
||||
per-event basis. It is optional.
|
||||
- The ``timestamp`` member contains the exact time of when the event
|
||||
occurred in the Server. It is a fixed json-object with time in
|
||||
seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
|
||||
there is a failure to retrieve host time, both members of the
|
||||
timestamp will be set to -1.
|
||||
|
||||
The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`.
|
||||
|
||||
Some events are rate-limited to at most one per second. If additional
|
||||
"similar" events arrive within one second, all but the last one are
|
||||
dropped, and the last one is delayed. "Similar" normally means same
|
||||
event type.
|
||||
|
||||
Forcing the JSON parser into known-good state
|
||||
---------------------------------------------
|
||||
|
||||
Incomplete or invalid input can leave the server's JSON parser in a
|
||||
state where it can't parse additional commands. To get it back into
|
||||
known-good state, the client should provoke a lexical error.
|
||||
|
||||
The cleanest way to do that is sending an ASCII control character
|
||||
other than ``\t`` (horizontal tab), ``\r`` (carriage return), or
|
||||
``\n`` (new line).
|
||||
|
||||
Sadly, older versions of QEMU can fail to flag this as an error. If a
|
||||
client needs to deal with them, it should send a 0xFF byte.
|
||||
|
||||
QGA Synchronization
|
||||
-------------------
|
||||
|
||||
When a client connects to QGA over a transport lacking proper
|
||||
connection semantics such as virtio-serial, QGA may have read partial
|
||||
input from a previous client. The client needs to force QGA's parser
|
||||
into known-good state using the previous section's technique.
|
||||
Moreover, the client may receive output a previous client didn't read.
|
||||
To help with skipping that output, QGA provides the
|
||||
``guest-sync-delimited`` command. Refer to its documentation for
|
||||
details.
|
||||
|
||||
|
||||
QMP Examples
|
||||
============
|
||||
|
||||
This section provides some examples of real QMP usage, in all of them
|
||||
``->`` marks text sent by the Client and ``<-`` marks replies by the Server.
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Server greeting
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
<- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
|
||||
"package": "v3.0.0"}, "capabilities": ["oob"] } }
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Capabilities negotiation
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
|
||||
<- { "return": {}}
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Simple 'stop' execution
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "stop" }
|
||||
<- { "return": {} }
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
KVM information
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "query-kvm", "id": "example" }
|
||||
<- { "return": { "enabled": true, "present": true }, "id": "example"}
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Parsing error
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": }
|
||||
<- { "error": { "class": "GenericError", "desc": "JSON parse error, expecting value" } }
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Powerdown event
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
<- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
|
||||
"event": "POWERDOWN" }
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
Out-of-band execution
|
||||
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "exec-oob": "migrate-pause", "id": 42 }
|
||||
<- { "id": 42,
|
||||
"error": { "class": "GenericError",
|
||||
"desc": "migrate-pause is currently only supported during postcopy-active state" } }
|
||||
|
||||
|
||||
Capabilities Negotiation
|
||||
========================
|
||||
|
||||
When a Client successfully establishes a connection, the Server is in
|
||||
Capabilities Negotiation mode.
|
||||
|
||||
In this mode only the ``qmp_capabilities`` command is allowed to run; all
|
||||
other commands will return the ``CommandNotFound`` error. Asynchronous
|
||||
messages are not delivered either.
|
||||
|
||||
Clients should use the ``qmp_capabilities`` command to enable capabilities
|
||||
advertised in the `Server Greeting`_ which they support.
|
||||
|
||||
When the ``qmp_capabilities`` command is issued, and if it does not return an
|
||||
error, the Server enters Command mode where capabilities changes take
|
||||
effect, all commands (except ``qmp_capabilities``) are allowed and asynchronous
|
||||
messages are delivered.
|
||||
|
||||
Compatibility Considerations
|
||||
============================
|
||||
|
||||
All protocol changes or new features which modify the protocol format in an
|
||||
incompatible way are disabled by default and will be advertised by the
|
||||
capabilities array (in the `Server Greeting`_). Thus, Clients can check
|
||||
that array and enable the capabilities they support.
|
||||
|
||||
The QMP Server performs a type check on the arguments to a command. It
|
||||
generates an error if a value does not have the expected type for its
|
||||
key, or if it does not understand a key that the Client included. The
|
||||
strictness of the Server catches wrong assumptions of Clients about
|
||||
the Server's schema. Clients can assume that, when such validation
|
||||
errors occur, they will be reported before the command generated any
|
||||
side effect.
|
||||
|
||||
However, Clients must not assume any particular:
|
||||
|
||||
- Length of json-arrays
|
||||
- Size of json-objects; in particular, future versions of QEMU may add
|
||||
new keys and Clients should be able to ignore them
|
||||
- Order of json-object members or json-array elements
|
||||
- Amount of errors generated by a command, that is, new errors can be added
|
||||
to any existing command in newer versions of the Server
|
||||
|
||||
Any command or member name beginning with ``x-`` is deemed experimental,
|
||||
and may be withdrawn or changed in an incompatible manner in a future
|
||||
release.
|
||||
|
||||
Of course, the Server does guarantee to send valid JSON. But apart from
|
||||
this, a Client should be "conservative in what they send, and liberal in
|
||||
what they accept".
|
||||
|
||||
Downstream extension of QMP
|
||||
===========================
|
||||
|
||||
We recommend that downstream consumers of QEMU do *not* modify QMP.
|
||||
Management tools should be able to support both upstream and downstream
|
||||
versions of QMP without special logic, and downstream extensions are
|
||||
inherently at odds with that.
|
||||
|
||||
However, we recognize that it is sometimes impossible for downstreams to
|
||||
avoid modifying QMP. Both upstream and downstream need to take care to
|
||||
preserve long-term compatibility and interoperability.
|
||||
|
||||
To help with that, QMP reserves JSON object member names beginning with
|
||||
``__`` (double underscore) for downstream use ("downstream names"). This
|
||||
means upstream will never use any downstream names for its commands,
|
||||
arguments, errors, asynchronous events, and so forth.
|
||||
|
||||
Any new names downstream wishes to add must begin with ``__``. To
|
||||
ensure compatibility with other downstreams, it is strongly
|
||||
recommended that you prefix your downstream names with ``__RFQDN_`` where
|
||||
RFQDN is a valid, reverse fully qualified domain name which you
|
||||
control. For example, a qemu-kvm specific monitor command would be:
|
||||
|
||||
::
|
||||
|
||||
(qemu) __org.linux-kvm_enable_irqchip
|
||||
|
||||
Downstream must not change the `server greeting`_ other than
|
||||
to offer additional capabilities. But see below for why even that is
|
||||
discouraged.
|
||||
|
||||
The section `Compatibility Considerations`_ applies to downstream as well
|
||||
as to upstream, obviously. It follows that downstream must behave
|
||||
exactly like upstream for any input not containing members with
|
||||
downstream names ("downstream members"), except it may add members
|
||||
with downstream names to its output.
|
||||
|
||||
Thus, a client should not be able to distinguish downstream from
|
||||
upstream as long as it doesn't send input with downstream members, and
|
||||
properly ignores any downstream members in the output it receives.
|
||||
|
||||
Advice on downstream modifications:
|
||||
|
||||
1. Introducing new commands is okay. If you want to extend an existing
|
||||
command, consider introducing a new one with the new behaviour
|
||||
instead.
|
||||
|
||||
2. Introducing new asynchronous messages is okay. If you want to extend
|
||||
an existing message, consider adding a new one instead.
|
||||
|
||||
3. Introducing new errors for use in new commands is okay. Adding new
|
||||
errors to existing commands counts as extension, so 1. applies.
|
||||
|
||||
4. New capabilities are strongly discouraged. Capabilities are for
|
||||
evolving the basic protocol, and multiple diverging basic protocol
|
||||
dialects are most undesirable.
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,289 @@
|
||||
=======================
|
||||
Vhost-user-gpu Protocol
|
||||
=======================
|
||||
|
||||
..
|
||||
Licence: This work is licensed under the terms of the GNU GPL,
|
||||
version 2 or later. See the COPYING file in the top-level
|
||||
directory.
|
||||
|
||||
.. contents:: Table of Contents
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The vhost-user-gpu protocol is aiming at sharing the rendering result
|
||||
of a virtio-gpu, done from a vhost-user back-end process to a vhost-user
|
||||
front-end process (such as QEMU). It bears a resemblance to a display
|
||||
server protocol, if you consider QEMU as the display server and the
|
||||
back-end as the client, but in a very limited way. Typically, it will
|
||||
work by setting a scanout/display configuration, before sending flush
|
||||
events for the display updates. It will also update the cursor shape
|
||||
and position.
|
||||
|
||||
The protocol is sent over a UNIX domain stream socket, since it uses
|
||||
socket ancillary data to share opened file descriptors (DMABUF fds or
|
||||
shared memory). The socket is usually obtained via
|
||||
``VHOST_USER_GPU_SET_SOCKET``.
|
||||
|
||||
Requests are sent by the *back-end*, and the optional replies by the
|
||||
*front-end*.
|
||||
|
||||
Wire format
|
||||
===========
|
||||
|
||||
Unless specified differently, numbers are in the machine native byte
|
||||
order.
|
||||
|
||||
A vhost-user-gpu message (request and reply) consists of 3 header
|
||||
fields and a payload.
|
||||
|
||||
+---------+-------+------+---------+
|
||||
| request | flags | size | payload |
|
||||
+---------+-------+------+---------+
|
||||
|
||||
Header
|
||||
------
|
||||
|
||||
:request: ``u32``, type of the request
|
||||
|
||||
:flags: ``u32``, 32-bit bit field:
|
||||
|
||||
- Bit 2 is the reply flag - needs to be set on each reply
|
||||
|
||||
:size: ``u32``, size of the payload
|
||||
|
||||
Payload types
|
||||
-------------
|
||||
|
||||
Depending on the request type, **payload** can be:
|
||||
|
||||
VhostUserGpuCursorPos
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+------------+---+---+
|
||||
| scanout-id | x | y |
|
||||
+------------+---+---+
|
||||
|
||||
:scanout-id: ``u32``, the scanout where the cursor is located
|
||||
|
||||
:x/y: ``u32``, the cursor position
|
||||
|
||||
VhostUserGpuCursorUpdate
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+-----+-------+-------+--------+
|
||||
| pos | hot_x | hot_y | cursor |
|
||||
+-----+-------+-------+--------+
|
||||
|
||||
:pos: a ``VhostUserGpuCursorPos``, the cursor location
|
||||
|
||||
:hot_x/hot_y: ``u32``, the cursor hot location
|
||||
|
||||
:cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format)
|
||||
|
||||
VhostUserGpuScanout
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+------------+---+---+
|
||||
| scanout-id | w | h |
|
||||
+------------+---+---+
|
||||
|
||||
:scanout-id: ``u32``, the scanout configuration to set
|
||||
|
||||
:w/h: ``u32``, the scanout width/height size
|
||||
|
||||
VhostUserGpuUpdate
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+------------+---+---+---+---+------+
|
||||
| scanout-id | x | y | w | h | data |
|
||||
+------------+---+---+---+---+------+
|
||||
|
||||
:scanout-id: ``u32``, the scanout content to update
|
||||
|
||||
:x/y/w/h: ``u32``, region of the update
|
||||
|
||||
:data: RGB data (PIXMAN_x8r8g8b8 format)
|
||||
|
||||
VhostUserGpuDMABUFScanout
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+------------+---+---+---+---+-----+-----+--------+-------+--------+
|
||||
| scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
|
||||
+------------+---+---+---+---+-----+-----+--------+-------+--------+
|
||||
|
||||
:scanout-id: ``u32``, the scanout configuration to set
|
||||
|
||||
:x/y: ``u32``, the location of the scanout within the DMABUF
|
||||
|
||||
:w/h: ``u32``, the scanout width/height size
|
||||
|
||||
:fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags
|
||||
|
||||
:fourcc: ``i32``, the DMABUF fourcc
|
||||
|
||||
|
||||
VhostUserGpuEdidRequest
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+------------+
|
||||
| scanout-id |
|
||||
+------------+
|
||||
|
||||
:scanout-id: ``u32``, the scanout to get edid from
|
||||
|
||||
|
||||
VhostUserGpuDMABUFScanout2
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
+----------------+----------+
|
||||
| dmabuf_scanout | modifier |
|
||||
+----------------+----------+
|
||||
|
||||
:dmabuf_scanout: ``VhostUserGpuDMABUFScanout``, filled as described in the
|
||||
VhostUserGpuDMABUFScanout structure.
|
||||
|
||||
:modifier: ``u64``, the DMABUF modifiers
|
||||
|
||||
|
||||
C structure
|
||||
-----------
|
||||
|
||||
In QEMU the vhost-user-gpu message is implemented with the following struct:
|
||||
|
||||
.. code:: c
|
||||
|
||||
typedef struct VhostUserGpuMsg {
|
||||
uint32_t request; /* VhostUserGpuRequest */
|
||||
uint32_t flags;
|
||||
uint32_t size; /* the following payload size */
|
||||
union {
|
||||
VhostUserGpuCursorPos cursor_pos;
|
||||
VhostUserGpuCursorUpdate cursor_update;
|
||||
VhostUserGpuScanout scanout;
|
||||
VhostUserGpuUpdate update;
|
||||
VhostUserGpuDMABUFScanout dmabuf_scanout;
|
||||
VhostUserGpuEdidRequest edid_req;
|
||||
struct virtio_gpu_resp_edid resp_edid;
|
||||
struct virtio_gpu_resp_display_info display_info;
|
||||
uint64_t u64;
|
||||
} payload;
|
||||
} QEMU_PACKED VhostUserGpuMsg;
|
||||
|
||||
Protocol features
|
||||
-----------------
|
||||
|
||||
.. code:: c
|
||||
|
||||
#define VHOST_USER_GPU_PROTOCOL_F_EDID 0
|
||||
#define VHOST_USER_GPU_PROTOCOL_F_DMABUF2 1
|
||||
|
||||
New messages and communication changes are negotiated thanks to the
|
||||
``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
|
||||
``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
|
||||
|
||||
Communication
|
||||
=============
|
||||
|
||||
Message types
|
||||
-------------
|
||||
|
||||
``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
|
||||
:id: 1
|
||||
:request payload: N/A
|
||||
:reply payload: ``u64``
|
||||
|
||||
Get the supported protocol features bitmask.
|
||||
|
||||
``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
|
||||
:id: 2
|
||||
:request payload: ``u64``
|
||||
:reply payload: N/A
|
||||
|
||||
Enable protocol features using a bitmask.
|
||||
|
||||
``VHOST_USER_GPU_GET_DISPLAY_INFO``
|
||||
:id: 3
|
||||
:request payload: N/A
|
||||
:reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification)
|
||||
|
||||
Get the preferred display configuration.
|
||||
|
||||
``VHOST_USER_GPU_CURSOR_POS``
|
||||
:id: 4
|
||||
:request payload: ``VhostUserGpuCursorPos``
|
||||
:reply payload: N/A
|
||||
|
||||
Set/show the cursor position.
|
||||
|
||||
``VHOST_USER_GPU_CURSOR_POS_HIDE``
|
||||
:id: 5
|
||||
:request payload: ``VhostUserGpuCursorPos``
|
||||
:reply payload: N/A
|
||||
|
||||
Set/hide the cursor.
|
||||
|
||||
``VHOST_USER_GPU_CURSOR_UPDATE``
|
||||
:id: 6
|
||||
:request payload: ``VhostUserGpuCursorUpdate``
|
||||
:reply payload: N/A
|
||||
|
||||
Update the cursor shape and location.
|
||||
|
||||
``VHOST_USER_GPU_SCANOUT``
|
||||
:id: 7
|
||||
:request payload: ``VhostUserGpuScanout``
|
||||
:reply payload: N/A
|
||||
|
||||
Set the scanout resolution. To disable a scanout, the dimensions
|
||||
width/height are set to 0.
|
||||
|
||||
``VHOST_USER_GPU_UPDATE``
|
||||
:id: 8
|
||||
:request payload: ``VhostUserGpuUpdate``
|
||||
:reply payload: N/A
|
||||
|
||||
Update the scanout content. The data payload contains the graphical bits.
|
||||
The display should be flushed and presented.
|
||||
|
||||
``VHOST_USER_GPU_DMABUF_SCANOUT``
|
||||
:id: 9
|
||||
:request payload: ``VhostUserGpuDMABUFScanout``
|
||||
:reply payload: N/A
|
||||
|
||||
Set the scanout resolution/configuration, and share a DMABUF file
|
||||
descriptor for the scanout content, which is passed as ancillary
|
||||
data. To disable a scanout, the dimensions width/height are set
|
||||
to 0, there is no file descriptor passed.
|
||||
|
||||
``VHOST_USER_GPU_DMABUF_UPDATE``
|
||||
:id: 10
|
||||
:request payload: ``VhostUserGpuUpdate``
|
||||
:reply payload: empty payload
|
||||
|
||||
The display should be flushed and presented according to updated
|
||||
region from ``VhostUserGpuUpdate``.
|
||||
|
||||
Note: there is no data payload, since the scanout is shared thanks
|
||||
to DMABUF, that must have been set previously with
|
||||
``VHOST_USER_GPU_DMABUF_SCANOUT``.
|
||||
|
||||
``VHOST_USER_GPU_GET_EDID``
|
||||
:id: 11
|
||||
:request payload: ``struct VhostUserGpuEdidRequest``
|
||||
:reply payload: ``struct virtio_gpu_resp_edid`` (from virtio specification)
|
||||
|
||||
Retrieve the EDID data for a given scanout.
|
||||
This message requires the ``VHOST_USER_GPU_PROTOCOL_F_EDID`` protocol
|
||||
feature to be supported.
|
||||
|
||||
``VHOST_USER_GPU_DMABUF_SCANOUT2``
|
||||
:id: 12
|
||||
:request payload: ``VhostUserGpuDMABUFScanout2``
|
||||
:reply payload: N/A
|
||||
|
||||
Same as VHOST_USER_GPU_DMABUF_SCANOUT, but also sends the dmabuf modifiers
|
||||
appended to the message, which were not provided in the other message.
|
||||
This message requires the ``VHOST_USER_GPU_PROTOCOL_F_DMABUF2`` protocol
|
||||
feature to be supported.
|
||||
@@ -0,0 +1,290 @@
|
||||
# -*- Mode: Python -*-
|
||||
# vim: filetype=python
|
||||
#
|
||||
# Copyright (C) 2018 Red Hat, Inc.
|
||||
#
|
||||
# Authors:
|
||||
# Marc-André Lureau <marcandre.lureau@redhat.com>
|
||||
#
|
||||
# This work is licensed under the terms of the GNU GPL, version 2 or
|
||||
# later. See the COPYING file in the top-level directory.
|
||||
|
||||
##
|
||||
# *******************************************
|
||||
# vhost user backend discovery & capabilities
|
||||
# *******************************************
|
||||
##
|
||||
|
||||
##
|
||||
# @VHostUserBackendType:
|
||||
#
|
||||
# List the various vhost user backend types.
|
||||
#
|
||||
# @9p: 9p virtio console
|
||||
#
|
||||
# @balloon: virtio balloon
|
||||
#
|
||||
# @block: virtio block
|
||||
#
|
||||
# @caif: virtio caif
|
||||
#
|
||||
# @console: virtio console
|
||||
#
|
||||
# @crypto: virtio crypto
|
||||
#
|
||||
# @gpu: virtio gpu
|
||||
#
|
||||
# @input: virtio input
|
||||
#
|
||||
# @net: virtio net
|
||||
#
|
||||
# @rng: virtio rng
|
||||
#
|
||||
# @rpmsg: virtio remote processor messaging
|
||||
#
|
||||
# @rproc-serial: virtio remoteproc serial link
|
||||
#
|
||||
# @scsi: virtio scsi
|
||||
#
|
||||
# @vsock: virtio vsock transport
|
||||
#
|
||||
# @fs: virtio fs (since 4.2)
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'enum': 'VHostUserBackendType',
|
||||
'data': [
|
||||
'9p',
|
||||
'balloon',
|
||||
'block',
|
||||
'caif',
|
||||
'console',
|
||||
'crypto',
|
||||
'gpu',
|
||||
'input',
|
||||
'net',
|
||||
'rng',
|
||||
'rpmsg',
|
||||
'rproc-serial',
|
||||
'scsi',
|
||||
'vsock',
|
||||
'fs'
|
||||
]
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendBlockFeature:
|
||||
#
|
||||
# List of vhost user "block" features.
|
||||
#
|
||||
# @read-only: The --read-only command line option is supported.
|
||||
#
|
||||
# @blk-file: The --blk-file command line option is supported.
|
||||
#
|
||||
# Since: 5.0
|
||||
##
|
||||
{
|
||||
'enum': 'VHostUserBackendBlockFeature',
|
||||
'data': [ 'read-only', 'blk-file' ]
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendCapabilitiesBlock:
|
||||
#
|
||||
# Capabilities reported by vhost user "block" backends
|
||||
#
|
||||
# @features: list of supported features.
|
||||
#
|
||||
# Since: 5.0
|
||||
##
|
||||
{
|
||||
'struct': 'VHostUserBackendCapabilitiesBlock',
|
||||
'data': {
|
||||
'features': [ 'VHostUserBackendBlockFeature' ]
|
||||
}
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendInputFeature:
|
||||
#
|
||||
# List of vhost user "input" features.
|
||||
#
|
||||
# @evdev-path: The --evdev-path command line option is supported.
|
||||
#
|
||||
# @no-grab: The --no-grab command line option is supported.
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'enum': 'VHostUserBackendInputFeature',
|
||||
'data': [ 'evdev-path', 'no-grab' ]
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendCapabilitiesInput:
|
||||
#
|
||||
# Capabilities reported by vhost user "input" backends
|
||||
#
|
||||
# @features: list of supported features.
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'struct': 'VHostUserBackendCapabilitiesInput',
|
||||
'data': {
|
||||
'features': [ 'VHostUserBackendInputFeature' ]
|
||||
}
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendGPUFeature:
|
||||
#
|
||||
# List of vhost user "gpu" features.
|
||||
#
|
||||
# @render-node: The --render-node command line option is supported.
|
||||
#
|
||||
# @virgl: The --virgl command line option is supported.
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'enum': 'VHostUserBackendGPUFeature',
|
||||
'data': [ 'render-node', 'virgl' ]
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendCapabilitiesGPU:
|
||||
#
|
||||
# Capabilities reported by vhost user "gpu" backends.
|
||||
#
|
||||
# @features: list of supported features.
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'struct': 'VHostUserBackendCapabilitiesGPU',
|
||||
'data': {
|
||||
'features': [ 'VHostUserBackendGPUFeature' ]
|
||||
}
|
||||
}
|
||||
|
||||
##
|
||||
# @VHostUserBackendCapabilities:
|
||||
#
|
||||
# Capabilities reported by vhost user backends.
|
||||
#
|
||||
# @type: The vhost user backend type.
|
||||
#
|
||||
# Since: 4.0
|
||||
##
|
||||
{
|
||||
'union': 'VHostUserBackendCapabilities',
|
||||
'base': { 'type': 'VHostUserBackendType' },
|
||||
'discriminator': 'type',
|
||||
'data': {
|
||||
'input': 'VHostUserBackendCapabilitiesInput',
|
||||
'gpu': 'VHostUserBackendCapabilitiesGPU'
|
||||
}
|
||||
}
|
||||
|
||||
##
|
||||
# @VhostUserBackend:
|
||||
#
|
||||
# Describes a vhost user backend to management software.
|
||||
#
|
||||
# It is possible for multiple @VhostUserBackend elements to match the
|
||||
# search criteria of management software. Applications thus need
|
||||
# rules to pick one of the many matches, and users need the ability to
|
||||
# override distro defaults.
|
||||
#
|
||||
# It is recommended to create vhost user backend JSON files (each
|
||||
# containing a single @VhostUserBackend root element) with a
|
||||
# double-digit prefix, for example "50-qemu-gpu.json",
|
||||
# "50-crosvm-gpu.json", etc, so they can be sorted in predictable
|
||||
# order. The backend JSON files should be searched for in three
|
||||
# directories:
|
||||
#
|
||||
# - /usr/share/qemu/vhost-user -- populated by distro-provided
|
||||
# packages (XDG_DATA_DIRS covers
|
||||
# /usr/share by default),
|
||||
#
|
||||
# - /etc/qemu/vhost-user -- exclusively for sysadmins' local
|
||||
# additions,
|
||||
#
|
||||
# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user
|
||||
# local additions
|
||||
# (XDG_CONFIG_HOME defaults to
|
||||
# $HOME/.config).
|
||||
#
|
||||
# Top-down, the list of directories goes from general to specific.
|
||||
#
|
||||
# Management software should build a list of files from all three
|
||||
# locations, then sort the list by filename (i.e., basename
|
||||
# component). Management software should choose the first JSON file
|
||||
# on the sorted list that matches the search criteria. If a more
|
||||
# specific directory has a file with same name as a less specific
|
||||
# directory, then the file in the more specific directory takes
|
||||
# effect. If the more specific file is zero length, it hides the less
|
||||
# specific one.
|
||||
#
|
||||
# For example, if a distro ships
|
||||
#
|
||||
# - /usr/share/qemu/vhost-user/50-qemu-gpu.json
|
||||
#
|
||||
# - /usr/share/qemu/vhost-user/50-crosvm-gpu.json
|
||||
#
|
||||
# then the sysadmin can prevent the default QEMU GPU being used at all
|
||||
# with
|
||||
#
|
||||
# $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
|
||||
#
|
||||
# The sysadmin can replace/alter the distro default QEMU GPU with
|
||||
#
|
||||
# $ vim /etc/qemu/vhost-user/50-qemu-gpu.json
|
||||
#
|
||||
# or they can provide a parallel QEMU GPU with higher priority
|
||||
#
|
||||
# $ vim /etc/qemu/vhost-user/10-qemu-gpu.json
|
||||
#
|
||||
# or they can provide a parallel QEMU GPU with lower priority
|
||||
#
|
||||
# $ vim /etc/qemu/vhost-user/99-qemu-gpu.json
|
||||
#
|
||||
# @type: The vhost user backend type.
|
||||
#
|
||||
# @description: Provides a human-readable description of the backend.
|
||||
# Management software may or may not display @description.
|
||||
#
|
||||
# @binary: Absolute path to the backend binary.
|
||||
#
|
||||
# @tags: An optional list of auxiliary strings associated with the
|
||||
# backend for which @description is not appropriate, due to the
|
||||
# latter's possible exposure to the end-user. @tags serves
|
||||
# development and debugging purposes only, and management software
|
||||
# shall explicitly ignore it.
|
||||
#
|
||||
# Since: 4.0
|
||||
#
|
||||
# .. qmp-example:
|
||||
#
|
||||
# {
|
||||
# "description": "QEMU vhost-user-gpu",
|
||||
# "type": "gpu",
|
||||
# "binary": "/usr/libexec/qemu/vhost-user-gpu",
|
||||
# "tags": [
|
||||
# "CONFIG_OPENGL=y",
|
||||
# "CONFIG_GBM=y"
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
##
|
||||
{
|
||||
'struct' : 'VhostUserBackend',
|
||||
'data' : {
|
||||
'description': 'str',
|
||||
'type': 'VHostUserBackendType',
|
||||
'binary': 'str',
|
||||
'*tags': [ 'str' ]
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,17 @@
|
||||
=====================
|
||||
Vhost-vdpa Protocol
|
||||
=====================
|
||||
|
||||
Introduction
|
||||
=============
|
||||
vDPA(Virtual data path acceleration) device is a device that uses
|
||||
a datapath which complies with the virtio specifications with vendor
|
||||
specific control path. vDPA devices can be both physically located on
|
||||
the hardware or emulated by software.
|
||||
|
||||
This document describes the vDPA support in qemu
|
||||
|
||||
Here is the kernel commit here
|
||||
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=4c8cf31885f69e86be0b5b9e6677a26797365e1d
|
||||
|
||||
TODO : More information will add later
|
||||
@@ -0,0 +1,111 @@
|
||||
Virtio balloon memory statistics
|
||||
================================
|
||||
|
||||
The virtio balloon driver supports guest memory statistics reporting. These
|
||||
statistics are available to QEMU users as QOM (QEMU Object Model) device
|
||||
properties via a polling mechanism.
|
||||
|
||||
Before querying the available stats, clients first have to enable polling.
|
||||
This is done by writing a time interval value (in seconds) to the
|
||||
guest-stats-polling-interval property. This value can be:
|
||||
|
||||
> 0
|
||||
enables polling in the specified interval. If polling is already
|
||||
enabled, the polling time interval is changed to the new value
|
||||
|
||||
0
|
||||
disables polling. Previous polled statistics are still valid and
|
||||
can be queried.
|
||||
|
||||
Once polling is enabled, the virtio-balloon device in QEMU will start
|
||||
polling the guest's balloon driver for new stats in the specified time
|
||||
interval.
|
||||
|
||||
To retrieve those stats, clients have to query the guest-stats property,
|
||||
which will return a dictionary containing:
|
||||
|
||||
* A key named 'stats', containing all available stats. If the guest
|
||||
doesn't support a particular stat, or if it couldn't be retrieved,
|
||||
its value will be -1. Currently, the following stats are supported:
|
||||
|
||||
- stat-swap-in
|
||||
- stat-swap-out
|
||||
- stat-major-faults
|
||||
- stat-minor-faults
|
||||
- stat-free-memory
|
||||
- stat-total-memory
|
||||
- stat-available-memory
|
||||
- stat-disk-caches
|
||||
- stat-htlb-pgalloc
|
||||
- stat-htlb-pgfail
|
||||
|
||||
* A key named last-update, which contains the last stats update
|
||||
timestamp in seconds. Since this timestamp is generated by the host,
|
||||
a buggy guest can't influence its value. The value is 0 if the guest
|
||||
has not updated the stats (yet).
|
||||
|
||||
It's also important to note the following:
|
||||
|
||||
- Previously polled statistics remain available even if the polling is
|
||||
later disabled
|
||||
|
||||
- As noted above, if a guest doesn't support a particular stat its value
|
||||
will always be -1. However, it's also possible that a guest temporarily
|
||||
couldn't update one or even all stats. If this happens, just wait for
|
||||
the next update
|
||||
|
||||
- Polling can be enabled even if the guest doesn't have stats support
|
||||
or the balloon driver wasn't loaded in the guest. If this is the case
|
||||
and stats are queried, last-update will be 0.
|
||||
|
||||
- The polling timer is only re-armed when the guest responds to the
|
||||
statistics request. This means that if a (buggy) guest doesn't ever
|
||||
respond to the request the timer will never be re-armed, which has
|
||||
the same effect as disabling polling
|
||||
|
||||
Here are a few examples. QEMU is started with ``-device virtio-balloon``,
|
||||
which generates ``/machine/peripheral-anon/device[1]`` as the QOM path for
|
||||
the balloon device.
|
||||
|
||||
Enable polling with 2 seconds interval::
|
||||
|
||||
{ "execute": "qom-set",
|
||||
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
||||
"property": "guest-stats-polling-interval", "value": 2 } }
|
||||
|
||||
{ "return": {} }
|
||||
|
||||
Change polling to 10 seconds::
|
||||
|
||||
{ "execute": "qom-set",
|
||||
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
||||
"property": "guest-stats-polling-interval", "value": 10 } }
|
||||
|
||||
{ "return": {} }
|
||||
|
||||
Get stats::
|
||||
|
||||
{ "execute": "qom-get",
|
||||
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
||||
"property": "guest-stats" } }
|
||||
{
|
||||
"return": {
|
||||
"stats": {
|
||||
"stat-swap-out": 0,
|
||||
"stat-free-memory": 844943360,
|
||||
"stat-minor-faults": 219028,
|
||||
"stat-major-faults": 235,
|
||||
"stat-total-memory": 1044406272,
|
||||
"stat-swap-in": 0
|
||||
},
|
||||
"last-update": 1358529861
|
||||
}
|
||||
}
|
||||
|
||||
Disable polling::
|
||||
|
||||
{ "execute": "qom-set",
|
||||
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
||||
"property": "stats-polling-interval", "value": 0 } }
|
||||
|
||||
{ "return": {} }
|
||||
@@ -0,0 +1,50 @@
|
||||
VNC LED state Pseudo-encoding
|
||||
=============================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This document describes the Pseudo-encoding of LED state for RFB which
|
||||
is the protocol used in VNC as reference link below:
|
||||
|
||||
http://tigervnc.svn.sourceforge.net/viewvc/tigervnc/rfbproto/rfbproto.rst?content-type=text/plain
|
||||
|
||||
When accessing a guest by console through VNC, there might be mismatch
|
||||
between the lock keys notification LED on the computer running the VNC
|
||||
client session and the current status of the lock keys on the guest
|
||||
machine.
|
||||
|
||||
To solve this problem it attempts to add LED state Pseudo-encoding
|
||||
extension to VNC protocol to deal with setting LED state.
|
||||
|
||||
Pseudo-encoding
|
||||
---------------
|
||||
|
||||
This Pseudo-encoding requested by client declares to server that it supports
|
||||
LED state extensions to the protocol.
|
||||
|
||||
The Pseudo-encoding number for LED state defined as:
|
||||
|
||||
======= ===============================================================
|
||||
Number Name
|
||||
======= ===============================================================
|
||||
-261 'LED state Pseudo-encoding'
|
||||
======= ===============================================================
|
||||
|
||||
LED state Pseudo-encoding
|
||||
--------------------------
|
||||
|
||||
The LED state Pseudo-encoding describes the encoding of LED state which
|
||||
consists of 3 bits, from left to right each bit represents the Caps, Num,
|
||||
and Scroll lock key respectively. '1' indicates that the LED should be
|
||||
on and '0' should be off.
|
||||
|
||||
Some example encodings for it as following:
|
||||
|
||||
======= ===============================================================
|
||||
Code Description
|
||||
======= ===============================================================
|
||||
100 CapsLock is on, NumLock and ScrollLock are off
|
||||
010 NumLock is on, CapsLock and ScrollLock are off
|
||||
111 CapsLock, NumLock and ScrollLock are on
|
||||
======= ===============================================================
|
||||
Reference in new issue
Block a user