From nobody Sun Feb 8 21:48:07 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.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.133.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=1646927584; cv=none; d=zohomail.com; s=zohoarc; b=P4YGlc5QN1ulnpSUkvYWQ5t1cTMyx4KKg/sAXYD2WDdtO+UlnPYR3ChNoHm8+cSvLILVeTQF5dQsWZlGbPjW4ztFI0TbFQkYreWYzcn6LF/e9uRLslkJF6S4pi++vWMM4+hZjhZ255lsuRT8rgbv3nPTOElekjV0wZkWkebQF8Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927584; 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=1cIqJa/FDAvbZys6NbYd3d478M6NEsst3FrvTj7fi18=; b=Yn3HmM64sk1tljiag5BXWCCXJVO618qbd3G8EA6t/KYnFoATdLOK5sHBacl5B/TTaqeVdmBH7uyESKZKvrIIeoxZuBvDlP2A3ouvx36uf8VULHCGSA4wtwKcx+OgUwe7NdZkLsRqlEKrKhva+V7UxiOgXVON/b1N/90GTaqdqT0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.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.133.124]) by mx.zohomail.com with SMTPS id 1646927584168250.1197654815411; Thu, 10 Mar 2022 07:53:04 -0800 (PST) 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-573-4Y07ESsFMXmdOAH3GJvv4g-1; Thu, 10 Mar 2022 10:52:25 -0500 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9D54F1C068D7; Thu, 10 Mar 2022 15:52:23 +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 85428401E32; Thu, 10 Mar 2022 15:52:23 +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 4389A195FD66; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 089C51953576 for ; Thu, 10 Mar 2022 15:52:22 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id B5A957C029; Thu, 10 Mar 2022 15:52:21 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 11F587C02C for ; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927583; 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=1cIqJa/FDAvbZys6NbYd3d478M6NEsst3FrvTj7fi18=; b=g/O27hI20m+MgW4IeCe0itzrY2bIpDcGzQ54miT2Uz1ktJBgBZs2biwRDN7cNQuMj8vXh8 55BEFuiF3hO6Hdww5eKhmUBvM36zCSglzdwrOqZkeLNohUSx9Xn70TJZSBBesmLU0mlYj9 VkOP5tjGq+KTcHiXUDRD3hrVq2n4zGs= X-MC-Unique: 4Y07ESsFMXmdOAH3GJvv4g-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 6/8] docs: Convert 'pci-hotplug' page to rST Date: Thu, 10 Mar 2022 16:51:28 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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.85 on 10.11.54.10 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: 1646927585188100003 Content-Type: text/plain; charset="utf-8" One internal reference was modified to work properly. Signed-off-by: Peter Krempa --- docs/meson.build | 2 +- docs/pci-hotplug.html.in | 185 --------------------------------------- docs/pci-hotplug.rst | 146 ++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+), 186 deletions(-) delete mode 100644 docs/pci-hotplug.html.in create mode 100644 docs/pci-hotplug.rst diff --git a/docs/meson.build b/docs/meson.build index 3bdea1407d..cdf78a04b4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files =3D [ 'internals', 'java', 'logging', - 'pci-hotplug', 'php', 'python', 'remote', @@ -104,6 +103,7 @@ docs_rst_files =3D [ 'newreposetup', 'nss', 'pci-addresses', + 'pci-hotplug', 'platforms', 'programming-languages', 'securityprocess', diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in deleted file mode 100644 index d61af1930e..0000000000 --- a/docs/pci-hotplug.html.in +++ /dev/null @@ -1,185 +0,0 @@ - - - - -

PCI topology and hotplug

- -
    - -

    - Perhaps surprisingly, most libvirt guests support only limited PCI - device hotplug out of the box, or even none at all. -

    -

    - The reason for this apparent limitation is the fact that each - hotplugged PCI device might require additional PCI controllers to - be added to the guest. Since most PCI controllers can't be - hotplugged, they need to be added before the guest is started; - however, libvirt has no way of knowing in advance how many devices - will be hotplugged during the guest's lifetime, thus making it - impossible to automatically provide the right amount of PCI - controllers: any arbitrary number would end up being too big - for some users, and too small for others. -

    -

    - Ultimately, the user is the only one who knows how much the guest - will need to grow dynamically, so the responsibility of planning - a suitable PCI topology in advance falls on them. -

    -

    - This document aims at providing all the information needed to - successfully plan the PCI topology of a guest. Note that the - details can vary a lot between architectures and even machine - types, hence the way it's organized. -

    - -

    x86_64 architecture

    - -

    q35 machine type

    - -

    - This is a PCI Express native machine type. The default PCI topology - looks like -

    - -
    -<controller type=3D'pci' index=3D'0' model=3D'pcie-root'/>
-<controller type=3D'pci' index=3D'1' model=3D'pcie-root-port'>
-  <model name=3D'pcie-root-port'/>
-  <target chassis=3D'1' port=3D'0x10'/>
-  <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x01' fu=
nction=3D'0x0'/>
-</controller>
    - -

    - and supports hotplugging a single PCI Express device, either - emulated or assigned from the host. -

    -

    - If you have a very specific use case, such as the appliances - used by libguestfs behind - the scenes to access disk images, and this automatically-added - pcie-root-port controller ends up being a nuisance, - you can prevent libvirt from adding it by manually managing PCI - controllers and addresses according to your needs. -

    -

    - Slots on the pcie-root controller do not support - hotplug, so the device will be hotplugged into the - pcie-root-port controller. If you plan to hotplug - more than a single PCI Express device, you should add a suitable - number of pcie-root-port controllers when defining - the guest: for example, add -

    - -
    -<controller type=3D'pci' model=3D'pcie-root'/>
-<controller type=3D'pci' model=3D'pcie-root-port'/>
-<controller type=3D'pci' model=3D'pcie-root-port'/>
-<controller type=3D'pci' model=3D'pcie-root-port'/>
    - -

    - if you expect to hotplug up to three PCI Express devices, - either emulated or assigned from the host. That's all the - information you need to provide: libvirt will fill in the - remaining details automatically. Note that you need to add - the pcie-root controller along with the - pcie-root-port controllers or you will get an - error. -

    -

    - Note that if you're adding PCI controllers to a guest and at - the same time you're also adding PCI devices, some of the - controllers will be used for the newly-added devices and won't - be available for hotplug once the guest has been started. -

    -

    - If you expect to hotplug legacy PCI devices, then you will need - specialized controllers, since all those mentioned above are - intended for PCI Express devices only: add -

    - -
    -<controller type=3D'pci' model=3D'pcie-to-pci-bridge'/>
    - -

    - and you'll be able to hotplug up to 31 legacy PCI devices, - either emulated or assigned from the host, in the slots - from 0x01 to 0x1f of the pcie-to-pci-bridge controller. -

    - -

    i440fx (pc) machine type

    - -

    - This is a legacy PCI native machine type. The default PCI - topology looks like -

    - -
    -<controller type=3D'pci' index=3D'0' model=3D'pci-root'/>
    - -

    - where each of the 31 slots (from 0x01 to 0x1f) on the - pci-root controller is hotplug capable and - can accept a legacy PCI device, either emulated or - assigned from the guest. -

    - -

    ppc64 architecture

    - -

    pseries machine type

    - -

    - The default PCI topology for the pseries machine - type looks like -

    - -
    -<controller type=3D'pci' index=3D'0' model=3D'pci-root'>
-  <model name=3D'spapr-pci-host-bridge'/>
-  <target index=3D'0'/>
-</controller>
    - -

    - The 31 slots, from 0x01 to 0x1f, on a pci-root - controller are all hotplug capable and, despite the name - suggesting otherwise, starting with QEMU 2.9 all of them - can accept PCI Express devices in addition to legacy PCI - devices; however, libvirt will only place emulated devices - on the default pci-root controller. -

    -

    - In order to take advantage of improved error reporting and - recovering capabilities, PCI devices assigned from the - host need to be isolated by placing each on a separate - pci-root controller, which has to be prepared - in advance for hotplug to work: for example, add -

    - -
    -<controller type=3D'pci' model=3D'pci-root'/>
-<controller type=3D'pci' model=3D'pci-root'/>
-<controller type=3D'pci' model=3D'pci-root'/>
    - -

    - if you expect to hotplug up to three PCI devices assigned - from the host. -

    - -

    aarch64 architecture

    - -

    mach-virt (virt) machine type

    - -

    - This machine type mostly behaves the same as the - q35 machine type, so you can just - refer to that section for information. -

    -

    - The only difference worth mentioning is that using legacy - PCI for mach-virt guests is extremely uncommon, - so you'll probably never need to add controllers other than - pcie-root-port. -

    - - - diff --git a/docs/pci-hotplug.rst b/docs/pci-hotplug.rst new file mode 100644 index 0000000000..bc7fdbbd86 --- /dev/null +++ b/docs/pci-hotplug.rst @@ -0,0 +1,146 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +PCI topology and hotplug +=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:: + +Perhaps surprisingly, most libvirt guests support only limited PCI device +hotplug out of the box, or even none at all. + +The reason for this apparent limitation is the fact that each hotplugged P= CI +device might require additional PCI controllers to be added to the guest. = Since +most PCI controllers can't be hotplugged, they need to be added before the= guest +is started; however, libvirt has no way of knowing in advance how many dev= ices +will be hotplugged during the guest's lifetime, thus making it impossible = to +automatically provide the right amount of PCI controllers: any arbitrary n= umber +would end up being too big for some users, and too small for others. + +Ultimately, the user is the only one who knows how much the guest will nee= d to +grow dynamically, so the responsibility of planning a suitable PCI topolog= y in +advance falls on them. + +This document aims at providing all the information needed to successfully= plan +the PCI topology of a guest. Note that the details can vary a lot between +architectures and even machine types, hence the way it's organized. + +x86_64 architecture +------------------- + +q35 machine type +~~~~~~~~~~~~~~~~ + +This is a PCI Express native machine type. The default PCI topology looks = like + +:: + + + + + +
    + + +and supports hotplugging a single PCI Express device, either emulated or +assigned from the host. + +If you have a very specific use case, such as the appliances used by +`libguestfs `__ behind the scenes to access disk +images, and this automatically-added ``pcie-root-port`` controller ends up= being +a nuisance, you can prevent libvirt from adding it by manually managing PCI +controllers and addresses according to your needs. + +Slots on the ``pcie-root`` controller do not support hotplug, so the devic= e will +be hotplugged into the ``pcie-root-port`` controller. If you plan to hotpl= ug +more than a single PCI Express device, you should add a suitable number of +``pcie-root-port`` controllers when defining the guest: for example, add + +:: + + + + + + +if you expect to hotplug up to three PCI Express devices, either emulated = or +assigned from the host. That's all the information you need to provide: li= bvirt +will fill in the remaining details automatically. Note that you need to ad= d the +``pcie-root`` controller along with the ``pcie-root-port`` controllers or = you +will get an error. + +Note that if you're adding PCI controllers to a guest and at the same time +you're also adding PCI devices, some of the controllers will be used for t= he +newly-added devices and won't be available for hotplug once the guest has = been +started. + +If you expect to hotplug legacy PCI devices, then you will need specialized +controllers, since all those mentioned above are intended for PCI Express +devices only: add + +:: + + + +and you'll be able to hotplug up to 31 legacy PCI devices, either emulated= or +assigned from the host, in the slots from 0x01 to 0x1f of the +``pcie-to-pci-bridge`` controller. + +i440fx (pc) machine type +~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a legacy PCI native machine type. The default PCI topology looks l= ike + +:: + + + +where each of the 31 slots (from 0x01 to 0x1f) on the ``pci-root`` control= ler is +hotplug capable and can accept a legacy PCI device, either emulated or ass= igned +from the guest. + +ppc64 architecture +------------------ + +pseries machine type +~~~~~~~~~~~~~~~~~~~~ + +The default PCI topology for the ``pseries`` machine type looks like + +:: + + + + + + +The 31 slots, from 0x01 to 0x1f, on a ``pci-root`` controller are all hotp= lug +capable and, despite the name suggesting otherwise, starting with QEMU 2.9= all +of them can accept PCI Express devices in addition to legacy PCI devices; +however, libvirt will only place emulated devices on the default ``pci-roo= t`` +controller. + +In order to take advantage of improved error reporting and recovering +capabilities, PCI devices assigned from the host need to be isolated by pl= acing +each on a separate ``pci-root`` controller, which has to be prepared in ad= vance +for hotplug to work: for example, add + +:: + + + + + +if you expect to hotplug up to three PCI devices assigned from the host. + +aarch64 architecture +-------------------- + +mach-virt (virt) machine type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This machine type mostly behaves the same as the `q35 machine +type <#q35-machine-type>`__, so you can just refer to that section for +information. + +The only difference worth mentioning is that using legacy PCI for ``mach-v= irt`` +guests is extremely uncommon, so you'll probably never need to add control= lers +other than ``pcie-root-port``. --=20 2.35.1