gtps1m08System Macros

Control Program (CP) Linkage

This section provides overview information, as well as information about:

Overview

The control program (CP) linkage is intended to provide TPF system programmers with a mechanism for linking between control program routines. Included here are a set of rules governing the linkage and a set of system macros that adhere to the rules. This linkage is available for use when modifying existing CP sections or creating new ones.

The tightly-coupled multiprocessing environment requires that certain system macros be coded in every control program CSECT that can be processed from multiple I-streams. The system macros provide linkage conventions and define work areas on I-stream unique stacks that protect the TPF system from corruption due to multiple I-streams using the same work space. All stack manipulation and CP linkage must be done only by these system macros to provide efficient, cost-effective modification in the future.

The mechanism assumes:

Stacks exist for the different environments in which the TPF system operates:

You can also define additional stack areas, such as user-defined stack areas, as needed. R13 is initialized to point to each respective stack at entry to the environment. (For example, first level I/O interrupt handler points R13 to the I/O stack; macro decoder points R13 to the SVC stack). Therefore, all CP routines assume R13 addresses a stack save area.

When an environment is entered, a work area, or stack, must be established for that environment. This stack can be of any size but must be large enough to include the total work area of the user requiring the largest work area at each level of stack use. The current implementation of stack control is limited and assumes an implied limit to levels of nested linkage calls because of the predefined stack size.

Register Defaults

This section provides information about register defaults as follows:

Note:
The entire CP does not necessarily adhere to these register conventions. It is possible to override each convention, with the exception of R13 usage.

The Stacks

This section provides information about:

Initialization

The system initializer, CCCTIN, carves out a stack for each environment for each I-stream. After initialization, while the TPF system is running, each environment entry point (for example, the macro decoder for SVC and the I/O interrupt handler for I/O) sets R13 to point to the appropriate stack. Therefore, the entire CP can assume R13 always points to a stack entry.

Each stack contains enough space to save registers and work space for the current CP linkage implementation.

DCTSTK Data Area

The DCTSTK data area that defines stack entries. It has a fixed area that defines space for registers, a performance area, and space for use by macros. In addition, by using the SLNKC macro you can define a variable amount of space on the stack for your use.

All stack manipulation and CP linkage must be done only by the SLNKC, DLNKC, CLNKC, and RLNKC macros to provide simple modification in the future.

Predefined Equates

Equate values are used to address predefined areas. The size of this area is constant, making it easier to view in a dump.

Previous Stack Pointer

This fullword contains a pointer to the previous stack area used. It is used to return to the caller and is for debugging dumps because it is often necessary to locate the stack area of the caller.

Register Save

Sixteen fullwords are allocated to save all general registers.

Performance Area

The performance area is allocated in every stack entry for use by performance-oriented routines such as storage block management routines that do not have to subtract and push the stack pointer. These routines cannot afford the added cost of pushing the stack pointer. Routines using the performance area cannot call a lower level routine.

STKINL Macro Save Area

The STKINL macro save area is an inline save area used by system macros to temporarily save and restore registers and data over the macro call. This alleviates the problem of finding a place to save registers during macro calls (inline macros or system macros that generate linkage to central routines).

User-Defined Area

The user-defined area, in DSECT form, can be variable in size depending on routine requirements, single register addressability, and stack size. Single register addressability limits the space to 4096 bytes. This space is defined by coding define storage instructions between the SLNKC and DLNKC macros.

Note:
These areas are not automatically initialized during subroutine calls and if initialization is important must be handled by the user.

Linkage

You should always use the SLNKC, DLNKC, CLNKC, and RLNKC system macros, which are CP linkage and stack manipulation macros, when linking between CP routines that require stacks. These system macros use the default register conventions described in Register Defaults, but the defaults can easily be overridden for general TPF system use.

This linkage meets the following requirements:

The following are assumptions about this linkage:

Initial Linkage

The CCCTIN system initializer carves out stacks for each environment (for example, SVC, I/O, MCHK, ERROR) for each I-stream and establishes a pointer to each stack in the prefix page. This pointer is initialized to the bottom of the stack minus 1 entry so that the stack is ready to be addressed upon entry to the environment.

