[libvirt] [PATCHv2] nodedev: document virsh nodedev-* commands

Eric Blake eblake at redhat.com
Sat Sep 24 12:58:26 UTC 2011

This section of the man page was completely missing; I stumbled on
it when I had no clue that I had to use nodedev-reattach after
I was done playing with <hostdev> device passthrough to one of my

* tools/virsh.pod (NODEDEV COMMANDS): New section.
(attach-device, detach-device): Add cross-references.

v2: fix copy-and-paste botch that ruined the previous attempt,
add cross references for use of the nodedev commands

 tools/virsh.pod |   78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 78 insertions(+), 0 deletions(-)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 43ed1ea..ddf7578 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -1179,6 +1179,7 @@ Attach a device to the domain, using a device definition in an XML file.
 See the documentation to learn about libvirt XML format for a device.
 For cdrom and floppy devices, this command only replaces the media within
 the single existing device; consider using B<update-device> for this usage.
+For passthrough host devices, see also B<nodedev-dettach>.

 =item B<attach-disk> I<domain-id> I<source> I<target>
 [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>]
@@ -1220,6 +1221,7 @@ I<persistent> indicates the changes will affect the next boot of the domain.

 Detach a device from the domain, takes the same kind of XML descriptions
 as command B<attach-device>.
+For passthrough host devices, see also B<nodedev-reattach>.

 =item B<detach-disk> I<domain-id> I<target>

@@ -1244,6 +1246,82 @@ XML format for a device.


+The following commands manipulate host devices that are intended to be
+passed through to guest domains via <hostdev> elements in a domain's
+<devices> section.  A node device key is generally specified by the bus
+name followed by its address, using underscores between all components,
+such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
+The B<nodedev-list> gives the full list of host devices that are known
+to libvirt, although this includes devices that cannot be assigned to
+a guest (for example, attempting to detach the PCI device that controls
+the host's hard disk controller where the guest's disk images live could
+cause the host system to lock up or reboot).
+For more information on node device definition see:
+Passthrough devices cannot be simultaneously used by the host and its
+guest domains.  Attempts to use a passthrough <hostdev> for a guest may
+have the ability to behave as if B<nodedev-dettach> had been called,
+although making this call explicitly is safe.  Once a guest no longer
+needs a passthrough device, reversing the process so that the host can
+again use the device requires the explicit use of B<nodedev-reattach>.
+=over 4
+=item B<nodedev-create> I<FILE>
+Create a device on the host node that can then be assigned to virtual
+machines. Normally, libvirt is able to automatically determine which
+host nodes are available for use, but this allows registration of
+host hardware that libvirt did not automatically detect.  I<file>
+contains xml for a top-level <device> description of a node device.
+=item B<nodedev-destroy> I<nodedev>
+Destroy (stop) a device on the host.  Note that this makes libvirt
+quit managing a host device, and may even make that device unusable
+by the rest of the physical host until a reboot.
+=item B<nodedev-dettach> I<nodedev>
+Detach I<nodedev> from the host, so that it can safely be used by
+guests via <hostdev> passthrough.  This is reversed with
+=item B<nodedev-dumpxml> I<nodedev>
+Dump a <device> XML representation for the given node device, including
+such information as the device name, which bus owns the device, the
+vendor and product id, and any capabilities of the device usable by
+libvirt (such as whether device reset is supported).
+=item B<nodedev-list> I<cap> I<--tree>
+List all of the devices available on the node that are known by libvirt.
+If I<cap> is used, the list is filtered to show only the nodes that
+include the given capability.  If I<--tree> is used, the output is
+formatted in a tree representing parents of each node.
+=item B<nodedev-reattach> I<nodedev>
+Declare that I<nodedev> is no longer in use by any guests, and that
+the host can resume normal use of the device.  While libvirt can
+sometimes perform an implicit B<nodedev-dettach> when creating a
+guest, it currently requires an explicit B<nodedev-reattach> after
+the last guest use of the device before the host regains full control.
+=item B<nodedev-reset> I<nodedev>
+Trigger a device reset for I<nodedev>, useful prior to transferring
+a node device between guest passthrough or the host.  Libvirt will
+often do this action implicitly when required, but this command
+allows an explicit reset when needed.

 The following commands manipulate networks. Libvirt has the capability to

More information about the libvir-list mailing list