Re: Language Reference, updated

[Mike Mason <mmlnx@us.ibm.com>]

Robb Romans wrote:
> I've updated the draft Language Reference. Here it is in gzipped LaTeX 
> and PostScript. Comments welcome.
> 
> Regards,
> Robb
> 

Hi Rob,

Sorry for not getting comments to you sooner.  Here they are.  Some are actually questions which need an answer from the mailing list.

Section 1.2
This section only mentions developers as potential users.  A second major audience is system administrators. Add something like this: "SystemTap also allows system administrators to easily write scripts that gather and manipulate data from the kernel that is not otherwise available using standard Linux tools."

I also think the sentence that mentions Kprobes can be removed, though I could be convinced otherwise.  I just don't think it's relevant here, especially since it's not mentioned anywhere else in the document.

Section 1.4, 1st paragraph
Also mention "War Stories" section on SystemTap wiki.
http://sourceware.org/systemtap/wiki

Section, 1.4.3, last sentence
The built in limits (MAXACTION, MAXNESTING, etc) deserve their own section describing what they are, how they're used and how to change them.  This should be fairly early in the document.

Section 2.2
Mention that tapset scripts look just like regular systemtap scripts, but they cannot be run directly.

Section 3.2
Mention that probe aliases can also refer to one or more other aliases.

Example:

probe socket.sendmsg = kernel.function ("sock_sendmsg") { ... }
probe socket.do_write = kernel.function ("do_sock_write") { ... }
probe socket.send = socket.sendmsg, socket.do_write {}

Section 3.3
Mention that arrays must be declared as global.  No local arrays allowed.

Section 3.6
Mention use of the deref() macro in embedded C for safety.  Give an example.

Section 4.1
This section mentions probe points to catch "counters rolling over".  Is this really supported?

Sections 4.1.1 & 4.1.2
Need descriptions.

Section 4.1.4
Optionalness!? Please rewrite to get rid of this word :-) 

Sections 4.2.1 - 4.2.5, 4.2.7 & 4.3.1
Need more explanation

Section 4.4
Remove "in some sequence", both places.  Begin and end probes can now be given a sequence number to control the order they are run.  If no sequence number is given, it defaults to 0.  Sequence numbers can be both positive and negative.  This is especially useful for tapset writers who may need to do some initialization in a begin probe.

Example:

In tapset file:
probe begin(-1000) { ... }

In user script:
probe begin { ... }

The user script begin probe defaults to sequence number 0, so the tapset begin probe will run first.

Section 5.1, latter half of 1st paragraph
Needs clean up and more explanation.

Section 5.6.11
Mention that the number of index values must match the number of indexes previously specified.

Section 5.7
Change "All strings are limited in length ..." to "All strings are limited in length to MAXSTRINGLEN, which defaults to 128 bytes."  Then refer back to the new limits section requested above.

Sections 5.7.2 & 5.7.3
Could use some examples.

Section 5.8.2
Clarify the difference between kernel_vr and kernel_v.  I think the info is there, I just think it would be better to explicitly explain the difference.

Section 6, 1st paragraph
The reference to statements being limited to "some number" should instead say they're limited to MAXACTION, which defaults to 1000. Then refer back to the new limits section requested above.

Section 6.0.6
Not sure why this is here. Remove.

Section 6.0.15
I'm not sure why you'd ever use a ';' by itself instead of a newline.  Explain further why you'd want to do that if, in fact, it's valid.

Section 7.3
Add explanation.

Section 7.4
Mention that MAXMAPENTRIES defaults to 2048, then refer back to the new limits section requested above.

Sections 8.4.1 - 8.4.3
Show examples of the output that results from using these functions.

Section 9.1.2
Mentions the "common trace buffer."  Users probably don't know about or care about the buffer, so remove the reference.  Simply say that log() prints the given string.

Section 9.1.3
Mentions that it prints an integer, string, or statistics value, but doesn't show how you specify them.  Also remove reference to "common trace buffer."

Section 9.1.8
Mentions "warning stream", but says nothing about what that is or what the result of using this function will be (i.e, prints the string with "WARNING:" prepended).

Sections 9.2.4 & 9.2.5
Question for mailing list:  what's the point of having both cpu() and cpuid()?  They both appear to give the same number (current cpu #).

Section 9.2.21
Explain what is meant by the "target process."

Sections 9.4 & 9.5
Add a good example of how to use the queuing functions.  I've attempted to use them and found them confusing.

Section 9.5.4
Mention that qsq_start is also how you create a queue.

Section 9.7.1
Mention that ctime always prints GMT.

Section 9.9
I think we should remove subsystem-specific functions from this document.  There are quite a few beyond just TCP already and many more will be added as we expand the tapsets.  Keeping this document up-to-date with those functions will be difficult.  Instead I suggest we document the subsystem-specific functions in the tapset-specific man pages (stapprobes.tcp(5) in this case).

Section 10

Also mention the tapset-specific man pages.  Perhaps just say run "apropos stapprobes" for a complete list:

Example:

# apropos stapprobes
stapprobes           (5)  - systemtap probe points
stapprobes.iosched [stapprobes] (5)  - systemtap IO scheduler probe points
stapprobes.netdev [stapprobes] (5)  - systemtap network device probe points
stapprobes.nfs [stapprobes] (5)  - systemtap NFS client side probe points
stapprobes.nfsd [stapprobes] (5)  - systemtap NFS server side probe points
stapprobes.pagefault [stapprobes] (5)  - systemtap pagefault probe points
stapprobes.process [stapprobes] (5)  - systemtap process probe points
stapprobes.rpc [stapprobes] (5)  - systemtap SunRPC probe points
stapprobes.scsi [stapprobes] (5)  - systemtap scsi probe points
stapprobes.signal [stapprobes] (5)  - systemtap signal probe points
stapprobes.tcp [stapprobes] (5)  - systemtap tcp probe points
stapprobes.udp [stapprobes] (5)  - systemtap udp probe points


That's it for now.  Again, sorry for the delay.

Mike Mason