From nobody Sun Feb 8 12:59:09 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1490792305107902.7965550556318; Wed, 29 Mar 2017 05:58:25 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 8325A8C54D; Wed, 29 Mar 2017 12:58:23 +0000 (UTC) Received: from colo-mx.corp.redhat.com (unknown [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5804685A5F; Wed, 29 Mar 2017 12:58:23 +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 030615EC63; Wed, 29 Mar 2017 12:58:23 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v2TCph9g010146 for ; Wed, 29 Mar 2017 08:51:43 -0400 Received: by smtp.corp.redhat.com (Postfix) id 69925962B8; Wed, 29 Mar 2017 12:51:43 +0000 (UTC) Received: from beluga.usersys.redhat.com (dhcp129-94.brq.redhat.com [10.34.129.94]) by smtp.corp.redhat.com (Postfix) with ESMTP id E76F2962BF; Wed, 29 Mar 2017 12:51:39 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 8325A8C54D Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=libvir-list-bounces@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 8325A8C54D From: Erik Skultety To: libvir-list@redhat.com Date: Wed, 29 Mar 2017 14:51:20 +0200 Message-Id: <2fb9f428fba2ad5eb535e3b0261f12bd6ff97b37.1490791809.git.eskultet@redhat.com> In-Reply-To: References: In-Reply-To: References: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: Erik Skultety Subject: [libvirt] [RFC PATCH 10/11] docs: Provide a nodedev driver stub documentation 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: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.30]); Wed, 29 Mar 2017 12:58:24 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" There's lot more to document about the nodedev driver, besides PCI and SR-IOV (even this might need to be extended), but let's start small-ish and at least have a page for it linked from the drivers.html. Signed-off-by: Erik Skultety --- docs/drivers.html.in | 6 +- docs/drvnodedev.html.in | 184 ++++++++++++++++++++++++++++++++++++++++++++= ++++ 2 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 docs/drvnodedev.html.in diff --git a/docs/drivers.html.in b/docs/drivers.html.in index be7483b9bc..61993861ee 100644 --- a/docs/drivers.html.in +++ b/docs/drivers.html.in @@ -4,7 +4,11 @@

Internal drivers

=20 -
    + =20

    The libvirt public API delegates its implementation to one or diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in new file mode 100644 index 0000000000..ed185c3df3 --- /dev/null +++ b/docs/drvnodedev.html.in @@ -0,0 +1,184 @@ + + + + +

    Host device management

    + +

    + Libvirt provides management of both physical and virtual host devices + (historically also referred to as node devices) like USB, PCI, SCSI,= and + network devices. This also includes various virtualization capabilit= ies + which the aforementioned devices provide for utilization, for example + SR-IOV, NPIV, MDEV, DRM, etc.
    +
    + The node device driver provides means to list and show details about= host + devices (virsh nodedev-list, + virsh nodedev-dumpxml), which are generic and can be us= ed + with all devices. It also provides means to create and destroy devic= es + (virsh nodedev-create, virsh nodedev-destroy) + which are meant to be used to create virtual devices, currently only + supported by NPIV + (more info = about NPIV)).
    +
    + Devices on the host system are arranged in a tree-like hierarchy, wi= th + the root node being called computer. The node device dr= iver + supports two backends to manage the devices, HAL and udev, with the = former + being deprecated in favour of the latter.
    + The generic format of a host device XML can be seen below. + To identify a device both within the host and the device tree hierar= chy, + the following elements are used: +

    +
    +
    name
    +
    + The device's name will be generated by libvirt using the subsyst= em, + like pci and the device's sysfs basename. +
    +
    path
    +
    + Fully qualified sysfs path to the device. +
    +
    parent
    +
    + This element identifies the parent node in the device hierarchy.= The + value of the element will correspond with the device parent's + name element or computer if the device= does + not have any parent. +
    +
    driver
    +
    + This elements reports the driver in use for this device. The pre= sence + of this element in the output XML depends on whether the underly= ing + device manager (most likely udev) exposes information about the + driver. +
    +
    capability
    +
    + Describes the device in terms of feature support. The element ha= s one + mandatory attribute type the value of which determi= nes + the type of the device. Currently recognized values for the attr= ibute + are: + system, + pci, + usb, + usb_device, + net, + scsi, + scsi_host (Since 0.4.7= ), + fc_host, + vports, + scsi_target (Since 0.7.3), + storage (Since 1.0.4), + scsi_generic (Since 1.0.7), + drm (Since 3.1.0), and + mdev (Since 3.2.0). + This element can be nested in which case it further specifies a + device's capability. Refer to specific device types to see more = values + for the type attribute which are exclusive. +
    +
    + +

    Basic structure of a node device

    + 
    +<device>
