What is a tapset?

[Vara Prasad <prasadav at us dot ibm dot com>]

What is a tapset?

In the last weeks call people expressed concern that the concept of 
tapset is not clear and well defined. This is my attempt to define it. 
If any of the concepts presented here are not clear please let me know 
what specifics are not well defined and clear. If you don't agree with 
some or part of the concepts please let me know and propose an 
alternative. My goal is to come to an agreement among all of us in the 
team about tapset in the next couple of days so we can present the same 
in OLS. I tried to cover the very basics that all the tapsets (i.e. 
script based and C based) should have. There may be other additional 
extensions that some tapsets might have but those are outside the scope 
of this paper.

Kprobes is the basic mechanism used by systemtap to get the control of 
execution in the case of synchronous probes. Kprobes requires specifying 
an address at which a trap/break instruction can be put and a function 
a.k.a. probe handler that runs when the trap/break instruction is 
executed. In the case of asynchronous events h/w is programmed to 
generate an interrupt when an event occurs and an interrupt handler is 
executed to handle the interrupts.

Every tapset function defines two items a probe point and a piece of 
code that exports some data that the tapset author feels relevant to 
understand the behavior of the system.

probepoint:  A "probepoint" may specify a particular code location (e.g. 
kernel.function("printk")) or it may specify an asynchronous
event (e.g., perfcounter("tlbmiss").count(4000)).

tapset code: For each probepoint, a piece of code that makes available 
named values a.k.a. "exported variables" that an end user can refer to 
in their scripts. I mentioned it as a piece of code to indicate that it 
can be written in scripting language or "C". There seems to be an 
agreement to a good extent that we can make tapset code as a 
procedure/function, although it is not a must. I like the idea of
making this as a procedure/function so that one can write this piece of 
code independently and packaged independently. NOTE: tapset code is not 
same as the probe handler, more about these two later.

tapset: A tapset is a collection of such "probepoint and tapset code" 
pairs in a related area. There are no rules in how one group these pairs 
into tapsets, it is based what makes a logical group from functionality 
and usage point of view.

Probe handler: It is a function that gets called when the probe point is 
hit. When users use systemtap, systemtap translator ALWAYS generates the 
probe handler and end users DIRECTLY DON'T write the probe handlers 
themselves unlike raw kprobes interface.

Relationship between probe point, tapset code and probe handler: Probe 
point defines where to put the trap instruction for kprobes or what 
events to monitor in the case of asynchronous events. Systemtap 
generates the probe handler and  it gets executed when the probepoint is 
hit. If the end user script refers to the variables exported by the 
associated tapset code Systemtap will call/include the tapset function 
code while generating the handler otherwise not. So just to reiterate 
tapset function will always be called by the probe handler but not 
directly by the end users. Call to tapset function is optional based on 
if end user script refers to the exported variables or not.