gtps1m08 | System Macros |
This section provides overview information, as well as information about:
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.
This section provides information about register defaults as follows:
This section provides information about:
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.
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.
Equate values are used to address predefined areas. The size of this area is constant, making it easier to view in a dump.
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.
Sixteen fullwords are allocated to save all general registers.
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.
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).
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.
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:
These areas do not exceed 4096 bytes of doubleword entries.
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.
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
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:
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
Keep in mind the following:
Examples of the use of these system macros and the stack area follow.
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
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
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
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.