docs/devel/s390-dasd-ipl.txt

   1 *****************************
   2 ***** s390 hardware IPL *****
   3 *****************************
   4
   5 The s390 hardware IPL process consists of the following steps.
   6
   7 1. A READ IPL ccw is constructed in memory location 0x0.
   8     This ccw, by definition, reads the IPL1 record which is located on the disk
   9     at cylinder 0 track 0 record 1. Note that the chain flag is on in this ccw
  10     so when it is complete another ccw will be fetched and executed from memory
  11     location 0x08.
  12
  13 2. Execute the Read IPL ccw at 0x00, thereby reading IPL1 data into 0x00.
  14     IPL1 data is 24 bytes in length and consists of the following pieces of
  15     information: [psw][read ccw][tic ccw]. When the machine executes the Read
  16     IPL ccw it read the 24-bytes of IPL1 to be read into memory starting at
  17     location 0x0. Then the ccw program at 0x08 which consists of a read
  18     ccw and a tic ccw is automatically executed because of the chain flag from
  19     the original READ IPL ccw. The read ccw will read the IPL2 data into memory
  20     and the TIC (Transfer In Channel) will transfer control to the channel
  21     program contained in the IPL2 data. The TIC channel command is the
  22     equivalent of a branch/jump/goto instruction for channel programs.
  23     NOTE: The ccws in IPL1 are defined by the architecture to be format 0.
  24
  25 3. Execute IPL2.
  26     The TIC ccw instruction at the end of the IPL1 channel program will begin
  27     the execution of the IPL2 channel program. IPL2 is stage-2 of the boot
  28     process and will contain a larger channel program than IPL1. The point of
  29     IPL2 is to find and load either the operating system or a small program that
  30     loads the operating system from disk. At the end of this step all or some of
  31     the real operating system is loaded into memory and we are ready to hand
  32     control over to the guest operating system. At this point the guest
  33     operating system is entirely responsible for loading any more data it might
  34     need to function. NOTE: The IPL2 channel program might read data into memory
  35     location 0 thereby overwriting the IPL1 psw and channel program. This is ok
  36     as long as the data placed in location 0 contains a psw whose instruction
  37     address points to the guest operating system code to execute at the end of
  38     the IPL/boot process.
  39     NOTE: The ccws in IPL2 are defined by the architecture to be format 0.
  40
  41 4. Start executing the guest operating system.
  42     The psw that was loaded into memory location 0 as part of the ipl process
  43     should contain the needed flags for the operating system we have loaded. The
  44     psw's instruction address will point to the location in memory where we want
  45     to start executing the operating system. This psw is loaded (via LPSW
  46     instruction) causing control to be passed to the operating system code.
  47
  48 In a non-virtualized environment this process, handled entirely by the hardware,
  49 is kicked off by the user initiating a "Load" procedure from the hardware
  50 management console. This "Load" procedure crafts a special "Read IPL" ccw in
  51 memory location 0x0 that reads IPL1. It then executes this ccw thereby kicking
  52 off the reading of IPL1 data. Since the channel program from IPL1 will be
  53 written immediately after the special "Read IPL" ccw, the IPL1 channel program
  54 will be executed immediately (the special read ccw has the chaining bit turned
  55 on). The TIC at the end of the IPL1 channel program will cause the IPL2 channel
  56 program to be executed automatically. After this sequence completes the "Load"
  57 procedure then loads the psw from 0x0.
  58
  59 **********************************************************
  60 ***** How this all pertains to QEMU (and the kernel) *****
  61 **********************************************************
  62
  63 In theory we should merely have to do the following to IPL/boot a guest
  64 operating system from a DASD device:
  65
  66 1. Place a "Read IPL" ccw into memory location 0x0 with chaining bit on.
  67 2. Execute channel program at 0x0.
  68 3. LPSW 0x0.
  69
  70 However, our emulation of the machine's channel program logic within the kernel
  71 is missing one key feature that is required for this process to work:
  72 non-prefetch of ccw data.
  73
  74 When we start a channel program we pass the channel subsystem parameters via an
  75 ORB (Operation Request Block). One of those parameters is a prefetch bit. If the
  76 bit is on then the vfio-ccw kernel driver is allowed to read the entire channel
  77 program from guest memory before it starts executing it. This means that any
  78 channel commands that read additional channel commands will not work as expected
  79 because the newly read commands will only exist in guest memory and NOT within
  80 the kernel's channel subsystem memory. The kernel vfio-ccw driver currently
  81 requires this bit to be on for all channel programs. This is a problem because
  82 the IPL process consists of transferring control from the "Read IPL" ccw
  83 immediately to the IPL1 channel program that was read by "Read IPL".
  84
  85 Not being able to turn off prefetch will also prevent the TIC at the end of the
  86 IPL1 channel program from transferring control to the IPL2 channel program.
  87
  88 Lastly, in some cases (the zipl bootloader for example) the IPL2 program also
  89 transfers control to another channel program segment immediately after reading
  90 it from the disk. So we need to be able to handle this case.
  91
  92 **************************
  93 ***** What QEMU does *****
  94 **************************
  95
  96 Since we are forced to live with prefetch we cannot use the very simple IPL
  97 procedure we defined in the preceding section. So we compensate by doing the
  98 following.
  99
 100 1. Place "Read IPL" ccw into memory location 0x0, but turn off chaining bit.
 101 2. Execute "Read IPL" at 0x0.
 102
 103    So now IPL1's psw is at 0x0 and IPL1's channel program is at 0x08.
 104
 105 4. Write a custom channel program that will seek to the IPL2 record and then
 106    execute the READ and TIC ccws from IPL1.  Normally the seek is not required
 107    because after reading the IPL1 record the disk is automatically positioned
 108    to read the very next record which will be IPL2. But since we are not reading
 109    both IPL1 and IPL2 as part of the same channel program we must manually set
 110    the position.
 111
 112 5. Grab the target address of the TIC instruction from the IPL1 channel program.
 113    This address is where the IPL2 channel program starts.
 114
 115    Now IPL2 is loaded into memory somewhere, and we know the address.
 116
 117 6. Execute the IPL2 channel program at the address obtained in step #5.
 118
 119    Because this channel program can be dynamic, we must use a special algorithm
 120    that detects a READ immediately followed by a TIC and breaks the ccw chain
 121    by turning off the chain bit in the READ ccw. When control is returned from
 122    the kernel/hardware to the QEMU bios code we immediately issue another start
 123    subchannel to execute the remaining TIC instruction. This causes the entire
 124    channel program (starting from the TIC) and all needed data to be refetched
 125    thereby stepping around the limitation that would otherwise prevent this
 126    channel program from executing properly.
 127
 128    Now the operating system code is loaded somewhere in guest memory and the psw
 129    in memory location 0x0 will point to entry code for the guest operating
 130    system.
 131
 132 7. LPSW 0x0.
 133    LPSW transfers control to the guest operating system and we're done.