Annotation of qemu/docs/bootindex.txt, revision

1.1       root        1: = Bootindex propery =
                      3: Block and net devices have bootindex property. This property is used to
                      4: determine the order in which firmware will consider devices for booting
                      5: the guest OS. If the bootindex property is not set for a device, it gets
                      6: lowest boot priority. There is no particular order in which devices with
                      7: unset bootindex property will be considered for booting, but they will
                      8: still be bootable.
                     10: == Example ==
                     12: Lets assume we have QEMU machine with two NICs (virtio, e1000) and two
                     13: disks (IDE, virtio):
                     15: qemu -drive file=disk1.img,if=none,id=disk1
                     16:      -device ide-drive,drive=disk1,bootindex=4
                     17:      -drive file=disk2.img,if=none,id=disk2
                     18:      -device virtio-blk-pci,drive=disk2,bootindex=3
                     19:      -netdev type=user,id=net0 -device virtio-net-pci,netdev=net0,bootindex=2
                     20:      -netdev type=user,id=net1 -device e1000,netdev=net1,bootindex=1
                     22: Given the command above, firmware should try to boot from the e1000 NIC
                     23: first.  If this fails, it should try the virtio NIC next, if this fails
                     24: too, it should try the virtio disk, and then the IDE disk.
                     26: == Limitations ==
                     28: 1. Some firmware has limitations on which devices can be considered for
                     29: booting.  For instance, the PC BIOS boot specification allows only one
                     30: disk to be bootable.  If boot from disk fails for some reason, the BIOS
                     31: won't retry booting from other disk.  It still can try to boot from
                     32: floppy or net, though.
                     34: 2. Sometimes, firmware cannot map the device path QEMU wants firmware to
                     35: boot from to a boot method.  It doesn't happen for devices the firmware
                     36: can natively boot from, but if firmware relies on an option ROM for
                     37: booting, and the same option ROM is used for booting from more then one
                     38: device, the firmware may not be able to ask the option ROM to boot from
                     39: a particular device reliably.  For instance with PC BIOS, if a SCSI HBA
                     40: has three bootable devices target1, target3, target5 connected to it,
                     41: the option ROM will have a boot method for each of them, but it is not
                     42: possible to map from boot method back to a specific target.  This is a
                     43: shortcoming of PC BIOS boot specification.