From 13e0ecd5fe642a243f98090d73cc4aa7bd699cff Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Mon, 3 Sep 2012 15:28:57 +0100 Subject: [PATCH] Removed basic untruths and added some discussion of debugging, though this starts to resemble a manual rather than a design document, and needs to be reworked. Copied from Perforce Change: 179203 ServerID: perforce.ravenbrook.com --- mps/design/telemetry/index.html | 143 +++++++++++++++++++------------- 1 file changed, 86 insertions(+), 57 deletions(-) diff --git a/mps/design/telemetry/index.html b/mps/design/telemetry/index.html index 167613215ef..4807a058df2 100644 --- a/mps/design/telemetry/index.html +++ b/mps/design/telemetry/index.html @@ -234,10 +234,7 @@ IMPLEMENTATION: Annotation .annot: An event annotation is of the form: - EVENT_PAW(FooCreate, pointer, address, word); - -.annot.format: Note that the format is indicated in the macro name. See -.format. + EVENT3(FooCreate, pointer, address, word); .annot.string: If there is a string in the format, it must be the last parameter (and hence there can be only one). There is currrently a maximum @@ -247,29 +244,27 @@ string length, defined by EventMaxStringLength in impl.h.eventcom. macro, as registered in impl.h.eventdef. .annot.param: The parameters of the event should be given as the remaining -parameters of the event macro, in order as indicated in the format. +parameters of the event macro, in order as indicated in the event parameters definition in impl.h.eventdef. Registration -.reg: All event types should be registered in impl.h.eventdef, in the form of a -relation. +.reg: All event types and parameters should +be registered in impl.h.eventdef, in the form of a higher-order list +macros. -.reg.just: This use of a relation macro enables great flexibility in the use of +.reg.just: This use of a higher-order macros enables great flexibility in the use of this file. -.reg.rel: The relation is of the form: - RELATION(FooCreate, 0x1234, TRUE, Arena, PAW) +.reg.rel: The event type registration is of the form: + EVENT(X, FooCreate, 0x1234, TRUE, Arena) .reg.type: The first parameter of the relation is the event type. This needs no prefix, and should correspond to that used in the annotation. .reg.code: The second parameter is the event code, a 16-bit value used to -represent this event type. [Not yet used. GavinM 1997-07-18] - -.reg.code.temp: On an interim basis, new events also have to be registered in -impl.h.eventcom. This will no longer be required when the event file format is -revised. +represent this event type. Codes should not be re-used for new event types, to allow interpretation of event +log files of all ages. .reg.always: The third parameter is a boolean value indicating whether this event type should be implemented in all varieties. See .control.buffer. @@ -284,10 +279,39 @@ event falls into. See .control. The possible values are: Seg -- per segment Ref -- per reference or fix Object -- per object or allocation -This list can be seen in impl.h.event. + User -- invoked by the user through the MPS interface +This list can be seen in impl.h.eventcom. -.reg.format: The fifth parameter is the format (see .format) and should -correspond to the annotation (see .annot.format). +[.reg.doc: Add a docstring column. RB 2012-09-03] + +.reg.params: The event parameters registration is of the form: + + #define EVENT_FooCreate_PARAMS(PARAM, X) \ + PARAM(X, 0, P, firstParamPointer) \ + PARAM(X, 1, U, secondParamUnsigned) + +.reg.param.index: The first column is the index, and must start at zero +and increase by one for each row. + +.reg.param.sort: The second column is the parameter "sort", which, when +appended to EventF, yields a type for the parameter. It is a letter from the following list: + P -- void * + A -- Addr + W -- Word + U -- unsigned int + S -- char * + D -- double + B -- Bool +The corresponding event parameter must be assignment compatible with the type. + +.param.types: When an event has parameters whose type is not in the above +list, use the following guidelines: All C pointer types not representing +strings use P; Size, Count, Index use W; others should be obvious. + +.reg.param.name: The third column is the parameter name. It should be a valid C identifier +and is used for debugging display and human readable output. + +[.reg.param.doc: Add a docstring column. RB 2012-09-03] .reg.dup: It is permissible for the one event type to be used for more than one annotation. There are generally two reasons for this: @@ -297,69 +321,65 @@ Note that all annotations for one event type must have the same format (as implied by .reg.format). -Format - -.format: Where a format is used to indicate the type, it is a sequence of -letters from the following list: - P -- void * - A -- Addr - W -- Word - U -- unsigned int - S -- char * - D -- double -The corresponding event parameters must be assignment compatible with these -types. - -.format.zero: If there are no parameters for an event, then the special format -"0" should be used. - -.format.types: When an event has parameters whose type is not in the above -list, use the following guidelines: All C pointer types not representing -strings use P; Size, Count, Index use W; Bool use U; others should be obvious. - -.format.support: Every format used needs bespoke support in impl.h.eventgen. -It has not been possible to provide support for all possible formats, so such -support is added when required. .format.support.auto: There is a tool in -impl.pl.eventgen that will generate impl.h.eventgen automatically. It is used -as follows: - 1. Claim the file eventgen.h. - 2. Invoke eventgen.pl. - 3. Check it compiles correctly in all varieties. - 4. Check in eventgen.h. - - Control .control: There are two types of event control, buffer and output. .control.buffer: Buffer control affects whether particular events implemented at all, and is controlled statically by variety using the always value (see -.reg.always) for the event type. This is only relevant to release varieties. -[Not yet implemented. GavinM 1997-07-18] +.reg.always) for the event type. The hot variety does compiles out annotations +with always=FALSE. The cool variety does not, so always buffers a complete +set of events. .control.output: Output control affects whether events written to the internal buffer are output via the plinth. This is set on a per-kind basis (see .reg.kind), using a control bit table stored in EventKindControl. By default, -all event kinds are on (in variety.ti). You may switch some kinds off using a +all event kinds are off. You may switch some kinds on using a debugger. For example, to disable Ref events using gdb (see impl.h.event for numeric codes): - break ArenaCreate + break TraceCreate run delete 1 - call BTRes(EventKindControl, 4) + print EventKindControl |= 4 continue +.control.env: The initial value of EventKindControl is read from the C environment +when the ANSI Plinth is used, and so event output can be controlled like this: + + MPS_TELEMETRY_CONTROL=127 amcss + .control.just: These controls are coarse, but very cheap. -.control.external: There will be an MPS interface function to control -EventKindControl. +.control.external: The MPS interface function mps_telemetry_control +can be used to change EventKindControl. .control.tool: The tools will be able to control EventKindControl. +Debugging + +.debug.buffer: Each event kind is logged in a separate buffer, EventBuffer[kind]. + +.debug.buffer.reverse: The events are logged in reverse order from the top of the buffer, with the last logged +event at EventLast[kind]. This allows recovery of the list of recent events using the event->any.size field. + +.debug.dump: The contents of all buffers can be dumped with the EventDump function from a debugger, e.g. + + gdb> print EventDump(mps_lib_get_stdout()) + +.debug.describe: Individual events can be described with the EventDescribe function, e.g. + + gdb> print EventDescribe(EventLast[3], mps_lib_get_stdout()) + +.debug.core: The event buffers are preserved in core dumps and can be used +to work out what the MPS was doing before a crash. Since the kinds correspond +to frequencies, ancient events may still be available in some buffers, even +if they have been flushed to the output stream. Some digging may be required. + + Dumper Tool .dumper: A primitive dumper tool is available in impl.c.eventcnv. For details, @@ -377,7 +397,6 @@ TEXT: .notes: - Set always to FALSE for all Ref and Object events; - - Fix use of BT for size in bytes, guess then check, BTInit; - Resolve protection transgression in impl.h.eventdef; - Make EventKind* enum members so they can be used from the debugger. @@ -422,6 +441,16 @@ TEXT: + + + 2012-09-03 + + RB + + Removed basic untruths and added some discussion of debugging, though this starts to resemble a manual rather than a design document, and needs to be reworked. + + +