Re: [Perftools]Re: tapset howto?

[Martin Hunt <hunt at redhat dot com>]

On Mon, 2005-09-19 at 13:55 -0400, Frank Ch. Eigler wrote:

> > During the next week, I am planning to clean up the runtime docs and
> > work on some library (tapset?) functions.
>
> How would you justify much effort on runtime documentation?

Because people other than you use it and have questions. It is used in
tapsets.  Porting the arch-dependent pieces and testing it is necessary
for supporting new cpus.
  
> > [...] One thing I would like to see [in a "howto"], is some
> > distinction between tapsets and library functions. The difference
> > being that library functions are core functions that are always
> > there. Tapsets are specific to sections of the kernel or
> > modules. [...]
> 
> There is not a substantial difference.  A script in .../tapset can
> contain any mixture of global/probe/probe-alias/function definitions,
> and may satisfy and generate external references with respect to other
> scripts.  The translator attempts to automatically resolve all these
> kinds of references.

>From an implementation standpoint, there is no difference. From a script
developer's standpoint, there is a huge difference. We need to collect
utility functions, that basically extend the language, group them
together and document them well. That way all scripts and tapsets can
make use of them.

> > We need some standard for documenting tapset functions. 
> 
> Like stapfuncs(5), stapprobes(5), and future stapvars(5)?  Maybe
> slicing the same content up "horizontally" (by tapset rather than by
> exported artifact category) would also make sense, and maybe this can
> be accomplished by mechanical means.

When we have a few dozen tapsets, I think you will not enjoy paging
through enormous man pages. Each tapset needs to be documented
individually and the tapset documentation automatically merged by some
means. And it needs to be easily searchable and indexed.

> > We need a standard for naming tapset functions. [...]
> 
> Indeed, a naming convention will be useful.  One part could be to name
> script-internal (undocumented == "unexported") objects with a leading
> "_".  Including the tapset name in all names would be good in cases of
> forseeable conflict.
> 

I agree.

Martin