From beeab55908e28a9e57461f660daaa822b5fc870f Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Fri, 23 Sep 2011 17:26:24 -0600 Subject: [PATCH] docs: document virsh nodedev-* commands 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 device passthrough to one of my guests. * tools/virsh.pod (NODEDEV COMMANDS): New section. (attach-device, detach-device): Add cross-references. --- tools/virsh.pod | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/tools/virsh.pod b/tools/virsh.pod index a01d723c4f..c0bb2745e4 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -1200,6 +1200,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 for this usage. +For passthrough host devices, see also B. =item B I I I [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] @@ -1241,6 +1242,7 @@ I 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. +For passthrough host devices, see also B. =item B I I @@ -1265,6 +1267,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 elements in a domain's + 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 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. + +Passthrough devices cannot be simultaneously used by the host and its +guest domains. Attempts to use a passthrough for a guest may +have the ability to behave as if B 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. + +=over 4 + +=item B I + +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 +contains xml for a top-level description of a node device. + +=item B I + +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 I + +Detach I from the host, so that it can safely be used by +guests via passthrough. This is reversed with +B. + +=item B I + +Dump a 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 I I<--tree> + +List all of the devices available on the node that are known by libvirt. +If I 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 I + +Declare that I 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 when creating a +guest, it currently requires an explicit B after +the last guest use of the device before the host regains full control. + +=item B I + +Trigger a device reset for I, 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 -- 2.39.5