When an environment is entered, R13 is set to point to the proper stack for the current I-stream. Since the stack pointer is located in the prefix page, it is addressable by the entire CP and is, by definition, I-stream-unique.

For example, when an SVC interrupt occurs, the macro decoder must:

                       L   R13,PFXSSAVE

This sets R13 to the SVC stack. You can now code the SLNKC and CLNKC macros.

Calling Linkage

To call a CP routine, the caller's link register or branch-to-register is saved in the register save area on the stack. Then the caller loads the branch-to-register (which will become the called routines base register) and BASRs to the routine. If default register conventions are used:

              CALLER   ST   R15,STKR15(,R13)
                       L    R15,CALLEE
                       BASR R14,R15
Note:
The branch-to-register, R15, is saved on the stack before the call to preserve its contents over the macro call. The called routine must not overlay the contents of STKR15 when it saves registers, and in addition it must restore R15 when returning.

Linkage upon Entry to a Routine

Upon entry to a CP routine that had been called by the calling linkage described previously (see Initial Linkage for more information) the lowest number register used by the routine through register 15 is stored into the caller's stack register save area. R13 is then decremented by the size of the work area needed by the current routine and its previous value, which points to the last stack entry, is saved in the current stack entry. If default register conventions are used:

              CALLEE   STM  R0,R14,STKR0(R13)
                       SL   R13,STKLEN
                       MVC  STKPREV,STKLEN+STKR13(R13)

Notes:

  1. Remember R15 was saved already by the caller. Therefore, it is essential that the caller and the callee know what is the base register of the called routine.

  2. The registers are saved on the stack first and then R13 is pushed. To find the register contents at entry to a routine in a dump, you must first get the pointer to the last stack entry (STKPREV).

Linkage to Return

To return to a CP routine that was called by the linkage described previously, R13 is restored to point to the caller's stack area. All registers saved by the called routine (except parameters being passed between calls) are restored, and return is made by a BR R14. If default register conventions are used:

                       L    R13,STKPREV(R13)
                       LM   R0,R15,STKR0(R13)
                       BR  R14
Note:
This includes the branch-to-register or BASE previously saved in the calling linkage logic.

Linkage Notes

Keep in mind the following:

Examples of the use of these system macros and the stack area follow.

Sample Stack Area Use

The following is a sample of the stack area use.

      (PROG2 SLNKC) R13 >       PERFORMANCE AREA
 
                                       PREV     Pointer to last stk
                                       R0       Register
                                       R1        save
                                        .         area
                                       R15
 
                                                USER DEFINED AREA
 
      (PROG1 SLNKC) R13 >       PREV     Pointer to last stk
                                       R0       Register
                                       R1         save
                                        .          area
                                       R15
 
                                                USER DEFINED AREA
 
      (PROG0) STACK> R13>PREV     Pointer to last stk
                                       R0
                                       R1           Register
                                        .            save
                                       R15            area
 
                                             USER DEFINED AREA
Note:
Performance area exists only at highest/deepest call. It is overlayed on all other calls.

Coding Example for Control Program (CP) Linkage

Program 0, which is the initial routine, is the initial entry to the CP environment. Load the stack register with the proper stack from prefix page. Call first routine.

        Without Macros                     With Macros
 
          .                                  .
          .                                  .
          .                                  .
          .                                  .
          L   R13,PFXSSAVE                   L     R13,PFXSSAVE
          .                                  .
          .                                  .
          .                                  .
          .                                  .
          ST  R15,STKR15(R13)                .
          L   R15,=A(PROG1)                  CLNKC RTN=PROG1,TYPE=INT
          BASR R14,R15                       .
          .                                  .
          .                                  .
          .                                  .
          LTORG ,                            LTORG ,
            =A(PROG1)                          =A(PROG1)
 
                 End Prog 0 Initial Entry to control program.

