TRACE - engage the trace mechanism.

Description:

Tracing, as applies to the following discussion, is a technique which consists of simulating the functional operation of a computer by utilizing one program to interpret and execute the instructions of another program. Such a technique provides excellent debugging and instrumentation capabilities, since each instruction of the traced (target) program can be dynamically examined before it is executed. For example, any desired analysis can be made of the instruction's operation code, modifier, effective address, etc.

The primary purpose for developing the debug trace package was to provide such a simulator, or trace mechanism, which could be used in the T/S environment. To this end, seven different types of traces have been made available: transfer trace, operation code trace, modifier trace, use trace, change trace, full trace and map trace. An eighth type (own code trace) is also available which permits the user to gain control before each instruction is executed.

The command which causes the trace mechanism to become engaged is TRACE, or simply T. Upon receipt of this command, the trace package will respond with the question

          TYPE?

This is a request to select the type of tracing which is to be performed. The user must enter one of the following:

tra
op
mod
use
chg
full
map
own

If the selection is anything other than TRA, FULL or MAP, the trace package will next issue a request for parameters related to the selected type. For example, if OP was specified, the user would be asked to enter the operation codes of the instructions he wished to trace.

The dialogue between user and trace package up to this point can be eliminated, if desired, by including the type selection and parameters (if required) on the same line as the trace command itself. Consider, for example, the following request to engage an operation code trace on the TSX1 amd RET instructions:

?trace
TYPE? op
ENTER OPS: tsx1,ret

This could be conveniently be expressed on a single line as follows:

?trace,op,tsx1,ret

The only other information required before the trace mechanism can be engaged consists of the memory locations where (or intervals within which) tracing is to take place. The following message will be issued requesting this information:

          ENTER TRACING REGION:

With the single exception of map tracing, users may respond with any number of locations and/or intervals specifying the areas of memory they wish to trace. An interval specification must take the form, A1:A2, and implies all locations from A1 to A2, inclusive. Note that all locations and location intervals will be considered relative to the offset, provided one has been previously established. If it is desired to specify an absolute location or location interval, the specification may be suffixed with the letter "A". Thus, for example, to trace

the absolute interval from 1310 through 1570,
the relative location 4633, and
the relative interval from 4656 through 4700,

the response should be:

ENTER TRACING REGION: 1310:1570a,4633,4656:4700

A null response to this request (i.e.., a carriage return only) implies the interval specification, 0:777777A. Thus, tracing will take place throughout all of allocated memory.

The tracing region specifications may also be included on the same line as the trace command, selection type and parameters by separating the latter from the former with a slash (/); for example,

?trace,op,tsx1,ret/1310:1570a,4633,4656:4700

or, if the default interval (0-777777A) is desired,

?trace,op,tsx1,ret/

Dialogue between user and trace package can thus be completely eliminated! With the trace mechanism now engaged, a question mark (?) will be issued indicating readiness to accept another command.

At the time the next run command is issued, the simulation process will begin; i.e., every instruction of the user's program will be executed in the controlled environment provided by the trace mechanism. Functionally, here's what happens:

The pseudo instruction counter (PIC) which is maintained by the trace mechanism is updated to the address of the next instruction to be executed. Unless the previous instruction was a repeat, derail or one which resulted in a transfer, the PIC will simply be incremented by one.
Next, the instruction word at the address furnished by PIC is obtained and the operation code is examined. If the op code is found to be illegal, the following message will be issued to the user:
```
     nnnnnn: op code fault resulting if executed
```
where, nnnnnn is the address (symbolic or numeric) of the offending instruction, relative to the offset, if one has been previously established. As with all other error conditions detected by the trace mechanism, the user will be immediately returned to command level. Since the trace mechanism will never attempt to execute an instruction having illegal properties, users have three alternatives if they wish to resume execution:
- patch the offending instruction before issuing the next run command.
- specify an address with the run command to bypass the instruction.
- disengage the trace mechanism before issuing the next run command.
If the instruction is not a repeat, derail or character/byte store, its final effective address will next be determined. During this process, the intruction's modifier is examined to insure it is legal. Also, if indirection is specified, the indirect chain will be traversed and all modifiers encountered will be similarly examined. Any of the following error messages may be issued as a result of the analysis:
```
nnnnnn: illegal modification resulting if executed
nnnnnn: tag fault resulting if executed
nnnnnn: memory fault resulting if executed
```
Note that the memory fault error message would be issued if the address of an indirect word was found to be out-of-bounds.
Having established the effective address, an analysis is now made to determine if the instruction requires a memory cycle or will result in a transfer of control. In both cases, the effective address will be examined to insure that it is within the boundaries of allocated memory. Furthermore, a test is made to determine if the effective address is referencing a location within the trace package itself. This analysis permits recognition of
- a breakpoint location previously established by the B command, and
- a TSX1, XED or STX1 addressing the trace package entry point (TRACE).
If the instruction will result in a store or transfer referencing some location in the trace package and is neither of the above, the following error message will be issued:
```
nnnnnn: store or transfer into trace pkg. resulting if executed
```
If the PIC is within any of the specified tracing regions, the instruction is now ready to be examined according to the type of trace which has been selected. For example, if an operation code is one of the OP code(s) selected by the user to be traced, providing
- all conditions are met,
- a map trace is not engaged, and
- trace output is not being queued,
a single line of output will be issued to the user indicating the following:
- location of the instruction, relative to the offset, if one is established.
- the mnemonic operation code.
- the address field (bits 0-17) of the instruction word.
- the modifier, if any.
- the effective address, if applicable. This will also be relative to the offset, provided one is established.
For example,
```
  004633  TSX1  000502,IC  (005335)
     .      .      .    .      .
     .      .      .    .      .........effective address
     .      .      .    .
     .      .      .    ................modifier
     .      .      .
     .      .      .....................instruction address
     .      .
     .      ............................operation code
     .
     ...................................instruction location
```
If the displayed instruction is one which is being executed by an XEC or XED, the location shown will be that of the execute instruction -- not the location of the instruction being executed. An "x" will be appended to the location field to identify this.

