Skip to contentSkip to conversation

docs/system/s390x: Document the "loadparm" machine property

PATCH In review Thomas Huth 3 participants 4 messages Nov 15, 2022

lore
Share & tools
lore
Reviewed-by on v1 1/1
#1 lore raw
In reply to Thomas Huth
Quoted 6 lines · On Mon, 14 Nov 2022 14:25:02 +0100 Thomas Huth <[email protected]> wrote:

The "loadparm" machine property is useful for selecting alternative kernels on the disk of the guest, but so far we do not tell the users yet how to use it. Add some documentation to fill this gap.

Quoted 41 lines
---
 docs/system/s390x/bootdevices.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
docs/system/s390x/bootdevices.rst +26 -0
index b5950133e8..40089c35a9 100644
@@ -53,6 +53,32 @@ recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned
 above) instead.
 
 
+Selecting kernels with the ``loadparm`` property
+------------------------------------------------
+
+The ``s390-ccw-virtio`` machine supports the so-called ``loadparm`` parameter
+which can be used to select the kernel on the disk of the guest that the
+s390-ccw bios should boot. When starting QEMU, it can be specified like this::
+
+ qemu-system-s390x -machine s390-ccw-virtio,loadparm=<string>
+
+The first way to use this parameter is to use the word ``PROMPT`` as the
+``<string>`` here. In that case the s390-ccw bios will show a list of
+installed kernels on the disk of the guest and ask the user to enter a number
+to chose which kernel should be booted -- similar to what can be achieved by
+specifying the ``-boot menu=on`` option when starting QEMU. Note that the menu
+list will only show the names of the installed kernels when using a DASD-like
+disk image with 4k byte sectors, on normal SCSI-style disks with 512-byte
+sectors, there is not enough space for the zipl loader on the disk to store
+the kernel names, so you only get a list without names here.
+
+The second way to use this parameter is to use a number in the range from 0
+to 31. The numbers that can be used here correspond to the numbers that are
+shown when using the ``PROMPT`` option, and the s390-ccw bios will then try
+to automatically boot the kernel that is associated with the given number.
+Note that ``0`` can be used to boot the default entry.
+
+
 Booting from a network device
 -----------------------------
 
#0 lore raw

PATCH 1/1 docs/system/s390x: Document the "loadparm" machine property

The "loadparm" machine property is useful for selecting alternative kernels on the disk of the guest, but so far we do not tell the users yet how to use it. Add some documentation to fill this gap.

---
 docs/system/s390x/bootdevices.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
docs/system/s390x/bootdevices.rst +26 -0
index b5950133e8..40089c35a9 100644
@@ -53,6 +53,32 @@ recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned
 above) instead.
 
 
+Selecting kernels with the ``loadparm`` property
+------------------------------------------------
+
+The ``s390-ccw-virtio`` machine supports the so-called ``loadparm`` parameter
+which can be used to select the kernel on the disk of the guest that the
+s390-ccw bios should boot. When starting QEMU, it can be specified like this::
+
+ qemu-system-s390x -machine s390-ccw-virtio,loadparm=<string>
+
+The first way to use this parameter is to use the word ``PROMPT`` as the
+``<string>`` here. In that case the s390-ccw bios will show a list of
+installed kernels on the disk of the guest and ask the user to enter a number
+to chose which kernel should be booted -- similar to what can be achieved by
+specifying the ``-boot menu=on`` option when starting QEMU. Note that the menu
+list will only show the names of the installed kernels when using a DASD-like
+disk image with 4k byte sectors, on normal SCSI-style disks with 512-byte
+sectors, there is not enough space for the zipl loader on the disk to store
+the kernel names, so you only get a list without names here.
+
+The second way to use this parameter is to use a number in the range from 0
+to 31. The numbers that can be used here correspond to the numbers that are
+shown when using the ``PROMPT`` option, and the s390-ccw bios will then try
+to automatically boot the kernel that is associated with the given number.
+Note that ``0`` can be used to boot the default entry.
+
+
 Booting from a network device
 -----------------------------
 
Signature · 1 line
2.31.1
#2 lore raw
Quoted 26 lines · Thomas Huth

The "loadparm" machine property is useful for selecting alternative kernels on the disk of the guest, but so far we do not tell the users yet how to use it. Add some documentation to fill this gap.

