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