A somewhat different format is used to display a repeat-type instruction. In place of the instruction address, modifier and effective address fields, the repeat count, increment and terminate conditions(s) will be shown. repeat count and increment will both be given in octal. The repeated instruction(s) will also be displayed on subsequent lines. These can be identified by the absence of the location field; i.e., this field will be left blank.

When displaying effective addresses for instructions like ABD, or A9BD, the address is displayed as "(WWWWWW XX)" where "WWWWWW" is the word address, and XX is the number of units into the word. "XX" may be 1 or 2 octal digits and is in the units appropriate to the instruction. This if an A9BD are AR0 to bit 27 (033) of location 0100, the value displayed would be (000100 3), but and EPPR of ABD that did the same would display (000100 33).
At this point, the instruction is ready to be executed or, in the case of certain instructions, simulated. Simulation is necessary if the instruction
- will result in a transfer of control,
- stores the instruction counter (IC) register, or
- is an XEC or XED.
Otherwise, all of the user's registers will be restored and the instruction (or a tailored version of it) will be executed. Tailoring, if applicable, is performed during step#3 and consists of stripping off modifiers of the following types:
- all RI and IR types.
- IC, IDC and DIC.
Derail instructions require special consideration by the trace mechanism before they can be executed. In the time-sharing environment, a drl is used to request a service function to be performed by the T/S executive, and is analogous to the MME used is the batch environment. The types of request, identified by the address portion of the DRL, will first be validated by the trace mechanism. If found to be illegal or privileged, the following error message will be issued:
```
nnnnnn: illegal drl resulting if executed
```
Next, a test is made to determine if the DRL is attempting to terminate execution. If so, the following message is issued:
```
nnnnnn: termination via drl xxxxxx resulting if executed
```
where, xxxxxx is the symbolic name of the terminating service function. This will be ABORT, DRLDSC, RETURN or SYSRET. Also, under certain conditions, the service functions RELMEM and RESTORE can cause issuance of this message.

Unless the DRL is a KIN request, its calling sequence is now reconstructed within the trace mechanism, tailored if necessary, and executed. Tailoring, in this sense, consists of changing the return address for service functions such as ADDMEM, RELMEM and RESTORE so that the trace mechanism will not lose control when the DRL is executed.

If the DRL is a KOUTN (keyboard output then input), the trace mechanism will immediately follow its execution with a KIN (keyboard input) to obtain the user's response. Upon encountering a subsequent DRL KIN in the target program, the trace mechanism will simulate it by moving the input received from the last KOUTN to the user's buffer. Note that this procedure is necessary because the trace package might perform keyboard I/O between the user's KOUTN and KIN, thus destroying his actual input data.

The KIN simulation requirement does, however, afford an excellent means to initiate a breakpoint and enter command level any time the target program does a KOUTN. This can be accomplished by responding to the program's input request with the following:
```
$BRK
```
Upon intercepting the user's input response and identifying this signal, the trace mechanism will issue the following message:
```
enter actual input data:
```
At this time, users must enter the actual data required by their program. Following this, the trace package will enter command level and users are now free to exercise any of the commands available to them. Traced execution will resume at the time the next run command is issued.

This is essentially how the trace mechanism works. Although it sounds like an infinitely slow process to step through each instruction of a program in this manner, the trace mechanism has been designed for efficiency and is respectably fast. A short summation of the implementation philosophy used is:

make the often used code fast at the expense of the infrequently used code, if necessary.
don't hesitate to make the coding complicated, if it makes it run faster.
take advantage, where possible, of optimal code arrangement to permit the processor to overlap the execution of instructions.

By using one copy of the trace package to trace the trace mechanism of a second copy, it was found that an average of 42.6 instructions were required to execute or simulate one target program instruction. Thus, you may expect your program to run slightly more than 40 times slower when it is being traced.