From nobody Mon Feb 9 11:05:53 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1648469545; cv=none; d=zohomail.com; s=zohoarc; b=cTcaQsDxLqW2LtppH/LaHMp34ez874VcsvV5sjhGfiS+GcwQSqTHWp5kwXAEB8WByz2cjVcWMGxwSdLdQB9NyMmG4dYPzJoIRn75D9d85v+Ll+zfh3/8+mSu7eDy7BbgiS4QTDWAnma5wL5Mf8WqZP0fhIwqGgZOY/mrU8tY944= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469545; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=varTUndcNY+tu7ULAvF+siULPBblsWY9tCckIvCevLQ=; b=kRCvWwNrcUxOLOSWAzSvVxByy5oR4Z5kxoDvXoVL5n4zxyoSWF3OaNK7kW5sIsPJUf7tPTpW381yKZ186oNI34VocKU9igZXAygRohK3LqcRhY9QnkzpfxWXTYgTOZIIia2O2YWBAJUJjXIPO42RKrAAnNE00fDksKgDYQY1Jew= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1648469545404528.4499937811041; Mon, 28 Mar 2022 05:12:25 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-572-R2OxAiX_OM6HSNiv88t9Ew-1; Mon, 28 Mar 2022 08:11:10 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 593A92A2AD64; Mon, 28 Mar 2022 12:11:07 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3A2D640CF8FE; Mon, 28 Mar 2022 12:11:07 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 0888F1940354; Mon, 28 Mar 2022 12:11:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B91671947BBE for ; Mon, 28 Mar 2022 12:11:03 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id AC1211400B19; Mon, 28 Mar 2022 12:11:03 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 27FA21402642 for ; Mon, 28 Mar 2022 12:11:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469544; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=varTUndcNY+tu7ULAvF+siULPBblsWY9tCckIvCevLQ=; b=Fs74ad/ckuVcQOL4lP4ewEx9TcvjIJZi1emmZfAZXQWOmIa6BqyF/nOku6anXTmSGbrYSD hBSVU1XoEYoCi1qiqHl13lwduXRCCqWxrDVrn3jZDV3TnIKWr97eptz+t9iDVtJl5lcoPT ascVGVQEXIqjkJG1dU8fcbIok9zI0dQ= X-MC-Unique: R2OxAiX_OM6HSNiv88t9Ew-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 17/29] docs: Convert 'formatcaps' page to rST Date: Mon, 28 Mar 2022 14:10:32 +0200 Message-Id: <16e193926211fad679cd01cfa0f9c1c05cfe2583.1648469356.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469546961100001 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa --- docs/formatcaps.html.in | 219 ---------------------------------------- docs/formatcaps.rst | 196 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 197 insertions(+), 220 deletions(-) delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in deleted file mode 100644 index 09662f78c8..0000000000 --- a/docs/formatcaps.html.in +++ /dev/null @@ -1,219 +0,0 @@ - - - - -

Driver capabilities XML format

