[Indigo]<DoradoDocs>MicroSample.memo!1

Heading:

Microcode Pc Histogram Sampling for the Dorado

Page Numbers: Yes X: 527 Y: 10.5"

Inter-Office Memorandum

ToDorado UsersDateNovember 30, 1980

FromMcDanielLocationPalo Alto

SubjectMicrocode Pc HistogramOrganizationCSL

Sampling for the Dorado

XEROX

Filed on: <doradodocs>microSample.memo

INTRODUCTION

The files described in this document can be found on,

[ivy]<DoradoSource>MicroSample(Defs).mesa
[ivy]<Dorado>MicroSample(Defs).bcd

This document describes a program that helps the programmer obtain a histogram for the Pc of the Dorado’s microcoded emulator. While the facility is generally available (ie., it is available to all emulators microcoded for the Dorado at the time of this writing), this document describes the Mesa interface, only. This program will be of interest to Mesa instruction set implementors, to people who create user microcode, and to those who wish to measure the microcode performance of programs executing on the Dorado. This document presumes familiarity with the Dorado hardware manual, the Dorado microcode assembler manual, and the Mesa language and system. While this program provides the user with a mechanism for acquiring the histogram data, it does not provide a mechanism for data analysis. At this writing there are two programs, a Lisp program written by Larry Masinter and a Bcpl program written by Peter Deutsch, that can analyze Dorado Pc-Histogram data, given both the data and the microcode .MB file.

The definitions file, MicroSampleDefs.mesa (.bcd) provides the user interface while MicroSample.mesa implements the Mesa-specific interface to the microcode.

MicroSample provides the user with an interface that will allocate storage outside the MDS, turn on and off data collection, and save the data on a file. Ambitious users could dispense with the MicroSample implementation by writing their own MACHINE CODE procedure that accesses the miscellaneous opcode that turns-on the microcode.

The Dorado’s junk task (which awakens every 32 microseconds) implements the microcode Pc-sampling feature. The junk task samples the emulator task’s current Pc by incrementing a LONG CARDINAL in memory. Thus, if the emulator spends 15% of its time at some absolute location in the microcode (say location 1234B), then the entry for location 1234B will contain 15% of all the counts. The microcode requires a long pointer to an array of LONG CARDINALS. The microcode uses the emulator’s Pc as the index into that array. Access to the microcode facility is provided by the miscellaneous opcode: the alpha byte is 243B and the single parameter is a LONG POINTER to an array of LONG CARDINALs of length equal to the size of the Dorado’s microinstruction memory. For brevity the term HistData will refer to that array of LONG CARDINALS.

While the microcode actively touches HistData, the implementation uses cleanup procedures to pause or resume sampling when the user enters or exits the Mesa debugger.

PROCEDURES

The procedure setMicroPcSampling which is defined below causes the microcode to keep histogram data. The single parameter is a LONG POINTER to HistData. If that pointer is NIL, the junk task stops collecting histogram data.

setMicroPcSampling: PROCEDURE[p: MicroSampleDefs.tlprMicroPcData]=
MACHINE CODE BEGIN
Mopcodes.zMISC, 243B;
END;

The basic facilites implemented by MicroSample are to start sampling, to save the results on a file and to stop sampling. The procedures that accomplish this are described below.

startMicroSampling: PROCEDURE;
saveMicroSamples: PROCEDURE;
saveMicroSamplesOnFile: PROCEDURE[n: STRING];
stopMicroSamples: PROCEDURE;

The procedure startMicroSampling generates the signal notRunnningOnDorado if that is the case. Otherwise it uses NewDataSegment to allocate storage outside the MDS. This routine zeros HistData and then it turns on the microcoded Pc sampling.

The procedure saveMicroSamples saves the HistData on the default file that is named, "MicroSamples.Counts" by calling the procedure saveMicroSamplesOnFile.

The procedure saveMicroSamplesOnFile["fileName"] opens a new word stream and dumps the contents of HistData onto the indicated file. Then it destroys the stream.

The procedure stopMicroPcSampling turns off the microcode that collects emulator Pc values, it deallocates HistData, and removes the cleanup procedure.

The additional procedures described below provide further flexibility for users who may have complicated requirements.

pauseMicroSampling: PROCEDURE;
resumeMicroSampling: PROCEDURE;
resetMicroPcData: PROCEDURE;
onDorado: PROCEDURE RETURNS[BOOLEAN];
longZero[lp: LONG POINTER, count: CARDINAL];

The procedure pauseMicroSampling turns off the microcode that collects samples. This routine does not touch HistData. The implementation removes its cleanup routine when the user calls this procedure.

The procedure resumeMicroSampling turns on, again, the microcode that collects emulator Pc values. The user invokes this procedure after calling pauseMicroSampling. The implementation adds its cleanup routine when when the user calls this procedure. If the startup procedure has not yet been called, this routine generates the signal, noAllocatedMicroPcBuffer.

The procedure resetMicroPcData zeros HistData.

The routine onDorado returns TRUE if MicroSample is executing on a Dorado.

The routine longZero takes a LONG POINTER and a CARDINAL. It zeros count words beginning at location lp.

OTHER ATTRIBUTES

The READONLY LONG POINTER lpHistData points to HistData.

The signal notRunningOnDorado indicates that MicroSample has been called and the processor is not a Dorado. At the time of this writing the only the Dorado supports the facilites described here.

The signal noAllocatedMicroPcBuffer indicates that the user has tried to do something that implied the existence of HistData and it (HistData) does not exist. Either the user has not yet invoked the startMicroSampling procedure, or the user has called the stopMicroSampling procedure which deallocated HistData.

The definitions file includes various type definitions that may be of interest to ambitious users. They are self evident in that they provide a Mesa description of the HistData. Current limitations in the compiler prevent making a straightforward declaration for HistData.

c: McDaniel