From nobody Mon Feb 9 14:34:33 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 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=1595510540; cv=none; d=zohomail.com; s=zohoarc; b=f/lqqgayukWySL8E9PHP6zeeIsOCSgXQ8npETkwMjSMPgzc6AZppw/V0EvW1Qx0/IQFhFAgZWRcfyp/a9xWhCKGB71nuBsCmesSxYYEAC1xZGQaFPySIVW+AQQ83R+9z5hlG6q3+Yam8YT5zf4ZYDjwwfD1ikCHl0Mq32/LOALc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510540; 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=yUbNi0jcHIZj2bd/deMOhIUjP644UJGk3fYjBoq+CC0=; b=EuJ/YOdlIml9WNgD3E5Iwb8qjPcROgmZytSM5+qEJ54aVt4InsvpysmlAhkoEzLhYIj26DBWGeeSfUTNdorF5TvyOsnfrxkyiuy9SdlCG+8Eg7TDmrV8JXC/b/iQHviuz88HPCTlfKERNF0OzK81JW8M3xQ9uJCoGtyweVomvw0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1595510540810339.13620607428754; Thu, 23 Jul 2020 06:22:20 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-494-vwvL3mV7Nimv50HATnc3xA-1; Thu, 23 Jul 2020 09:22:16 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D60AD193248F; Thu, 23 Jul 2020 13:22:10 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B5BA58FA21; Thu, 23 Jul 2020 13:22:10 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 83BA21800FDE; Thu, 23 Jul 2020 13:22:10 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDM7BA028499 for ; Thu, 23 Jul 2020 09:22:07 -0400 Received: by smtp.corp.redhat.com (Postfix) id 6A43E19D7D; Thu, 23 Jul 2020 13:22:07 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id B99EB1A91F for ; Thu, 23 Jul 2020 13:22:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510539; 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=yUbNi0jcHIZj2bd/deMOhIUjP644UJGk3fYjBoq+CC0=; b=O65gIOQGul9+nCQ/owvwAHou5z0A32ab2aSkrcBUAtuvoZgib7c1gWcGrLps1izXrIt3OG 22jzmI4/3M11AIqBsQ2vi6rS1rnenYoI/eS2Ndt6XsDcIoEfg4+/oHF5uYnY+H7wwwVPwl G6JsR22vq2rF7EVeywGCp5LcTiomQG8= X-MC-Unique: vwvL3mV7Nimv50HATnc3xA-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 09/32] docs: formatdomain-devices: Split out address information Date: Thu, 23 Jul 2020 15:21:14 +0200 Message-Id: <00038e117fee5f0d57e9b7baaac55a83086149ff.1595510131.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Start splitting out part of into smaller sections. Signed-off-by: Peter Krempa --- docs/formatdomain-devices-address.rst | 92 ++++++++++++++++++++++++++ docs/formatdomain-devices.rst | 94 +-------------------------- docs/meson.build | 1 + 3 files changed, 94 insertions(+), 93 deletions(-) create mode 100644 docs/formatdomain-devices-address.rst diff --git a/docs/formatdomain-devices-address.rst b/docs/formatdomain-devi= ces-address.rst new file mode 100644 index 0000000000..902dc94ae1 --- /dev/null +++ b/docs/formatdomain-devices-address.rst @@ -0,0 +1,92 @@ +:anchor:`` + +Device Addresses +~~~~~~~~~~~~~~~~ + +Many devices have an optional ``
`` sub-element to describe where = the +device is placed on the virtual bus presented to the guest. If an address = (or +any optional attribute within an address) is omitted on input, libvirt will +generate an appropriate address; but an explicit address is required if mo= re +control over layout is required. See below for device examples including an +address element. + +Every address has a mandatory attribute ``type`` that describes which bus = the +device is on. The choice of which address to use for a given device is +constrained in part by the device and the architecture of the guest. For +example, a ```` device uses ``type=3D'drive'``, while a ```= ` device +would use ``type=3D'pci'`` on i686 or x86_64 guests, or ``type=3D'spapr-vi= o'`` on +PowerPC64 pseries guests. Each address type has further optional attribute= s that +control where on the bus the device will be placed: + +``pci`` + PCI addresses have the following additional attributes: ``domain`` (a 2= -byte + hex integer, not currently used by qemu), ``bus`` (a hex value between = 0 and + 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive= ), and + ``function`` (a value between 0 and 7, inclusive). Also available is the + ``multifunction`` attribute, which controls turning on the multifunctio= n bit + for a particular slot/function in the PCI control register ( :since:`si= nce + 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but = should + be set to 'on' for function 0 of a slot that will have multiple functio= ns + used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the + architecture are supported. For example, PCI addresses for S390 guests = will + have a ``zpci`` child element, with two attributes: ``uid`` (a hex value + between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between + 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for + User-defined Identifiers and Function Identifiers. + :since:`Since 1.3.5` , some hypervisor drivers may accept an + ``
`` element with no other attributes as an expl= icit + request to assign a PCI address for the device rather than some other t= ype of + address that may also be appropriate for that same device (e.g. virtio-= mmio). + The relationship between the PCI addresses configured in the domain XML= and + those seen by the guest OS can sometime seem confusing: a separate docu= ment + describes `how PCI addresses work `__ in more detai= l. +``drive`` + Drive addresses have the following additional attributes: ``controller`= ` (a + 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` = (a + 2-digit target number), and ``unit`` (a 2-digit unit number on the bus). +``virtio-serial`` + Each virtio-serial address has the following additional attributes: + ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus nu= mber), + and ``slot`` (a 2-digit slot within the bus). +``ccid`` + A CCID address, for smart-cards, has the following additional attribute= s: + ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot = within + the bus). :since:`Since 0.8.8.` +``usb`` + USB addresses have the following additional attributes: ``bus`` (a hex = value + between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up = to + four octets, such as 1.2 or 2.1.3.1). +``spapr-vio`` + On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus= . It + has a flat 32-bit address space; by convention, devices are generally + assigned at a non-zero multiple of 0x00001000, but other addresses are = valid + and permitted by libvirt. Each address has the following additional + attribute: ``reg`` (the hex value address of the starting register). + :since:`Since 0.9.9.` +``ccw`` + S390 guests with a ``machine`` value of s390-ccw-virtio use the native = CCW + bus for I/O devices. CCW bus addresses have the following additional + attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ss= id`` + (a value between 0 and 3, inclusive) and ``devno`` (a hex value between= 0 and + 0xffff, inclusive). Partially specified bus addresses are not allowed. = If + omitted, libvirt will assign a free bus address with cssid=3D0xfe and s= sid=3D0. + Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0= .4` +``virtio-mmio`` + This places the device on the virtio-mmio transport, which is currently= only + available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-= mmio + addresses do not have any additional attributes. :since:`Since 1.1.3` + If the guest architecture is ``aarch64`` and the machine type is ``virt= ``, + libvirt will automatically assign PCI addresses to devices; however, the + presence of a single device with virtio-mmio address in the guest + configuration will cause libvirt to assign virtio-mmio addresses to all + further devices. :since:`Since 3.0.0` +``isa`` + ISA addresses have the following additional attributes: ``iobase`` and + ``irq``. :since:`Since 1.2.1` +``unassigned`` + For PCI hostdevs, ``
`` allows the admin to + include a PCI hostdev in the domain XML definition, without making it + available for the guest. This allows for configurations in which Libvirt + manages the device as a regular PCI hostdev, regardless of whether the = guest + will have access to it. ``
`` is an invalid + address type for all other device types. :since:`Since 6.0.0` diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 564ce4caca..c789495e5d 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -41,99 +41,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3= .9.0` .. include:: formatdomain-devices-disk.rst .. include:: formatdomain-devices-filesystem.rst - -:anchor:`` - -Device Addresses -~~~~~~~~~~~~~~~~ - -Many devices have an optional ``
`` sub-element to describe where = the -device is placed on the virtual bus presented to the guest. If an address = (or -any optional attribute within an address) is omitted on input, libvirt will -generate an appropriate address; but an explicit address is required if mo= re -control over layout is required. See below for device examples including an -address element. - -Every address has a mandatory attribute ``type`` that describes which bus = the -device is on. The choice of which address to use for a given device is -constrained in part by the device and the architecture of the guest. For -example, a ```` device uses ``type=3D'drive'``, while a ```= ` device -would use ``type=3D'pci'`` on i686 or x86_64 guests, or ``type=3D'spapr-vi= o'`` on -PowerPC64 pseries guests. Each address type has further optional attribute= s that -control where on the bus the device will be placed: - -``pci`` - PCI addresses have the following additional attributes: ``domain`` (a 2= -byte - hex integer, not currently used by qemu), ``bus`` (a hex value between = 0 and - 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive= ), and - ``function`` (a value between 0 and 7, inclusive). Also available is the - ``multifunction`` attribute, which controls turning on the multifunctio= n bit - for a particular slot/function in the PCI control register ( :since:`si= nce - 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but = should - be set to 'on' for function 0 of a slot that will have multiple functio= ns - used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the - architecture are supported. For example, PCI addresses for S390 guests = will - have a ``zpci`` child element, with two attributes: ``uid`` (a hex value - between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between - 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for - User-defined Identifiers and Function Identifiers. - :since:`Since 1.3.5` , some hypervisor drivers may accept an - ``
`` element with no other attributes as an expl= icit - request to assign a PCI address for the device rather than some other t= ype of - address that may also be appropriate for that same device (e.g. virtio-= mmio). - The relationship between the PCI addresses configured in the domain XML= and - those seen by the guest OS can sometime seem confusing: a separate docu= ment - describes `how PCI addresses work `__ in more detai= l. -``drive`` - Drive addresses have the following additional attributes: ``controller`= ` (a - 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` = (a - 2-digit target number), and ``unit`` (a 2-digit unit number on the bus). -``virtio-serial`` - Each virtio-serial address has the following additional attributes: - ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus nu= mber), - and ``slot`` (a 2-digit slot within the bus). -``ccid`` - A CCID address, for smart-cards, has the following additional attribute= s: - ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot = within - the bus). :since:`Since 0.8.8.` -``usb`` - USB addresses have the following additional attributes: ``bus`` (a hex = value - between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up = to - four octets, such as 1.2 or 2.1.3.1). -``spapr-vio`` - On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus= . It - has a flat 32-bit address space; by convention, devices are generally - assigned at a non-zero multiple of 0x00001000, but other addresses are = valid - and permitted by libvirt. Each address has the following additional - attribute: ``reg`` (the hex value address of the starting register). - :since:`Since 0.9.9.` -``ccw`` - S390 guests with a ``machine`` value of s390-ccw-virtio use the native = CCW - bus for I/O devices. CCW bus addresses have the following additional - attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ss= id`` - (a value between 0 and 3, inclusive) and ``devno`` (a hex value between= 0 and - 0xffff, inclusive). Partially specified bus addresses are not allowed. = If - omitted, libvirt will assign a free bus address with cssid=3D0xfe and s= sid=3D0. - Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0= .4` -``virtio-mmio`` - This places the device on the virtio-mmio transport, which is currently= only - available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-= mmio - addresses do not have any additional attributes. :since:`Since 1.1.3` - If the guest architecture is ``aarch64`` and the machine type is ``virt= ``, - libvirt will automatically assign PCI addresses to devices; however, the - presence of a single device with virtio-mmio address in the guest - configuration will cause libvirt to assign virtio-mmio addresses to all - further devices. :since:`Since 3.0.0` -``isa`` - ISA addresses have the following additional attributes: ``iobase`` and - ``irq``. :since:`Since 1.2.1` -``unassigned`` - For PCI hostdevs, ``
`` allows the admin to - include a PCI hostdev in the domain XML definition, without making it - available for the guest. This allows for configurations in which Libvirt - manages the device as a regular PCI hostdev, regardless of whether the = guest - will have access to it. ``
`` is an invalid - address type for all other device types. :since:`Since 6.0.0` +.. include:: formatdomain-devices-address.rst :anchor:`` diff --git a/docs/meson.build b/docs/meson.build index e4e7cf4c89..e30f213739 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -126,6 +126,7 @@ docs_rst_files =3D [ 'includes': [ 'formatdomain-devices.rst', 'formatdomain-devices-disk.rst', 'formatdomain-devices-filesystem.rst', + 'formatdomain-devices-address.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2