- -
    - -

    Element and attribute overview

    - -

    As new virtualization engine support gets added to libvirt, and to - handle cases like QEMU supporting a variety of emulations, a query - interface has been added in 0.2.1 allowing to list the set of supported - virtualization capabilities on the host:

    - - 
    char * virConnectGetCapabilities (virConnectPtr conn);
    - -

    The value returned is an XML document listing the virtualization - capabilities of the host and virtualization engine to which - @conn is connected. One can test it using virsh - command line tool command 'capabilities', it dumps the XML - associated to the current connection.

    - -

    As can be seen in the example, the - capabilities XML consists of the capabilities element whi= ch - have exactly one host child element to report information= on - host capabilities, and zero or more guest element to expr= ess - the set of architectures the host can run at the moment.

    - - -

    Host capabilities

    - -

    The <host/> element consists of the following ch= ild - elements:

    -
    -
    uuid
    -
    The host UUID.
    - -
    cpu
    -
    The host CPU architecture and features.
    - -
    power_management
    -
    whether host is capable of memory suspend, disk hibernation, or - hybrid suspend.
    - -
    migration_features
    -
    This element exposes information on the hypervisor's migration - capabilities, like live migration, supported URI transports, and so - on.
    - -
    topology
    -
    This element embodies the host internal topology. Management - applications may want to learn this information when orchestrating n= ew - guests - e.g. due to reduce inter-NUMA node transfers.
    - -
    secmodel
    -
    To find out default security labels for different security model= s you - need to parse this element. In contrast with the former elements, th= is is - repeated for each security model the libvirt daemon currently suppor= ts. -
    -
    - - -

    Guest capabilities

    - -

    While the previous section aims at host - capabilities, this one focuses on capabilities available to a guest - using a given hypervisor. The <guest/> element will - typically wrap up the following elements:

    - -
    -
    os_type
    -
    This expresses what kind of operating system the hypervisor - is able to run. Possible values are: -
    -
    xen
    -
    for XEN PV
    - -
    linux
    -
    legacy alias for xen
    - -
    xenpvh
    -
    for XEN PVH
    - -
    hvm
    -
    Unmodified operating system
    - -
    exe
    -
    Container based virtualization
    -
    -
    - -
    arch
    -
    This element brings some information on supported guest - architecture. Possible subelements are: -
    -
    wordsize
    Size of CPU word in bits, fo= r example 64.
    -
    emulator
    Emulator (device model) path= , for - use in emulato= r - element of domain XML.
    -
    loader
    Loader path, for use in - loader eleme= nt of domain - XML.
    -
    machine
    Machine type, for use in - machine= - attribute of os/type element in domain XML. For example Xen - supports xenfv for HVM, xenpv for - PV, or xenpvh for PVH.
    -
    domain
    The type attribut= e of - this element specifies the type of hypervisor required to ru= n the - domain. Use in type - attribute of the domain root element.
    -
    -
    - -
    features
    -
    This optional element encases possible features that can be us= ed - with a guest of described type. Possible subelements are: -
    -
    pae
    If present, 32-bit guests can use= PAE - address space extensions, since - 0.4.1
    -
    nonpae
    If present, 32-bit guests can = be run - without requiring PAE, since - 0.4.1
    -
    ia64_be
    If present, IA64 guests can b= e run in - big-endian mode, since 0.4.1 -
    acpi
    If this element is present, - the default attribute describes whether the - hypervisor exposes ACPI to the guest by default, and - the toggle attribute describes whether the - user can override this - default. Since 0.4.1
    -
    apic
    If this element is present, - the default attribute describes whether the - hypervisor exposes APIC to the guest by default, and - the toggle attribute describes whether the - user can override this - default. Since 0.4.1
    -
    cpuselection
    If this element is prese= nt, the - hypervisor supports the <cpu> element - within a domain definition for fine-grained control over - the CPU presented to the - guest. Since 0.7.5
    -
    deviceboot
    If this element is present, - the <boot order=3D'...'/> element can - be used inside devices, rather than the older boot - specification by category. Since - 0.8.8
    -
    disksnapshot
    If this element is prese= nt, - the default attribute describes whether - external disk snapshots are supported. If absent, - external snapshots may still be supported, but it - requires attempting the API and checking for an error to - find out for sure. Since - 1.2.3
    -
    -
    -
    - -

    Examples

    - -

    For example, in the case of a 64-bit machine with hardware - virtualization capabilities enabled in the chip and - BIOS you will see:

    - - 
    <capabilities>
