mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: rstfy s390 dasd ipl documentation

Browse Source 
While at it, also fix the numbering in 'What QEMU does'.

Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20200213162942.14177-2-cohuck@redhat.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
This commit is contained in:
Cornelia Huck 2020-01-28 13:24:14 +01:00
parent 8b51c0961c
commit cc3d15a5ea
3 changed files with 63 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
MAINTAINERS
View File

@ -1259,7 +1259,7 @@ S: Supported
F: hw/s390x/ipl.* F: hw/s390x/ipl.*
F: pc-bios/s390-ccw/ F: pc-bios/s390-ccw/
F: pc-bios/s390-ccw.img F: pc-bios/s390-ccw.img
F: docs/devel/s390-dasd-ipl.txt F: docs/devel/s390-dasd-ipl.rst
T: git https://github.com/borntraeger/qemu.git s390-next T: git https://github.com/borntraeger/qemu.git s390-next
L: qemu-s390x@nongnu.org L: qemu-s390x@nongnu.org

1
docs/devel/index.rst
View File

@ -25,3 +25,4 @@ Contents:
tcg-plugins tcg-plugins
bitops bitops
reset reset
s390-dasd-ipl

117
docs/devel/s390-dasd-ipl.txt → docs/devel/s390-dasd-ipl.rst
View File

