[Qemu-devel] [PATCH 2/2] Add boot index documentation.

[Gleb Natapov <gleb@redhat.com>]

---
 docs/bootindex.txt |   42 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 42 insertions(+), 0 deletions(-)
 create mode 100644 docs/bootindex.txt

diff --git a/docs/bootindex.txt b/docs/bootindex.txt
new file mode 100644
index 0000000..9609c7f
--- /dev/null
+++ b/docs/bootindex.txt
@@ -0,0 +1,42 @@
+= Bootindex property =
+
+Block and net devices have bootindex property. This property is used to
+determine the order in which firmware will consider devices for booting
+guest OS. If bootindex property is not set for a device it gets lowest
+boot priority. There is no particular order in which devices with unset
+bootindex property will be considered for booting, but they will still be
+bootable.
+
+== Example ==
+
+Lets assume we have QEMU machine with two NICs (virtio, e1000) and two
+disks (IDE, virtio):
+
+qemu -drive file=disk1.img,if=none,id=disk1
+     -device ide-drive,drive=disk1,bootindex=4
+     -drive file=disk2.img,if=none,id=disk2
+     -device virtio-blk-pci,drive=disk2,bootindex=3
+     -netdev type=user,id=net0 -device virtio-net-pci,netdev=net0,bootindex=2
+     -netdev type=user,id=net1 -device e1000,netdev=net1,bootindex=1
+
+Given command like above firmware should try to boot guest OS from e1000
+NIC if this fails it should try virtio NIC next, if this fails too it
+should try virtio disk and then IDE disk.
+
+== Limitations ==
+
+1. Some firmware has limitation on order in which devices can be
+considered for booting. For instance PC bios boot specification allows
+only one disk to be bootable. If boot from disk fails for some reason
+bios cannot retry booting from other disk. It still can try to boot from
+floppy or net though.
+
+2. Sometimes firmware cannot map device path QEMU wants firmware to boot
+from to boot method. It doesn't happen for devices firmware can natively
+boot from, but if firmware relies on option rom for booting, and same
+option rom is used for booting from more then one device, firmware may
+not be able to ask option rom to boot from particular device reliably.
+For instance with PC bios if scsi HBA has three bootable devices target1,
+target3, target5, connected to it option rom will create boot method for
+each of them, but it is not possible to map boot method back to specific
+target. This is a shortcoming of PC bios boot specification.
-- 
1.7.2.3