t/html; charset=UTF-8 Last-Modified: Fri, 08 May 2026 04:52:00 GMT Expires: Fri, 08 May 2026 05:07:00 GMT docs: move D-Bus VMState documentation to source XML - bwlp/qemu.git - Experimental fork of QEMU with video encoding patches
summaryrefslogtreecommitdiffstats
path: root/docs/interop
diff options
context:
space:
mode:
authorMarc-André Lureau2021-10-05 23:35:29 +0200
committerMarc-André Lureau2021-12-21 07:50:21 +0100
commitd2f25776ca4044ce4f19a4065cc0e4d2566f32ec (patch)
treecbab72532bff0b8ca98cf20499dfbf88a2205b54 /docs/interop
parentbackends: move dbus-vmstate1.xml to backends/ (diff)
downloadqemu-d2f25776ca4044ce4f19a4065cc0e4d2566f32ec.tar.gz
qemu-d2f25776ca4044ce4f19a4065cc0e4d2566f32ec.tar.xz
qemu-d2f25776ca4044ce4f19a4065cc0e4d2566f32ec.zip
docs: move D-Bus VMState documentation to source XML
Use the source XML document as single reference, importing its documentation via the dbus-doc directive. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Diffstat (limited to 'docs/interop')
-rw-r--r--docs/interop/dbus-vmstate.rst52
1 files changed, 8 insertions, 44 deletions
diff --git a/docs/interop/dbus-vmstate.rst b/docs/interop/dbus-vmstate.rst
index 1d719c1c60..5fb3f279e2 100644
--- a/docs/interop/dbus-vmstate.rst
+++ b/docs/interop/dbus-vmstate.rst
@@ -2,9 +2,6 @@
D-Bus VMState
=============
-Introduction
-============
-
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)
@@ -26,49 +23,16 @@ dbus-vmstate object can be configured with the expected list of
helpers by setting its ``id-list`` property, with a comma-separated
``Id`` list.
-Interface
-=========
-
-On object path ``/org/qemu/VMState1``, the following
-``org.qemu.VMState1`` interface should be implemented:
-
-.. code:: xml
-
- <interface name="org.qemu.VMState1">
- <property name="Id" type="s" access="read"/>
- <method name="Load">
- <arg type="ay" name="data" direction="in"/>
- </method>
- <method name="Save">
- <arg type="ay" name="data" direction="out"/>
- </method>
- </interface>
-
-"Id" property
--------------
-
-A string that identifies the helper uniquely. (maximum 256 bytes
-including terminating NUL byte)
-
-.. note::
-
- The helper ID namespace is a separate namespace. In particular, it is not
- related to QEMU "id" used in -object/-device objects.
-
-Load(in u8[] bytes) method
---------------------------
-
-The method called on destination with the state to restore.
+.. only:: sphinx4
-The helper may be initially started in a waiting state (with
-an --incoming argument for example), and it may resume on success.
+ .. dbus-doc:: backends/dbus-vmstate1.xml
-An error may be returned to the caller.
+.. only:: not sphinx4
-Save(out u8[] bytes) method
----------------------------
+ .. warning::
+ Sphinx 4 is required to build D-Bus documentation.
-The method called on the source to get the current state to be
-migrated. The helper should continue to run normally.
+ This is the content of ``backends/dbus-vmstate1.xml``:
-An error may be returned to the caller.
+ .. literalinclude:: ../../backends/dbus-vmstate1.xml
+ :language: xml
generated by cgit v1.2.3-55-g7522 (git 2.39.0) at 2026-05-08 06:52:00 +0200
span> # # Update Linux kernel headers QEMU requires from a specified kernel tree. # # Copyright (C) 2011 Siemens AG # # Authors: # Jan Kiszka <jan.kiszka@siemens.com> # # This work is licensed under the terms of the GNU GPL version 2. # See the COPYING file in the top-level directory. tmpdir=$(mktemp -d) linux="$1" output="$2" if [ -z "$linux" ] || ! [ -d "$linux" ]; then cat << EOF usage: update-kernel-headers.sh LINUX_PATH [OUTPUT_PATH] LINUX_PATH Linux kernel directory to obtain the headers from OUTPUT_PATH output directory, usually the qemu source tree (default: $PWD) EOF exit 1 fi if [ -z "$output" ]; then output="$PWD" fi cp_portable() { f=$1 to=$2 if grep '#include' "$f" | grep -v -e 'linux/virtio' \ -e 'linux/types' \ -e 'stdint' \ -e 'linux/if_ether' \ -e 'input-event-codes' \ -e 'sys/' \ -e 'pvrdma_verbs' \ -e 'drm.h' \ -e 'limits' \ -e 'linux/kernel' \ -e 'linux/sysinfo' \ -e 'asm-generic/kvm_para' \ > /dev/null then echo "Unexpected #include in input file $f". exit 2 fi header=$(basename "$f"); sed -e 's/__aligned_u64/__u64 __attribute__((aligned(8)))/g' \ -e 's/__u\([0-9][0-9]*\)/uint\1_t/g' \ -e 's/u\([0-9][0-9]*\)/uint\1_t/g' \ -e 's/__s\([0-9][0-9]*\)/int\1_t/g' \ -e 's/__le\([0-9][0-9]*\)/uint\1_t/g' \ -e 's/__be\([0-9][0-9]*\)/uint\1_t/g' \ -e 's/"\(input-event-codes\.h\)"/"standard-headers\/linux\/\1"/' \ -e 's/<linux\/\([^>]*\)>/"standard-headers\/linux\/\1"/' \ -e 's/__bitwise//' \ -e 's/__attribute__((packed))/QEMU_PACKED/' \ -e 's/__inline__/inline/' \ -e 's/__BITS_PER_LONG/HOST_LONG_BITS/' \ -e '/\"drm.h\"/d' \ -e '/sys\/ioctl.h/d' \ -e 's/SW_MAX/SW_MAX_/' \ -e 's/atomic_t/int/' \ -e 's/__kernel_long_t/long/' \ -e 's/__kernel_ulong_t/unsigned long/' \ -e 's/struct ethhdr/struct eth_header/' \ -e '/\#define _LINUX_ETHTOOL_H/a \\n\#include "net/eth.h"' \ "$f" > "$to/$header"; } # This will pick up non-directories too (eg "Kconfig") but we will # ignore them in the next loop. ARCHLIST=$(cd "$linux/arch" && echo *) for arch in $ARCHLIST; do # Discard anything which isn't a KVM-supporting architecture if ! [ -e "$linux/arch/$arch/include/asm/kvm.h" ] && ! [ -e "$linux/arch/$arch/include/uapi/asm/kvm.h" ] ; then continue fi if [ "$arch" = x86 ]; then arch_var=SRCARCH else arch_var=ARCH fi make -C "$linux" INSTALL_HDR_PATH="$tmpdir" $arch_var=$arch headers_install rm -rf "$output/linux-headers/asm-$arch" mkdir -p "$output/linux-headers/asm-$arch" for header in kvm.h unistd.h bitsperlong.h mman.h; do cp "$tmpdir/include/asm/$header" "$output/linux-headers/asm-$arch" done if [ $arch = mips ]; then cp "$tmpdir/include/asm/sgidefs.h" "$output/linux-headers/asm-mips/" cp "$tmpdir/include/asm/unistd_o32.h" "$output/linux-headers/asm-mips/" cp "$tmpdir/include/asm/unistd_n32.h" "$output/linux-headers/asm-mips/" cp "$tmpdir/include/asm/unistd_n64.h" "$output/linux-headers/asm-mips/" fi if [ $arch = powerpc ]; then cp "$tmpdir/include/asm/unistd_32.h" "$output/linux-headers/asm-powerpc/" cp "$tmpdir/include/asm/unistd_64.h" "$output/linux-headers/asm-powerpc/" fi rm -rf "$output/include/standard-headers/asm-$arch" mkdir -p "$output/include/standard-headers/asm-$arch" if [ $arch = s390 ]; then cp_portable "$tmpdir/include/asm/virtio-ccw.h" "$output/include/standard-headers/asm-s390/" cp "$tmpdir/include/asm/unistd_32.h" "$output/linux-headers/asm-s390/" cp "$tmpdir/include/asm/unistd_64.h" "$output/linux-headers/asm-s390/" fi if [ $arch = arm ]; then cp "$tmpdir/include/asm/unistd-eabi.h" "$output/linux-headers/asm-arm/" cp "$tmpdir/include/asm/unistd-oabi.h" "$output/linux-headers/asm-arm/" cp "$tmpdir/include/asm/unistd-common.h" "$output/linux-headers/asm-arm/" fi if [ $arch = arm64 ]; then cp "$tmpdir/include/asm/sve_context.h" "$output/linux-headers/asm-arm64/" fi if [ $arch = x86 ]; then cp "$tmpdir/include/asm/unistd_32.h" "$output/linux-headers/asm-x86/" cp "$tmpdir/include/asm/unistd_x32.h" "$output/linux-headers/asm-x86/" cp "$tmpdir/include/asm/unistd_64.h" "$output/linux-headers/asm-x86/" cp_portable "$tmpdir/include/asm/kvm_para.h" "$output/include/standard-headers/asm-$arch" # Remove everything except the macros from bootparam.h avoiding the # unnecessary import of several video/ist/etc headers sed -e '/__ASSEMBLY__/,/__ASSEMBLY__/d' \ "$tmpdir/include/asm/bootparam.h" > "$tmpdir/bootparam.h" cp_portable "$tmpdir/bootparam.h" \ "$output/include/standard-headers/asm-$arch" fi done rm -rf "$output/linux-headers/linux" mkdir -p "$output/linux-headers/linux" for header in kvm.h vfio.h vfio_ccw.h vhost.h \ psci.h psp-sev.h userfaultfd.h mman.h; do cp "$tmpdir/include/linux/$header" "$output/linux-headers/linux" done rm -rf "$output/linux-headers/asm-generic" mkdir -p "$output/linux-headers/asm-generic" for header in unistd.h bitsperlong.h mman-common.h mman.h hugetlb_encode.h; do cp "$tmpdir/include/asm-generic/$header" "$output/linux-headers/asm-generic" done if [ -L "$linux/source" ]; then cp "$linux/source/COPYING" "$output/linux-headers" else cp "$linux/COPYING" "$output/linux-headers" fi # Recent kernel sources split the copyright/license info into multiple # files, which we need to copy. This set of licenses is the set that # are referred to by SPDX lines in the headers we currently copy. # We don't copy the Documentation/process/license-rules.rst which # is also referred to by COPYING, since it's explanatory rather than license. if [ -d "$linux/LICENSES" ]; then mkdir -p "$output/linux-headers/LICENSES/preferred" \ "$output/linux-headers/LICENSES/exceptions" for l in preferred/GPL-2.0 preferred/BSD-2-Clause preferred/BSD-3-Clause \ exceptions/Linux-syscall-note; do cp "$linux/LICENSES/$l" "$output/linux-headers/LICENSES/$l" done fi cat <<EOF >$output/linux-headers/linux/virtio_config.h #include "standard-headers/linux/virtio_config.h" EOF cat <<EOF >$output/linux-headers/linux/virtio_ring.h #include "standard-headers/linux/virtio_ring.h" EOF cat <<EOF >$output/linux-headers/linux/vhost_types.h #include "standard-headers/linux/vhost_types.h" EOF rm -rf "$output/include/standard-headers/linux" mkdir -p "$output/include/standard-headers/linux" for i in "$tmpdir"/include/linux/*virtio*.h \ "$tmpdir/include/linux/qemu_fw_cfg.h" \ "$tmpdir/include/linux/input.h" \ "$tmpdir/include/linux/input-event-codes.h" \ "$tmpdir/include/linux/pci_regs.h" \ "$tmpdir/include/linux/ethtool.h" "$tmpdir/include/linux/kernel.h" \ "$tmpdir/include/linux/vhost_types.h" \ "$tmpdir/include/linux/sysinfo.h"; do cp_portable "$i" "$output/include/standard-headers/linux" done mkdir -p "$output/include/standard-headers/drm" cp_portable "$tmpdir/include/drm/drm_fourcc.h" \ "$output/include/standard-headers/drm" rm -rf "$output/include/standard-headers/drivers/infiniband/hw/vmw_pvrdma" mkdir -p "$output/include/standard-headers/drivers/infiniband/hw/vmw_pvrdma" # Remove the unused functions from pvrdma_verbs.h avoiding the unnecessary # import of several infiniband/networking/other headers tmp_pvrdma_verbs="$tmpdir/pvrdma_verbs.h" # Parse the entire file instead of single lines to match # function declarations expanding over multiple lines # and strip the declarations starting with pvrdma prefix. sed -e '1h;2,$H;$!d;g' -e 's/[^};]*pvrdma[^(| ]*([^)]*);//g' \ "$linux/drivers/infiniband/hw/vmw_pvrdma/pvrdma_verbs.h" > \ "$tmp_pvrdma_verbs"; for i in "$linux/drivers/infiniband/hw/vmw_pvrdma/pvrdma_ring.h" \ "$linux/drivers/infiniband/hw/vmw_pvrdma/pvrdma_dev_api.h" \ "$tmp_pvrdma_verbs"; do \ cp_portable "$i" \ "$output/include/standard-headers/drivers/infiniband/hw/vmw_pvrdma/" done rm -rf "$output/include/standard-headers/rdma/" mkdir -p "$output/include/standard-headers/rdma/" for i in "$tmpdir/include/rdma/vmw_pvrdma-abi.h"; do cp_portable "$i" \ "$output/include/standard-headers/rdma/" done cat <<EOF >$output/include/standard-headers/linux/types.h /* For QEMU all types are already defined via osdep.h, so this * header does not need to do anything. */ EOF cat <<EOF >$output/include/standard-headers/linux/if_ether.h #define ETH_ALEN 6 EOF rm -rf "$tmpdir"
generated by cgit v1.2.3-55-g7522 (git 2.39.0) at 2026-05-08 06:52:00 +0200