PTRACE — Processor trace

Description

The PTRACE macro creates a trace table entry and places it in the system trace table. The entry consists of an event identifier, the contents of a designated range of general registers or storage locations, and system supplied status information.

When using this macro, the user must provide the following information:
  • The type of trace entry that is to be created
  • The data to be recorded in the trace entry

The PTRACE macro can only be issued with DAT-ON. The caller must be in key 0 and supervisor state but can be in cross memory mode and in either 24 or 31-bit addressing mode. All addresses passed to the PTRACE routine are treated as 31-bit addresses. PTRACE users must include the IHAPSA and IHATRVT mapping macros and register 13 must point to a 72-byte save area that can be used by the PTRACE service.

PTRACE accepts the TRACEMODE=TRACG option to request the use of TRACG to record trace data. This option alters the interpretation of the existing REGS and SAVEAREA options.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state, key 0
Dispatchable unit mode: Task or SRB
Cross memory mode: Any
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt Status: Enabled or disabled for I/O or external interrupts
Locks: Any locks may be held
Control parameters: Must be in the primary address space

Programming requirements

The PTRACE macro can only be issued with DAT-ON. All addresses passed to the PTRACE routine are treated as 31-bit addresses. PTRACE users must include the IHAPSA and IHATRVT mapping macros and register 13 must point to a 72-byte save area that can be used by the PTRACE service.

Restrictions

None.

Output register information

After the caller issues the macro, the macro might use some registers as work registers or might change the contents of some registers. When the macro returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code

Performance implications

None.

Syntax

The PTRACE macro is written as follows:

Syntax Description
   
     name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede PTRACE.
   
PTRACE  
   
␢ One or more blanks must follow PTRACE.
   
TYPE=USRn n: hexadecimal digit 0 - F.
   
   ,REGS=(reg1,reg2) Default: REGS=(1)
   ,REGS=(1) reg1: decimal digit 2 - 12.
  reg2: decimal digit 2 - 12.
   
,SAVEAREA=STANDARD  
,SAVEAREA=F4SA  
   
,TRACEMODE=TRACE Default: TRACE
,TRACEMODE=TRACG  
   

Parameters

The parameters are explained as follows:

TYPE=USRn
Specifies a user-event explicit trace entry. The hexadecimal number, n, identifies the entry. Trace processing places this number in the trace entry for identification purposes.
,REGS=(reg1,reg2)
,REGS=(1)
Defines the data to be placed in the user's trace entries. Multiple trace entries are created if more than 5 registers or 5 words of data are requested.

If REGS=(reg1,reg2) is specified, the data is located in a range of registers, where reg1 specifies the first register in the range and reg2 specifies the last register in the range. The register number, reg2, must always be greater than or equal to the register number, reg1. A maximum of 11 words of data can be indicated for tracing using REGS=(reg1,reg2).

If REGS=(1) is specified or used as the default, register 1 must contain the 31-bit address of a parameter list. The high order bit of this address must be set to 0. If REGS=(1) is specified, up to 1024 words of data can be recorded. The parameter list contains N+1 fullword entries. The first word contains the number of words of data (N) to be recorded. This is followed by the N words of data to be placed in the user's trace entries.

For TRACEMODE=TRACG this refers to a range of 64-bit registers.

,SAVEAREA=STANDARD
,SAVEAREA=F4SA
STANDARD format specifies that register 13 contains the address of a 72-byte save area that can be used by the PTRACE routine.

IF F4SA is used, specifies 64-bit GPR 13 contains the address of a 144-byte save area in F4SA format for TRACEMODE=TRACG.

,TRACEMODE=TRACE
,TRACEMODE=TRACG
An optional operand that requests the use of TRACG for generation of a system trace entry. Omission of this option requests the use of TRACE. TRACEMODE=TRACE may be explicitly coded to designate the default use of the TRACE instruction.

When control returns to the caller, registers 2-13 are restored to their original values, but the original contents of registers 0, 1, 14, and 15 are destroyed. On exit, register 15 contains a return code.

Return and reason codes

The hexadecimal return code from the PTRACE macro is as follows:

Table 1. Return Code for the PTRACE Macro
Return Code Meaning
00 Meaning: The function completed successfully.

Example 1

Create a trace table entry for user event 4. Registers 5, 6, and 7 contain the user data to be recorded. 
PTRACE TYPE=USR4,REGS=(5,7),SAVEAREA=STANDARD

Example 2

Create trace table entries for user event C. Register 1 contains the address of a parameter list containing the data to be recorded. 
PTRACE TYPE=USRC,REGS=(1),SAVEAREA=STANDARD