[libvirt] [PATCH] docs: Enhance documentation of the old-style boot configuration

Also encourages people to use per-device boot elements for better control. --- docs/formatdomain.html.in | 22 +++++++++++++++++----- 1 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 6bf64a6..ff09113 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -131,12 +131,24 @@ <dd>The <code>dev</code> attribute takes one of the values "fd", "hd", "cdrom" or "network" and is used to specify the next boot device to consider. The <code>boot</code> element can be repeated multiple - times to setup a priority list of boot devices to try in turn. The - <code>boot</code> element cannot be used if per-device boot elements - are used (see <a href="#elementsDisks">disks</a>, + times to setup a priority list of boot devices to try in turn. + Multiple devices of the same type are sorted according to their + targets while preserving the order of buses. After defining the + domain, its XML configuration returned by libvirt (through + virDomainGetXMLDesc) lists devices in the sorted order. Once sorted, + the first device is marked as bootable. Thus, e.g., a domain + configured to boot from "hd" with vdb, hda, vda, and hdc disks + assigned to it will boot from vda (the sorted list is vda, vdb, hda, + hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from + hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to + configure in the desired way, which is why per-device boot elements + (see <a href="#elementsDisks">disks</a>, <a href="#elementsNICS">network interfaces</a>, and - <a href="#elementsUSB">USB and PCI devices</a> sections below). - <span class="since">Since 0.1.3, per-device boot since 0.8.8</span> + <a href="#elementsUSB">USB and PCI devices</a> sections below) were + introduced and they are the preferred way providing full control over + booting order. The <code>boot</code> element and per-device boot + elements are mutually exclusive. <span class="since">Since 0.1.3, + per-device boot since 0.8.8</span> </dd> <dt><code>bootmenu</code></dt> <dd> Whether or not to enable an interactive boot menu prompt on guest -- 1.7.8.4