-  <host>
-    <cpu>
-      <arch>x86_64</arch>
-      <features>
-        <vmx/>
-      </features>
-      <model>core2duo</model>
-      <vendor>Intel</vendor>
-      <topology sockets=3D"1" dies=3D"1" cores=3D"2" threads=3D"1"/>
-      <feature name=3D"lahf_lm"/>
-      <feature name=3D'xtpr'/>
-      ...
-    </cpu>
-    <power_management>
-      <suspend_mem/>
-      <suspend_disk/>
-      <suspend_hybrid/>
-    </power_management>
-  </host>
-
-  <!-- xen-3.0-x86_64 -->
-  <guest>
-    <os_type>xen</os_type>
-    <arch name=3D"x86_64">
-      <wordsize>64</wordsize>
-      <domain type=3D"xen"></domain>
-      <emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
-    </arch>
-    <features>
-    </features>
-  </guest>
-
-  <!-- hvm-3.0-x86_32 -->
-  <guest>
-    <os_type>hvm</os_type>
-    <arch name=3D"i686">
-      <wordsize>32</wordsize>
-      <domain type=3D"xen"></domain>
-      <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
-      <machine>pc</machine>
-      <machine>isapc</machine>
-      <loader>/usr/lib/xen/boot/hvmloader</loader>
-    </arch>
-    <features>
-      <cpuselection/>
-      <deviceboot/>
-    </features>
-  </guest>
-  ...
-</capabilities>
    - - diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst new file mode 100644 index 0000000000..1ba847cea1 --- /dev/null +++ b/docs/formatcaps.rst @@ -0,0 +1,196 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D +Driver capabilities XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + +.. contents:: + +Element and attribute overview +------------------------------ + +As new virtualization engine support gets added to libvirt, and to handle = cases +like QEMU supporting a variety of emulations, a query interface has been a= dded +in 0.2.1 allowing to list the set of supported virtualization capabilities= on +the host: + +:: + + char * virConnectGetCapabilities (virConnectPtr conn); + +The value returned is an XML document listing the virtualization capabilit= ies of +the host and virtualization engine to which ``@conn`` is connected. One ca= n test +it using ``virsh`` command line tool command '``capabilities``', it dumps = the +XML associated to the current connection. + +As can be seen in the `example <#elementExamples>`__, the capabilities XML +consists of the ``capabilities`` element which have exactly one ``host`` c= hild +element to report information on host capabilities, and zero or more ``gue= st`` +element to express the set of architectures the host can run at the moment. + +Host capabilities +~~~~~~~~~~~~~~~~~ + +The ```` element consists of the following child elements: + +``uuid`` + The host UUID. +``cpu`` + The host CPU architecture and features. +``power_management`` + whether host is capable of memory suspend, disk hibernation, or hybrid + suspend. +``migration_features`` + This element exposes information on the hypervisor's migration capabili= ties, + like live migration, supported URI transports, and so on. +``topology`` + This element embodies the host internal topology. Management applicatio= ns may + want to learn this information when orchestrating new guests - e.g. due= to + reduce inter-NUMA node transfers. +``secmodel`` + To find out default security labels for different security models you n= eed to + parse this element. In contrast with the former elements, this is repea= ted + for each security model the libvirt daemon currently supports. + +Guest capabilities +~~~~~~~~~~~~~~~~~~ + +While the `previous section <#elementHost>`__ aims at host capabilities, t= his +one focuses on capabilities available to a guest using a given hypervisor.= The +```` element will typically wrap up the following elements: + +``os_type`` + This expresses what kind of operating system the hypervisor is able to = run. + Possible values are: + + ``xen`` + for XEN PV + ``linux`` + legacy alias for ``xen`` + ``xenpvh`` + for XEN PVH + ``hvm`` + Unmodified operating system + ``exe`` + Container based virtualization +``arch`` + This element brings some information on supported guest architecture. + Possible subelements are: + + ``wordsize`` + Size of CPU word in bits, for example 64. + ``emulator`` + Emulator (device model) path, for use in + `emulator `__ element of domain X= ML. + ``loader`` + Loader path, for use in `loader `__ + element of domain XML. + ``machine`` + Machine type, for use in + `machine `__ attribute of + os/type element in domain XML. For example Xen supports ``xenfv`` fo= r HVM, + ``xenpv`` for PV, or ``xenpvh`` for PVH. + ``domain`` + The ``type`` attribute of this element specifies the type of hypervi= sor + required to run the domain. Use in + `type `__ attribute of the do= main + root element. +``features`` + This optional element encases possible features that can be used with a= guest + of described type. Possible subelements are: + + ``pae`` + If present, 32-bit guests can use PAE address space extensions, + :since:`since 0.4.1` + ``nonpae`` + If present, 32-bit guests can be run without requiring PAE, :since:`= since + 0.4.1` + ``ia64_be`` + If present, IA64 guests can be run in big-endian mode, :since:`since + 0.4.1` + ``acpi`` + If this element is present, the ``default`` attribute describes whet= her + the hypervisor exposes ACPI to the guest by default, and the ``toggl= e`` + attribute describes whether the user can override this default. + :since:`Since 0.4.1` + ``apic`` + If this element is present, the ``default`` attribute describes whet= her + the hypervisor exposes APIC to the guest by default, and the ``toggl= e`` + attribute describes whether the user can override this default. + :since:`Since 0.4.1` + ``cpuselection`` + If this element is present, the hypervisor supports the ```` el= ement + within a domain definition for fine-grained control over the CPU pre= sented + to the guest. :since:`Since 0.7.5` + ``deviceboot`` + If this element is present, the ```` element ca= n be + used inside devices, rather than the older boot specification by cat= egory. + :since:`Since 0.8.8` + ``disksnapshot`` + If this element is present, the ``default`` attribute describes whet= her + external disk snapshots are supported. If absent, external snapshots= may + still be supported, but it requires attempting the API and checking = for an + error to find out for sure. :since:`Since 1.2.3` + +Examples +~~~~~~~~ + +For example, in the case of a 64-bit machine with hardware virtualization +capabilities enabled in the chip and BIOS you will see: + +:: + + + + + x86_64 + + + + core2duo + Intel + + + + ... + + + + + + + + + + + + xen + + 64 + + /usr/lib64/xen/bin/qemu-dm + + + + + + + + + hvm + + 32 + + /usr/lib/xen/bin/qemu-dm + pc + isapc + /usr/lib/xen/boot/hvmloader + + + + + + + + ... + diff --git a/docs/meson.build b/docs/meson.build index acc455c7c7..95c9babcf5 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files =3D [ 'csharp', 'dbus', 'docs', - 'formatcaps', 'formatdomaincaps', 'formatnetwork', 'formatnetworkport', @@ -83,6 +82,7 @@ docs_rst_files =3D [ 'firewall', 'format', 'formatbackup', + 'formatcaps', 'formatcheckpoint', 'formatdomain', 'formatsecret', --=20 2.35.1