+  <name>pci_0000_00_17_0</name>
+  <path>/sys/devices/pci0000:00/0000:00:17.0</path>
+  <parent>computer</parent>
+  <driver>
+    <name>ahci</name>
+  </driver>
+  <capability type=3D'pci'>
+...
+  </capability>
+</device>
    + +
      + +

      PCI host devices

      +
      +
      capability
      +
      + When used as top level element, the supported values for the + type attribute are pci and + phys_function (see SR-IOV below= ). +
      +
      + 
      +<device>
+  <name>pci_0000_04_00_1</name>
+  <path>/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1</path&g=
t;
+  <parent>pci_0000_00_06_0</parent>
+  <driver>
+    <name>igb</name>
+  </driver>
+  <capability type=3D'pci'>
+    <domain>0</domain>
+    <bus>4</bus>
+    <slot>0</slot>
+    <function>1</function>
+    <product id=3D'0x10c9'>82576 Gigabit Network Connection</prod=
uct>
+    <vendor id=3D'0x8086'>Intel Corporation</vendor>
+    <iommuGroup number=3D'15'>
+      <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x00' function=3D=
'0x1'/>
+    </iommuGroup>
+    <numa node=3D'0'/>
+    <pci-express>
+      <link validity=3D'cap' port=3D'1' speed=3D'2.5' width=3D'2'/>
+      <link validity=3D'sta' speed=3D'2.5' width=3D'2'/>
+    </pci-express>
+  </capability>
+</device>
      + +

      + The XML format for a PCI device stays the same for any further + capabilities it supports, a single nested <capability> + element will be included for each capability the device supports. +

      + +

      SR-IOV capability

      +

      + Single root input/output virtualization (SR-IOV) allows sharing of t= he + PCIe resources by multiple virtual environments. That is achieved by + slicing up a single full-featured physical resource called physical + function (PF) into multiple devices called virtual functions (VFs) s= haring + their configuration with the underlying PF. Despite the SR-IOV + specification, the amount of VFs that can be created on a PF varies = among + manufacturers.
      +
      + Suppose the NIC above was also SR-IOV capable, = it would + also include a nested + <capability> element enumerating all virtual + functions available on the physical device (physical port) like in t= he + example below. +

      + + 
      +<capability type=3D'pci'>
+...
+  <capability type=3D'virt_functions' maxCount=3D'7'>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x10' function=3D'0=
x1'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x10' function=3D'0=
x3'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x10' function=3D'0=
x5'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x10' function=3D'0=
x7'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x11' function=3D'0=
x1'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x11' function=3D'0=
x3'/>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x11' function=3D'0=
x5'/>
+  </capability>
+...
+</capability>
      +

      + A SR-IOV child device on the other hand, would then report its top l= evel + capability type as a physical function instead: +

      + + 
      +<device>
+...
+  <capability type=3D'phys_function'>
+    <address domain=3D'0x0000' bus=3D'0x04' slot=3D'0x00' function=3D'0=
x0'/>
+  </capability>
+...
+<device>
      + + + --=20 2.12.2 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list