diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/bootindex.txt | 52 | ||||
| -rw-r--r-- | docs/system/bootindex.rst | 76 | ||||
| -rw-r--r-- | docs/system/index.rst | 1 |
3 files changed, 77 insertions, 52 deletions
diff --git a/docs/bootindex.txt b/docs/bootindex.txt deleted file mode 100644 index 6937862..0000000 --- a/docs/bootindex.txt +++ /dev/null @@ -1,52 +0,0 @@ -= 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 -the guest OS. If the 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 == - -Let's assume we have a QEMU machine with two NICs (virtio, e1000) and two -disks (IDE, virtio): - -qemu -drive file=disk1.img,if=none,id=disk1 - -device ide-hd,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 the command above, firmware should try to boot from the e1000 NIC -first. If this fails, it should try the virtio NIC next; if this fails -too, it should try the virtio disk, and then the IDE disk. - -== Limitations == - -1. Some firmware has limitations on which devices can be considered for -booting. For instance, the PC BIOS boot specification allows only one -disk to be bootable. If boot from disk fails for some reason, the BIOS -won't retry booting from other disk. It can still try to boot from -floppy or net, though. - -2. Sometimes, firmware cannot map the device path QEMU wants firmware to -boot from to a boot method. It doesn't happen for devices the firmware -can natively boot from, but if firmware relies on an option ROM for -booting, and the same option ROM is used for booting from more then one -device, the firmware may not be able to ask the option ROM to boot from -a particular device reliably. For instance with the PC BIOS, if a SCSI HBA -has three bootable devices target1, target3, target5 connected to it, -the option ROM will have a boot method for each of them, but it is not -possible to map from boot method back to a specific target. This is a -shortcoming of the PC BIOS boot specification. - -== Mixing bootindex and boot order parameters == - -Note that it does not make sense to use the bootindex property together -with the "-boot order=..." (or "-boot once=...") parameter. The guest -firmware implementations normally either support the one or the other, -but not both parameters at the same time. Mixing them will result in -undefined behavior, and thus the guest firmware will likely not boot -from the expected devices. diff --git a/docs/system/bootindex.rst b/docs/system/bootindex.rst new file mode 100644 index 0000000..8b057f8 --- /dev/null +++ b/docs/system/bootindex.rst @@ -0,0 +1,76 @@ +Managing device boot order with bootindex properties +==================================================== + +QEMU can tell QEMU-aware guest firmware (like the x86 PC BIOS) +which order it should look for a bootable OS on which devices. +A simple way to set this order is to use the ``-boot order=`` option, +but you can also do this more flexibly, by setting a ``bootindex`` +property on the individual block or net devices you specify +on the QEMU command line. + +The ``bootindex`` properties are used to determine the order in which +firmware will consider devices for booting the guest OS. If the +``bootindex`` property is not set for a device, it gets the lowest +boot priority. There is no particular order in which devices with no +``bootindex`` property set will be considered for booting, but they +will still be bootable. + +Some guest machine types (for instance the s390x machines) do +not support ``-boot order=``; on those machines you must always +use ``bootindex`` properties. + +There is no way to set a ``bootindex`` property if you are using +a short-form option like ``-hda`` or ``-cdrom``, so to use +``bootindex`` properties you will need to expand out those options +into long-form ``-drive`` and ``-device`` option pairs. + +Example +------- + +Let's assume we have a QEMU machine with two NICs (virtio, e1000) and two +disks (IDE, virtio): + +.. parsed-literal:: + + |qemu_system| -drive file=disk1.img,if=none,id=disk1 \\ + -device ide-hd,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 the command above, firmware should try to boot from the e1000 NIC +first. If this fails, it should try the virtio NIC next; if this fails +too, it should try the virtio disk, and then the IDE disk. + +Limitations +----------- + +Some firmware has limitations on which devices can be considered for +booting. For instance, the PC BIOS boot specification allows only one +disk to be bootable. If boot from disk fails for some reason, the BIOS +won't retry booting from other disk. It can still try to boot from +floppy or net, though. + +Sometimes, firmware cannot map the device path QEMU wants firmware to +boot from to a boot method. It doesn't happen for devices the firmware +can natively boot from, but if firmware relies on an option ROM for +booting, and the same option ROM is used for booting from more then one +device, the firmware may not be able to ask the option ROM to boot from +a particular device reliably. For instance with the PC BIOS, if a SCSI HBA +has three bootable devices target1, target3, target5 connected to it, +the option ROM will have a boot method for each of them, but it is not +possible to map from boot method back to a specific target. This is a +shortcoming of the PC BIOS boot specification. + +Mixing bootindex and boot order parameters +------------------------------------------ + +Note that it does not make sense to use the bootindex property together +with the ``-boot order=...`` (or ``-boot once=...``) parameter. The guest +firmware implementations normally either support the one or the other, +but not both parameters at the same time. Mixing them will result in +undefined behavior, and thus the guest firmware will likely not boot +from the expected devices. diff --git a/docs/system/index.rst b/docs/system/index.rst index 64a424a..650409d 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -26,6 +26,7 @@ or Hypervisor.Framework. authz gdb managed-startup + bootindex cpu-hotplug pr-manager targets |