| 1 | Boot devices on s390x |
| 2 | ===================== |
| 3 | |
| 4 | Booting with bootindex parameter |
| 5 | -------------------------------- |
| 6 | |
| 7 | For classical mainframe guests (i.e. LPAR or z/VM installations), you always |
| 8 | have to explicitly specify the disk where you want to boot from (or "IPL" from, |
| 9 | in s390x-speak -- IPL means "Initial Program Load"). |
| 10 | |
| 11 | So for booting an s390x guest in QEMU, you should always mark the |
| 12 | device where you want to boot from with the ``bootindex`` property, for |
| 13 | example:: |
| 14 | |
| 15 | qemu-system-s390x -drive if=none,id=dr1,file=guest.qcow2 \ |
| 16 | -device virtio-blk,drive=dr1,bootindex=1 |
| 17 | |
| 18 | Multiple devices may have a bootindex. The lowest bootindex is assigned to the |
| 19 | device to IPL first. If the IPL fails for the first, the device with the second |
| 20 | lowest bootindex will be tried and so on until IPL is successful or there are no |
| 21 | remaining boot devices to try. |
| 22 | |
| 23 | For booting from a CD-ROM ISO image (which needs to include El-Torito boot |
| 24 | information in order to be bootable), it is recommended to specify a ``scsi-cd`` |
| 25 | device, for example like this:: |
| 26 | |
| 27 | qemu-system-s390x -blockdev file,node-name=c1,filename=... \ |
| 28 | -device virtio-scsi \ |
| 29 | -device scsi-cd,drive=c1,bootindex=1 |
| 30 | |
| 31 | Note that you really have to use the ``bootindex`` property to select the |
| 32 | boot device. The old-fashioned ``-boot order=...`` command of QEMU (and |
| 33 | also ``-boot once=...``) is not supported on s390x. |
| 34 | |
| 35 | |
| 36 | Booting without bootindex parameter |
| 37 | ----------------------------------- |
| 38 | |
| 39 | The QEMU guest firmware (the so-called s390-ccw bios) has also some rudimentary |
| 40 | support for scanning through the available block devices. So in case you did |
| 41 | not specify a boot device with the ``bootindex`` property, there is still a |
| 42 | chance that it finds a bootable device on its own and starts a guest operating |
| 43 | system from it. However, this scanning algorithm is still very rough and may |
| 44 | be incomplete, so that it might fail to detect a bootable device in many cases. |
| 45 | It is really recommended to always specify the boot device with the |
| 46 | ``bootindex`` property instead. |
| 47 | |
| 48 | This also means that you should avoid the classical short-cut commands like |
| 49 | ``-hda``, ``-cdrom`` or ``-drive if=virtio``, since it is not possible to |
| 50 | specify the ``bootindex`` with these commands. Note that the convenience |
| 51 | ``-cdrom`` option even does not give you a real (virtio-scsi) CD-ROM device on |
| 52 | s390x. Due to technical limitations in the QEMU code base, you will get a |
| 53 | virtio-blk device with this parameter instead, which might not be the right |
| 54 | device type for installing a Linux distribution via ISO image. It is |
| 55 | recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned |
| 56 | above) instead. |
| 57 | |
| 58 | |
| 59 | Selecting kernels with the ``loadparm`` property |
| 60 | ------------------------------------------------ |
| 61 | |
| 62 | The ``s390-ccw-virtio`` machine supports the so-called ``loadparm`` parameter |
| 63 | which can be used to select the kernel on the disk of the guest that the |
| 64 | s390-ccw bios should boot. When starting QEMU, it can be specified like this:: |
| 65 | |
| 66 | qemu-system-s390x -machine s390-ccw-virtio,loadparm=<string> |
| 67 | |
| 68 | The first way to use this parameter is to use the word ``PROMPT`` as the |
| 69 | ``<string>`` here. In that case the s390-ccw bios will show a list of |
| 70 | installed kernels on the disk of the guest and ask the user to enter a number |
| 71 | to chose which kernel should be booted -- similar to what can be achieved by |
| 72 | specifying the ``-boot menu=on`` option when starting QEMU. Note that the menu |
| 73 | list will only show the names of the installed kernels when using a DASD-like |
| 74 | disk image with 4k byte sectors. On normal SCSI-style disks with 512-byte |
| 75 | sectors, there is not enough space for the zipl loader on the disk to store |
| 76 | the kernel names, so you only get a list without names here. |
| 77 | |
| 78 | The second way to use this parameter is to use a number in the range from 0 |
| 79 | to 31. The numbers that can be used here correspond to the numbers that are |
| 80 | shown when using the ``PROMPT`` option, and the s390-ccw bios will then try |
| 81 | to automatically boot the kernel that is associated with the given number. |
| 82 | Note that ``0`` can be used to boot the default entry. If the machine |
| 83 | ``loadparm`` is not assigned a value, then the default entry is used. |
| 84 | |
| 85 | By default, the machine ``loadparm`` applies to all boot devices. If multiple |
| 86 | devices are assigned a ``bootindex`` and the ``loadparm`` is to be different |
| 87 | between them, an independent ``loadparm`` may be assigned on a per-device basis. |
| 88 | |
| 89 | An example guest using per-device ``loadparm``:: |
| 90 | |
| 91 | qemu-system-s390x -drive if=none,id=dr1,file=primary.qcow2 \ |
| 92 | -device virtio-blk,drive=dr1,bootindex=1 \ |
| 93 | -drive if=none,id=dr2,file=secondary.qcow2 \ |
| 94 | -device virtio-blk,drive=dr2,bootindex=2,loadparm=3 |
| 95 | |
| 96 | In this case, the primary boot device will attempt to IPL using the default |
| 97 | entry (because no ``loadparm`` is specified for this device or for the |
| 98 | machine). If that device fails to boot, the secondary device will attempt to |
| 99 | IPL using entry number 3. |
| 100 | |
| 101 | If a ``loadparm`` is specified on both the machine and a device, the per-device |
| 102 | value will superseded the machine value. Per-device ``loadparm`` values are |
| 103 | only used for devices with an assigned ``bootindex``. The machine ``loadparm`` |
| 104 | is used when attempting to boot without a ``bootindex``. |
| 105 | |
| 106 | |
| 107 | Booting from a network device |
| 108 | ----------------------------- |
| 109 | |
| 110 | The firmware that ships with QEMU includes a small TFTP network bootloader |
| 111 | for virtio-net-ccw devices. The ``bootindex`` property is especially |
| 112 | important for booting via the network. If you don't specify the ``bootindex`` |
| 113 | property here, the network bootloader won't be taken into consideration and |
| 114 | the network boot will fail. For a successful network boot, try something |
| 115 | like this:: |
| 116 | |
| 117 | qemu-system-s390x -netdev user,id=n1,tftp=...,bootfile=... \ |
| 118 | -device virtio-net-ccw,netdev=n1,bootindex=1 |
| 119 | |
| 120 | The network bootloader also has basic support for pxelinux.cfg-style |
| 121 | configuration files. See the `PXELINUX Configuration page |
| 122 | <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration>`__ |
| 123 | for details how to set up the configuration file on your TFTP server. |
| 124 | The supported configuration file entries are ``DEFAULT``, ``LABEL``, |
| 125 | ``KERNEL``, ``INITRD`` and ``APPEND`` (see the `Syslinux Config file syntax |
| 126 | <https://wiki.syslinux.org/wiki/index.php?title=Config>`__ for more |
| 127 | information). |