22.1 What information you need

Let's briefly review the information you need for successful debugging on the mainframe.

22.1.1 User address spaces

You may remember from 20.3, "Exploiting mainframe processor architecture," that there are several kinds of address spaces. In particular, the Linux kernel runs in primary space mode, and all user programs run in home space mode.

Let's have a short look at the virtual address space or user space process. In Figure 22-1 we see the organization of the virtual memory. The stack grows from high addresses to low. The dynamic segments are used, e.g., for shared libraries, and are located above the anonymous mapping base. The code and heap of a user program are located between the program base and the anonymous mapping base.

Figure 22-1. Address space organization

The addresses for "end of memory" and "anonymous mapping base" depend on the version of the Linux kernel used. "Program base" depends on the linker script setting. These will change with time, as everything in Linux does. Table 22-1 lists some values of kernel versions current at the time of writing.

Table 22-1. Kernel addresses

	Linux for S/390 (31-bit hex)	Linux for zSeries (64-bit)
End of virtual memory	7fff ffff	2exp(41-1)
Anonymous mapping base	4000 0000	2exp40
Program base (assume normally used linker script setting)	40 0000	2exp31

Knowing these values, it is possible to see, for example, on the address portion of a program PSW whether a program currently is running in a shared library or in program code. We will show examples of this later.

The above scheme is valid only for user space processes. Kernel space addresses can be located beween 0 and "end of virtual memory." If you find an instruction address smaller than "program base," this might indicate that it is a kernel address.

22.1.2 The PSW

A very important piece of information is the PSW. We looked at both the 31-bit PSW and the 64-bit PSW in 21.3, "The program status word." The most relevant bits for problem determination and debugging are the interrupt masks (the input/output mask, bit 6, and the external mask, bit 7; see also 21.1.5, "Interrupts"), the machine check bit (bit 13), the wait state bit (bit 14), the problem state bit (bit 15), and the address space control bits (bits 16 and 17).

A single bit (bit 15) defines the state: the machine runs in problem state if the bit is set to 1. Certain instructions are then disabled. All Linux user programs run with this bit set to 1. Kernel programs run in supervisor state with the bit set to 0. Therefore, the PSW can tell us if the CPU executes kernel or user code.

In some cases, the DAT mode, or virtual addressing bit (bit 15), can be of interest. This bit indicates whether dynamic address translation is enabled. Dynamic addressing is always enabled under Linux. The meanings of the address space control bits are:

00	Primary Space Mode with DAT on. The Linux kernel currently runs in this mode. Control register CR1 is associated with this mode and points to the primary segment table origin.
01	Access register mode. This mode is used in functions to copy data between kernel and user space.
10	Secondary space mode. This is not used in Linux. However, control register CR7, which is associated with this mode, is used in Linux. Normally, CR13=CR7 to allow data to be copied between kernel and user space.
11	Home Space Mode. All user programs run in this mode. This mode is associated with CR13, which points to the home segment table origin.

22.1.3 Registers

Registers were covered in 21.2.1, "zSeries registers." The most important registers for debugging are 14 and 15. Register 14 is the return address, and register 15 is the stack pointer.

22.1.4 The stack frame

Each function normally has an associated stack frame on the runtime stack. This stack grows downward from high addresses. Figure 22-2 shows the stack frame organization. This organization applies to both kernel and user space stacks. SP in the figure denotes the stack pointer. When the function is executed by a CPU, SP is held in general purpose register r15.

Figure 22-2. Standard stack frame

The register save area (see Figure 22-3) on the stack frame for the currently executed function is for use of the next called function. In the prolog of the called function, the registers of the calling function, which are overwritten, are saved in the register save area of the calling function's stackframe. Therefore, the register save area of the currently executed function does not contain valid register values (they are not yet saved).

Figure 22-3. Register save area for 64-bit (31-bit values in parentheses)

If the backchain is implemented (which means that the compiler created code for setting up the backchain), it is possible to walk by hand through the stack frames by just following the backchain. The first stack frame on the stack normally has a backchain of 0 (NULL), which indicates the end of the stack.