---
  docs/system/s390x/bootdevices.rst | 26 ++++++++++++++++++++++++++
  1 file changed, 26 insertions(+)
docs/system/s390x/bootdevices.rst +8 -0
index b5950133e8..40089c35a9 100644
@@ -53,6 +53,32 @@ recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned
  above) instead.
 
 
+Selecting kernels with the ``loadparm`` property
+------------------------------------------------
+
+The ``s390-ccw-virtio`` machine supports the so-called ``loadparm`` parameter
+which can be used to select the kernel on the disk of the guest that the
+s390-ccw bios should boot. When starting QEMU, it can be specified like this::
+
+ qemu-system-s390x -machine s390-ccw-virtio,loadparm=<string>

docs/system/s390x/bootdevices.rst recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned · line 73

Quoted 10 lines
docs/system/s390x/bootdevices.rst +10 -0
+
+The first way to use this parameter is to use the word ``PROMPT`` as the
+``<string>`` here. In that case the s390-ccw bios will show a list of
+installed kernels on the disk of the guest and ask the user to enter a number
+to chose which kernel should be booted -- similar to what can be achieved by
+specifying the ``-boot menu=on`` option when starting QEMU. Note that the menu
+list will only show the names of the installed kernels when using a DASD-like
+disk image with 4k byte sectors, on normal SCSI-style disks with 512-byte
+sectors, there is not enough space for the zipl loader on the disk to store
+the kernel names, so you only get a list without names here.

I'd suggest splitting the last sentence into two so there's a clear separation between DASD and SCSI.

Quoted 11 lines
docs/system/s390x/bootdevices.rst +8 -0
+
+The second way to use this parameter is to use a number in the range from 0
+to 31. The numbers that can be used here correspond to the numbers that are
+shown when using the ``PROMPT`` option, and the s390-ccw bios will then try
+to automatically boot the kernel that is associated with the given number.
+Note that ``0`` can be used to boot the default entry.
+
+
  Booting from a network device
  -----------------------------
 
#3 lore raw
Quoted 35 lines · Janosch Frank
Quoted 34 lines · Thomas Huth

The "loadparm" machine property is useful for selecting alternative kernels on the disk of the guest, but so far we do not tell the users yet how to use it. Add some documentation to fill this gap.

---
  docs/system/s390x/bootdevices.rst | 26 ++++++++++++++++++++++++++

  1 file changed, 26 insertions(+)
docs/system/s390x/bootdevices.rst +0 -0
index b5950133e8..40089c35a9 100644
@@ -53,6 +53,32 @@ recommended to specify a CD-ROM device via ``-device 

scsi-cd`` (as mentioned
  above) instead.

docs/system/s390x/bootdevices.rst +4 -0
+Selecting kernels with the ``loadparm`` property
+------------------------------------------------
+
+The ``s390-ccw-virtio`` machine supports the so-called ``loadparm`` 

parameter

docs/system/s390x/bootdevices.rst +2 -0
+which can be used to select the kernel on the disk of the guest that the
+s390-ccw bios should boot. When starting QEMU, it can be specified like 

this::

docs/system/s390x/bootdevices.rst +6 -0
+
+ qemu-system-s390x -machine s390-ccw-virtio,loadparm=<string>
+
+The first way to use this parameter is to use the word ``PROMPT`` as the
+``<string>`` here. In that case the s390-ccw bios will show a list of
+installed kernels on the disk of the guest and ask the user to enter a 

number

docs/system/s390x/bootdevices.rst +2 -0
+to chose which kernel should be booted -- similar to what can be achieved by
+specifying the ``-boot menu=on`` option when starting QEMU. Note that the 
Quoted 8 lines

docs/system/s390x/bootdevices.rst recommended to specify a CD-ROM device via ``-device scsi-cd`` (as mentioned · line 73

Quoted 6 lines

menu
+list will only show the names of the installed kernels when using a DASD-like

docs/system/s390x/bootdevices.rst +3 -0
+disk image with 4k byte sectors, on normal SCSI-style disks with 512-byte
+sectors, there is not enough space for the zipl loader on the disk to store
+the kernel names, so you only get a list without names here.

I'd suggest splitting the last sentence into two so there's a clear separation between DASD and SCSI.

Yes, makes sense, I'll replace the "," with a "." there.

Thomas