; ************ TRACE ROUTINES FOR PROGRAM COUNTER SAMPLING ***************
;
;
; Performance Measurement and Evaluation routines which collect program
; counter samples by tracing the instruction stream.  Data collection is
; initiated by subroutine PME_INIT and terminated by PME_EXIT.  After
; tracing has been exited, it can be restarted by calling PME_CONT.
; These calls are documented in more detail below.
;
;
;		Written by Bert Beander, March, 1979.



	.TITLE	PMETRACE Performance Measurement and Evaluation
	.IDENT	/V01-01/

	.LIBRARY "PMEDEFS.MLB"

	PMEDEFS				; Define all Bucket File tags
	$CHFDEF				; Define all CHF$ tags
	$PSLDEF				; Define all PSL$ tags
	$SSDEF				; Define all SS$ tags
	$FABDEF				; Define all FAB$ tags
	$RABDEF				; Define all RAB$ tags


; Local data areas
;
	.PSECT	PME_DATA,NOEXE,LONG

STOP_FLAG:	.BYTE	1		; Trace stop flag


	.PSECT	PME_CODE,EXE,NOWRT,LONG,PIC


; **************** PME_INIT:  TRACE INITIATION ROUTINE ********************
;
;
; Trace initiation routine to read in the empty bucket file and start tracing
; to collect program counter values.  The routine is called as follows:
;
;			CALL PME_INIT
;
; This causes the empty bucket file to be opened, read into memory, checked
; for validity, and closed.  All bucket counts are cleared to zeroes if the
; file header so requests, and the tracing operation is started.  The input
; bucket file's name can be specified by calling PME_IFILE before calling
; PME_INIT (see the PMEBLKIO module).  If PME_IFILE is not called, a default
; file name is used.
;
;
; Read in the empty Bucket File, turn on the tracing, and return to the caller.
;
	.ENTRY	PME_INIT,^M<>		; Trace Initiation entry point

	CALLS	#0,PME_OPEN		; Read in the empty Bucket File
	CLRB	STOP_FLAG		; Clear the trace stop flag
	MOVAB	PME_TBIT_TRAP,@12(FP)	; Set trap routine address for the caller
	BISL2	#PSL$M_TBIT,4(FP)	; Set T-bit in the return PSL
	RET				; Return


; ****************** PME_EXIT:  TRACE EXIT ROUTINE ***********************
;
;
; Routine to turn off the tracing.  This routine is called as follows:
;
;			CALL PME_EXIT
;
; This causes tracing to be turned off, the T-bit trap handler to be disabled,
; and the updated Bucket File to be written out as a new file.  The output
; file's name can be specified by calling PME_OFILE before calling PME_EXIT
; (see the PMEBLKIO module).  If PME_OFILE is not called, a default file name
; is used.
;
;
; Turn off tracing, disable the exception handler, and write out the
; accumulated trace data into a new Bucket File.
;
	.ENTRY	PME_EXIT,^M<>		; Trace Termination entry point

	INCB	STOP_FLAG		; Turn off the tracing
	CLRL	(FP)			; Disable the exception handler
	CALLS	#0,PME_CLOSE		; Write out new Bucket File
	RET				; Return to the caller


; **************** PME_CONT:  TRACE CONTINUATION ROUTINE *******************
;
;
; Trace continuation routine which restarts tracing after it has been turned
; off.  This routine is called as follows:
;
;			CALL PME_CONT
;
; This call clears the stop flag and sets the T-bit and exception handler
; address.  This causes tracing to continue with the same bucket file as
; before (the same in-memory copy).  Tracing is stopped with another call
; on PME_EXIT.
;
	.ENTRY	PME_CONT,^M<>		; Trace Continuation entry point

	CLRB	STOP_FLAG		; Turn on tracing
	MOVAB	PME_TBIT_TRAP,@12(FP)	; Set the exception handler
	BISL2	#PSL$M_TBIT,4(FP)	; Set the T-bit in the return PSL
	RET				; Return


; ******************* TRACE T-BIT TRAP ROUTINE *****************************
;
;
; Every T-bit trap (which occurs after every instruction) transfers control
; to this routine.  Check to see if we should stop tracing or if this is a
; non-T-bit exception--otherwise, tally this PC value and return normally.
;
PME_TBIT_TRAP:				; Trap Routine entry point
	.WORD	^M<R1,R2,R3>		;
	MOVL	CHF$L_SIGARGLST(AP),R3	; R3 = address of signal arguments
	BLBS	STOP_FLAG,10$		; Branch if tracing was just turned off
	CMPW	#SS$_TBIT,CHF$L_SIG_NAME(R3) ; Was this a T-bit trap?
	BNEQ	20$			; If not, go to 20$
	MOVL	CHF$L_SIG_ARG1(R3),R0	; R0 = the passed Program Counter value
	JSB	PME_COUNT		; Tally this PC in the proper bucket
	MOVZWL	#SS$_CONTINUE,R0	; Return "continue" status
	BISL2	#PSL$M_TBIT,12(R3)	; Enable the T-bit trap again
	RET				; Return


; The trace is to stop--clear the T-bit and return with normal status
;
10$:	BICL2	#PSL$M_TBIT!PSL$M_TP,12(R3) ; Turn off T-bit trap
	MOVZWL	#SS$_CONTINUE,R0	; Return "continue" status
	RET				;


; This was not a T-bit trap--resignal the exception handler at the next level
;
20$:	MOVZWL	#SS$_RESIGNAL,R0	; Return "resignal" status
	RET				;


; ******************** PME_SFILE:  A DUMMY ROUTINE **************************
;
;
; This dummy subroutine is provided only so that a user who has used the time
; interval sampling method of collecting program counter samples can switch to
; these routines (the trace sampling method) without change to his program.
; Since tracing does not generate a sampling output file (the number of samples
; would be too large), this routine does nothing.
;
	.ENTRY	PME_SFILE,^M<>		; Dummy entry point
	
	RET				; Return immediately

	.END