OWN - Execute user code during trace.

Description:

This type of trace permits you to gain control from the trace mechanism before each instruction is executed (or simulated). To engage an own code trace, you must supply a special subroutine to perform the desired tracing function(s). The entry point to the subroutine will be requested by the trace package, as follows:

ENTER ABS. ADDRESS OF OWN PROCEDURE:

At this time, you must enter the absolute address of the entry point to your subroutine procedure. When the next run command is issued, control will be passed to this entry point via a TSX1 before each instruction is executed, provided the instruction is in one of the specified tracing regions. This includes every step of an execute (XEC or XED) chain, but does not include repeated instructions; i.e., the subroutine will be entered before the repeat instruction itself is executed, but not before each execution of the repeated instruction(s). With EIS opcodes, your subroutine is called for each EIS descriptor.

Upon each entry into the subroutine, certain registers will be set by the trace mechanism, as follows:

X0 - contains a pointer to the target program's registers. These registers are loaded and stored by LREG and SREG instructions addressing this area.
X1 - the linkage register between the trace mechanism and your subroutine.
X3 - contains the pseudo instruction counter (PIC). the PIC reflects the location of the current instruction being executed.
X4 - contains a pointer to the location of the instruction word itself. Except for instructions being executed via XEC or XED, X3 and X4 will be identical.
X5 - index 5 contains the effective address of the single word instruction, if applicable.
IR - loaded with the target program's indicators.

QR - individual bits in this register reflect attributes of the instruction, as follows:

BIT#    MEANING, IF BIT IS ON
 
00      unconditional transfer
01      conditional transfer
02      RPT, RPL or RPD
03      XEC or XED
04      STCA, STCQ, STBA or STBQ
05      STC1, STC2 or TSXn
06      instruction changes the register(s)
        specified by bits 18-33
07      instruction stores data somewhere in
        memory
08-17   reserved (subscript into name table)
18      affects the meaning of bits 28-35;
        if this bit is on, the bits indicate
        AR registers
19      if opcode being traced
20      memory cycle(s) required
21      affects the meaning of bits 28-35;
        if this bit is on, the bits indicate
        PR registers 
22      AR utilized
23      QR utilized
24      AQ utilized
25      ER utilized
26      EAQ utilized
27      IR utilized
28      X0 utilized (or AR0 or PR0)
29      X1 utilized (or AR1 or PR1)
30      X2 utilized (or AR2 or PR2)
31      X3 utilized (or AR3 or PR3)
32      X4 utilized (or AR4 or PR4)
33      X5 utilized (or AR5 or PR5)
34      X6 utilized (or AR6 or PR6)
35      X7 utilized (or AR7 or PR7)

Several of these bits require further comment.

Bit 19 is typically turned on when a particular opcode is being executed, but not when you are performing a "use trace" (see "expl trace trace use"). If you are tracing XED instructions, the bit will also be turned on for whatever opcodes are being performed within the XED.
Bit 20 is only turned on when memory is actually read or written. It is not turned on if memory is just used in calculating an effective address.
Bits 28-35 represent X registers if bits 18 and 21 are both off. If bit 18 is on, bits 28-35 represent AR registers and if bit 21 is on, bits 28-35 represent pointer registers.

Following this analysis, you must return to the trace mechanism so that the instruction can be executed and the simulation process continued. With the linkage register (X1) restored to its contents at entry, you have two alternatives to relinquish his control:

TRA 0,1 - this return will prevent the instruction from being displayed.
TRA 1,1 - this return will cause the instruction to be displayed. If pause mode is enabled, command level will be entered before the instruction is executed.

Registers other than X1 need not be saved or restored by your subroutine. They will be properly restored by the trace mechanism when the subroutine returns.

Own code tracing can be a dangerous technique! For example, you must always be aware that your trace subroutine cannot use code which might also be used by the target program. The same, of course, goes for shared data areas. On the other hand, own code tracing can provide capabilities limited only by your imagination and ingenuity.