Contribute DebugCounter documentation #340
Conversation
amankumar1
force-pushed
the
DebugCounterDoc
branch
from
eac63b1
to
d48b3f0
Compare
| @@ -0,0 +1,126 @@ | |||
| # Debug Counter | |||
|
|
|||
| A debug counter is a facility for adding instrumentation to jitted code to count arbitrary things. | |||
There was a problem hiding this comment.
There is also an incStaticDebugCounter which can be used to count things at compile-time. Perhaps a better introduction would be to say debug counters are a general infrastructure for counting things. There are two flavours - static and dynamic. Static counters do not add anything to the code generated by the compiler, but server to count events at compile-time while dynamic counters are incremented at runtime and are used to count events in code generated by the compiler.
|
|
||
| ## Naming Scheme | ||
|
|
||
| The name of a counter can affect its behaviour, and its relationship with other counters. Special characters in a counter name signal the debug counter facility to treat a counter in a special way. |
There was a problem hiding this comment.
The name does not affect the counter behaviour - it modifies the display processing logic for counters which affects how the results are shown to the user - the raw counter will continue to bump in the same way.
| ``` | ||
| export TR_DebugCounterFileName=debugcounters.txt | ||
| ``` | ||
| Setting the option to `debugCounters={*}` will output all dynamic debug counters. |
There was a problem hiding this comment.
This is not a useful thing in general due to the nature of debug counters and is probably not worth documenting.
amankumar1
force-pushed
the
DebugCounterDoc
branch
2 times, most recently
from
b76d0b0
to
da187fa
Compare
|
@andrewcraik Documentation updated. |
|
Thanks for accommodating those changes. To round out the documentation it also should discuss incStaticDebugCounter which creates a static debug counter without a dynamic counterpart. These are used quite a bit in the optimizer to count compile events that we do not need or cannot count at runtime. That is to say static only counters can and do exist, dynamic counters get static counterparts by default since knowing the ratio of the number of counters inserted vs the number of counter bumps observed at runtime is a generally useful thing for a dynamic counter. |
|
Do you think having example usage(s) shown in the documentation would be useful ? It might serve as a quick reminder on what the syntax is, rather than have to read the full documentation. |
|
Yes - perhaps having a 'Quick Summary' section with example syntax and the full documentation below might help and addition to the incStaticDebugCounter notes. |
amankumar1
force-pushed
the
DebugCounterDoc
branch
4 times, most recently
from
bb77706
to
dda84dc
Compare
|
@vijaysun-omr @andrewcraik Added example syntax and made some other minor changes and additions. |
|
One more small request : please added the -Xjit command lines one would need to use for the examples you showed. Thanks. |
Contribute compiler/ras/DebugCounter.md. Documenation constains information about using debug counters, different types of debug counters, naming schemes, and specifying output. [ci skip] Documentation Signed-off-by: Aman Kumar <[email protected]>
amankumar1
force-pushed
the
DebugCounterDoc
branch
from
dda84dc
to
48ee8cb
Compare
|
@vijaysun-omr Added the command line options for the examples. |
|
Looks good. Thanks Aman. |
Contribute compiler/ras/DebugCounter.md.
Documenation constains information about using debug counters,
different types of debug counters, naming schemes, and
specifying output.
Signed-off-by: Aman Kumar [email protected]