@ -1,49 +1,55 @@
***************************** Booting from real channel-attached devices on s390x
***** s390 hardware IPL ***** ===================================================
*****************************
s390 hardware IPL
-----------------
The s390 hardware IPL process consists of the following steps. The s390 hardware IPL process consists of the following steps.
1. A READ IPL ccw is constructed in memory location 0x0. 1. A READ IPL ccw is constructed in memory location ``0x0``.
This ccw, by definition, reads the IPL1 record which is located on the disk This ccw, by definition, reads the IPL1 record which is located on the disk
at cylinder 0 track 0 record 1. Note that the chain flag is on in this ccw at cylinder 0 track 0 record 1. Note that the chain flag is on in this ccw
so when it is complete another ccw will be fetched and executed from memory so when it is complete another ccw will be fetched and executed from memory
location 0x08. location ``0x08``.
2. Execute the Read IPL ccw at 0x00, thereby reading IPL1 data into 0x00. 2. Execute the Read IPL ccw at ``0x00``, thereby reading IPL1 data into ``0x00``.
IPL1 data is 24 bytes in length and consists of the following pieces of IPL1 data is 24 bytes in length and consists of the following pieces of
information: [psw][read ccw][tic ccw]. When the machine executes the Read information: ``[psw][read ccw][tic ccw]``. When the machine executes the Read
IPL ccw it read the 24-bytes of IPL1 to be read into memory starting at IPL ccw it read the 24-bytes of IPL1 to be read into memory starting at
location 0x0. Then the ccw program at 0x08 which consists of a read location ``0x0``. Then the ccw program at ``0x08`` which consists of a read
ccw and a tic ccw is automatically executed because of the chain flag from ccw and a tic ccw is automatically executed because of the chain flag from
the original READ IPL ccw. The read ccw will read the IPL2 data into memory the original READ IPL ccw. The read ccw will read the IPL2 data into memory
and the TIC (Transfer In Channel) will transfer control to the channel and the TIC (Transfer In Channel) will transfer control to the channel
program contained in the IPL2 data. The TIC channel command is the program contained in the IPL2 data. The TIC channel command is the
equivalent of a branch/jump/goto instruction for channel programs. equivalent of a branch/jump/goto instruction for channel programs.
NOTE: The ccws in IPL1 are defined by the architecture to be format 0.
NOTE: The ccws in IPL1 are defined by the architecture to be format 0.
3. Execute IPL2. 3. Execute IPL2.
The TIC ccw instruction at the end of the IPL1 channel program will begin The TIC ccw instruction at the end of the IPL1 channel program will begin
the execution of the IPL2 channel program. IPL2 is stage-2 of the boot the execution of the IPL2 channel program. IPL2 is stage-2 of the boot
process and will contain a larger channel program than IPL1. The point of process and will contain a larger channel program than IPL1. The point of
IPL2 is to find and load either the operating system or a small program that IPL2 is to find and load either the operating system or a small program that
loads the operating system from disk. At the end of this step all or some of loads the operating system from disk. At the end of this step all or some of
the real operating system is loaded into memory and we are ready to hand the real operating system is loaded into memory and we are ready to hand
control over to the guest operating system. At this point the guest control over to the guest operating system. At this point the guest
operating system is entirely responsible for loading any more data it might operating system is entirely responsible for loading any more data it might
need to function. NOTE: The IPL2 channel program might read data into memory need to function.
location 0 thereby overwriting the IPL1 psw and channel program. This is ok
as long as the data placed in location 0 contains a psw whose instruction NOTE: The IPL2 channel program might read data into memory
address points to the guest operating system code to execute at the end of location ``0x0`` thereby overwriting the IPL1 psw and channel program. This is ok
the IPL/boot process. as long as the data placed in location ``0x0`` contains a psw whose instruction
NOTE: The ccws in IPL2 are defined by the architecture to be format 0. address points to the guest operating system code to execute at the end of
the IPL/boot process.
NOTE: The ccws in IPL2 are defined by the architecture to be format 0.
4. Start executing the guest operating system. 4. Start executing the guest operating system.
The psw that was loaded into memory location 0 as part of the ipl process The psw that was loaded into memory location ``0x0`` as part of the ipl process
should contain the needed flags for the operating system we have loaded. The should contain the needed flags for the operating system we have loaded. The
psw's instruction address will point to the location in memory where we want psw's instruction address will point to the location in memory where we want
to start executing the operating system. This psw is loaded (via LPSW to start executing the operating system. This psw is loaded (via LPSW
instruction) causing control to be passed to the operating system code. instruction) causing control to be passed to the operating system code.
In a non-virtualized environment this process, handled entirely by the hardware, In a non-virtualized environment this process, handled entirely by the hardware,
is kicked off by the user initiating a "Load" procedure from the hardware is kicked off by the user initiating a "Load" procedure from the hardware
@ -54,18 +60,17 @@ written immediately after the special "Read IPL" ccw, the IPL1 channel program
will be executed immediately (the special read ccw has the chaining bit turned will be executed immediately (the special read ccw has the chaining bit turned
on). The TIC at the end of the IPL1 channel program will cause the IPL2 channel on). The TIC at the end of the IPL1 channel program will cause the IPL2 channel
program to be executed automatically. After this sequence completes the "Load" program to be executed automatically. After this sequence completes the "Load"
procedure then loads the psw from 0x0. procedure then loads the psw from ``0x0``.
********************************************************** How this all pertains to QEMU (and the kernel)
***** How this all pertains to QEMU (and the kernel) ***** ----------------------------------------------
**********************************************************
In theory we should merely have to do the following to IPL/boot a guest In theory we should merely have to do the following to IPL/boot a guest
operating system from a DASD device: operating system from a DASD device:
1. Place a "Read IPL" ccw into memory location 0x0 with chaining bit on. 1. Place a "Read IPL" ccw into memory location ``0x0`` with chaining bit on.
2. Execute channel program at 0x0. 2. Execute channel program at ``0x0``.
3. LPSW 0x0. 3. LPSW ``0x0``.
However, our emulation of the machine's channel program logic within the kernel However, our emulation of the machine's channel program logic within the kernel
is missing one key feature that is required for this process to work: is missing one key feature that is required for this process to work:
@ -89,32 +94,31 @@ Lastly, in some cases (the zipl bootloader for example) the IPL2 program also
transfers control to another channel program segment immediately after reading transfers control to another channel program segment immediately after reading
it from the disk. So we need to be able to handle this case. it from the disk. So we need to be able to handle this case.
************************** What QEMU does
***** What QEMU does ***** --------------
**************************
Since we are forced to live with prefetch we cannot use the very simple IPL Since we are forced to live with prefetch we cannot use the very simple IPL
procedure we defined in the preceding section. So we compensate by doing the procedure we defined in the preceding section. So we compensate by doing the
following. following.
1. Place "Read IPL" ccw into memory location 0x0, but turn off chaining bit. 1. Place "Read IPL" ccw into memory location ``0x0``, but turn off chaining bit.
2. Execute "Read IPL" at 0x0. 2. Execute "Read IPL" at ``0x0``.
So now IPL1's psw is at 0x0 and IPL1's channel program is at 0x08. So now IPL1's psw is at ``0x0`` and IPL1's channel program is at ``0x08``.
4. Write a custom channel program that will seek to the IPL2 record and then 3. Write a custom channel program that will seek to the IPL2 record and then
execute the READ and TIC ccws from IPL1. Normally the seek is not required execute the READ and TIC ccws from IPL1. Normally the seek is not required
because after reading the IPL1 record the disk is automatically positioned because after reading the IPL1 record the disk is automatically positioned
to read the very next record which will be IPL2. But since we are not reading to read the very next record which will be IPL2. But since we are not reading
both IPL1 and IPL2 as part of the same channel program we must manually set both IPL1 and IPL2 as part of the same channel program we must manually set
the position. the position.
5. Grab the target address of the TIC instruction from the IPL1 channel program. 4. Grab the target address of the TIC instruction from the IPL1 channel program.
This address is where the IPL2 channel program starts. This address is where the IPL2 channel program starts.
Now IPL2 is loaded into memory somewhere, and we know the address. Now IPL2 is loaded into memory somewhere, and we know the address.
6. Execute the IPL2 channel program at the address obtained in step #5. 5. Execute the IPL2 channel program at the address obtained in step #4.
Because this channel program can be dynamic, we must use a special algorithm Because this channel program can be dynamic, we must use a special algorithm
that detects a READ immediately followed by a TIC and breaks the ccw chain that detects a READ immediately followed by a TIC and breaks the ccw chain
@ -126,8 +130,9 @@ following.
channel program from executing properly. channel program from executing properly.
Now the operating system code is loaded somewhere in guest memory and the psw Now the operating system code is loaded somewhere in guest memory and the psw
in memory location 0x0 will point to entry code for the guest operating in memory location ``0x0`` will point to entry code for the guest operating
system. system.
7. LPSW 0x0. 6. LPSW ``0x0``
LPSW transfers control to the guest operating system and we're done. LPSW transfers control to the guest operating system and we're done.