7:58 a.m.
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
guests.
* 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.
=back
+=head1 NODEDEV COMMANDS
+
+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:
+L<http://libvirt.org/formatnode.html>.
+
+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
+B<nodedev-reattach>.
+
+=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.
+
+=back
+
=head1 VIRTUAL NETWORK COMMANDS
The following commands manipulate networks. Libvirt has the capability to
--
1.7.4.4