Program 1, which is the caller routine, saves registers on the stack. Push the stack pointer. Save the caller's stack pointer.

          Without Macros                    With Macros
 
          PROG1   DS   0H                          PROG1  DS  0H
 
 
    USING P1WK,R13
    STM R0,R14,STKR0(R13)                      SLNKC LOREG=R0,
    SL  R13,=A(P1WKL)                                DSECT=P1WRK
    MVC STKPREV(R13),K1WKLEN_STRK13(R13)
  P1WK    DSECT
  STKPRF  DS    16X Performance area
  STKPREV DS    1F  Previous Stack
  STKREGS DS    16F Register Save
  STKINL  DS    6F  In-Line Reg Save
 
  P1A     DS    1F                        P1A  DS  1F
  P1B     DS    1F                        P1B  DS  1F
  P1C     DS    1F                        P1C  DS  1F
 
          DS    0D
  P1WKLEN EQU   *-P1WK
          CSECT                              DLNKC
          .                                  .
          .                                  .
          ST   R15,STKR15(R13)               .
          L    R15,PROG2A                    CLNKC RTN=PROG2,TYPE=INT
          BASR R14,R15                       .
          .                                  .
          .                                  .
          .                                  .
          LM R0,R15,STKREGS                 RLNKC LOREG=R0
          BR R14                             .
          .                                  .
          .                                  .
  PROG2A  DC  A(PROG2)                       LTORG
          LTORG ,                              =A(PROG2)
            =A(P1WKLEN)                        =A(P1WKLEN)
 
                            End Prog 1

Program 2, which is the called routine, saves registers on the stack. Push the stack pointer. Save the caller's stack pointer.

     Without Macros                       With Macros
 
          PROG2   DS   0H                          PROG2  DS  0H
 
 
    USING P2WK,R13
    STM R0,R14,STKR0(R13)                      SLNKC LOREG=R0,
    SL  R13,=A(P2WKL)                                DSECT=P2WK
    MVC STKPREV(R13),P2WKLEN+STKR13(R13)
  P2WK    DSECT
  STKPRF  DS    16X Performance area
  STKPREV DS    1F  Previous Stack
  STKREGS DS    16F Register Save
  STKINL  DS    6F  Inline Reg Save
 
  P2A     DS    1F                        P2A  DS  1F
  P2B     DS    1F                        P2B  DS  1F
  P2C     DS    1F                        P2C  DS  1F
          DS    0D                           .
  P2WKLEN EQU   *-P2WK                       .
          CSECT                              DLNKC
          .                                  .
          .                                  .
          .                                  .
          .                                  .
          LM R0,R15,STKREGS                 RLNKC LOREG=R0
          BR R14                             .
          .                                  .
          .                                  .
          .                                  .
 
                              End Prog 2

Stack Definition Example

The following is an example of a stack definition.

               PFXSSAVE DS F - SVC Stk
 
               PFXFSAVE DS F - Fast Link Stk          I-
                                                        S
               PFXISAVE DS F - I/O Stk                   T
                                                          R
               PFXESAVE DS F - External Stk                E
                                                            A
               PFXPSAVE DS F - Program Ck Stk (real address) M
 
               PFXMSAVV DS F - Machine Ck Stk (SVA)       #1
 
               PFXMSAVR DS F - Machine Ck Stk (real address)
 
               PFXZSAVE DS F - Program Ck IO Stk
 
               PFXSSAVE DS F - SVC Stk
 
               PFXFSAVE DS F - Fast Link Stk          I-
                                                        S
               PFXISAVE DS F - I/O Stk                   T
                                                          R
               PFXESAVE DS F - External Stk                E
                                                            A
               PFXPSAVE DS F - Program Ck Stk (real address) M
 
               PFXMSAVV DS F - Machine Ck Stk (SVA)       #2
 
               PFXMSAVR DS F - Machine Ck Stk (real address)
 
               PFXZSAVE DS F - Program Ck IO Stk

Equates

There are common equates provided to refer to a variety of system structures. Among them are:

In addition to system macros that consist purely of equates, DSECTS also often carry equates with them.