-- MicroSampleDefs.mesa  GMcD December 2, 1980  5:30 PM 

-- There are detailed comments for the procedures defined here at the end of the file.

--  This public interface allows random users to turn on the micro-pc (ie., microcode Pc-sampling) feature of the Dorado microcode.  The implementation will allocate sufficient storage (outside the MDS) for the feature to work.  When the user is done with an experiment, the data can be saved on a file for later analysis.

--  The micro-pc sampling feature causes the junk task (which awakens every 32 microseconds) to increment a LONG CARDINAL in memory according to the current microcode pc for the emulator task.  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 micro-pc as the index into that array.

-- The routine longZero will generate an error if it is passed NIL.

-- The implementation will generate the SIGNAL notRunningOnDorado  whenever the user tries to access a routine that logically requires the program be running on a Dorado.

-- The implementation will generate the SIGNAL noAllocatedMicroPcBuffer if the user has not invoked the startup procedure "startMicroSampling", and is trying to use a routine that assumes the startup procedure has been called already..

DIRECTORY
  Mopcodes USING [zMISC];

MicroSampleDefs: DEFINITIONS=
BEGIN

-- TYPES

tlprMicroPcData: TYPE = LONG POINTER TO trMicroPcData;
trMicroPcData: TYPE = MACHINE DEPENDENT RECORD[mpc: ARRAY [0..0) OF LONG CARDINAL];

-- CONSTANTS

sizeMicroPcCount: CARDINAL=2;	-- long cardinals
lengthMicroPcData: CARDINAL=10000B;	-- [0..7777B]
sizeMicroPcData: CARDINAL=sizeMicroPcCount*lengthMicroPcData;

-- ROUTINES

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

startMicroSampling: PROCEDURE;
saveMicroSamples: PROCEDURE;
saveMicroSamplesOnFile: PROCEDURE[n: STRING];
stopMicroSampling: PROCEDURE;
pauseMicroSampling: PROCEDURE;
resumeMicroSampling: PROCEDURE;
resetMicroPcData: PROCEDURE;

-- MISCELLANEOUS FEATURES

lpHistData: READONLY tlprMicroPcData;
longZero: PROCEDURE[lp: LONG POINTER, count: CARDINAL];
onDorado: PUBLIC PROCEDURE RETURNS[BOOLEAN];

-- SIGNALS

notRunningOnDorado: SIGNAL;
noAllocatedMicroPcBuffer: SIGNAL;

-- DOCUMENTATION

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

-- saveMicroPcSamples saves the current data on the default file that is named, "MicroSamples.Counts" by calling the procedure "saveMicroSamplesOnFile"

-- saveMicroSamplesOnFile["fileName"] opens a new word stream and dumps the contents of the current micro history onto the indicated file.  Then it destroys the stream.

-- stopMicroPcSampling turns off the microcode that collects emulator Pc values and then it deletes the storage allocated for that function.

-- pauseMicroPcSampling turns off the microcode that collects samples

-- resumeMicroPcSampling turns on, again, the microcode that collects emulator pc values.  If the startup procedure has not yet been called, this routine generates the signal, noAllocatedMicroPcBuffer.

-- resetMicroPcData zeros the storage where the emulator pc values get stored

-- onDorado returns TRUE if the code is currently executing on a Dorado

-- longZero[lp: LONG POINTER, count: CARDINAL] zeros count words beginning at lp.



END.