Language Reference, updated
Mike Mason
mmlnx@us.ibm.com
Tue Feb 27 17:58:00 GMT 2007
Robb,
Sorry for the delay. Here's what I have so far. More to come.
Mike
Robb Romans wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>>>>>> "MM" == Mike Mason <mmlnx@us.ibm.com> writes:
>
> Mike, thanks for the great feedback. I have implemented most of your
> suggestions, except for a remaining few where I have questions.
>
> In section 3.2.4, "Unused alias variables", where is a good explanation
> for this section?
Looks like your updated doc has an accurate description for this section.
>
> MM> Section 3.6 Mention use of the deref() macro in embedded C for
> MM> safety. Give an example.
>
> I could use a little help with this. Would anyone be able to provide a
> good working example?
In the sentence that starts "There are a number of undocumented..." I
change it as follows:
"There are a number of undocumented but complex safety constraints on
concurrency, resource consumption and runtime limits that are applied
to code written in the SystemTap language. These constraints are not
applied to embedded C code, so use with caution."
Here's what I would say about kread():
One of the safety mechanisms automatically used in the generated C code
is the kread() macro. This macro protects against pointer accesses that
could crash the system. Embedded C is used verbatim, so you must
explicitly use kread() for any pointer accesses that are at all suspect.
For example, to access the following pointer chain in embedded C:
name = skb->dev->name
do the following:
struct net_device *dev;
char *name;
dev = kread(&(skb->dev));
name = kread(&(dev->name));
>
> MM> Section 4.1 This section mentions probe points to catch
> MM> "counters rolling over". Is this really supported?
>
> I've removed that verbiage. OK?
Fine with me.
>
> MM> Sections 4.1.1 & 4.1.2 Need descriptions.
>
> For prefixes and suffixes, I am not sure how to correctly document these
> terms.
Leave as-is. The details of prefixes and suffixes are described in section 4.2.
>
> MM> Sections 4.2.1 - 4.2.5, 4.2.7 & 4.3.1 Need more explanation
>
> I found information on these sections from the man page description of
> "dwarf probes." That info is pretty much contained verbatim in Section
> 4.2 "Built-in probe point types (Dwarf probes)." There is some
> redundancy with the following subsections 4.2.1 - 4.2.4. I could use
> some direction on how to sort out the overlap, and how to better
> document the subsections.
I'll help with this in a follow-on email.
>
> MM> Sections 5.7.2 & 5.7.3 Could use some examples.
>
> (Now 5.7.1 and 5.7.2)
> I could use help finding appropriate examples here.
Add Section 5.7.3 Example:
For example, if the following script(example.stp):
probe begin { printf("%d, %s\n", $1, @2) }
is invoked as follows:
# stap example.stp 10 mystring
then 10 is substituted for $1 and "mystring" for @2.
The output will be:
10, mystring
>
> MM> Section 6.0.6 Not sure why this is here. Remove.
>
> I left in the reference to "-" and added a link to associative
> arrays. Let me know the right thing to do.
I don't think this has anything to do with associative arrays. I'm not sure what "- (delete) <name>" is telling me. Unless we can come up with an example of it's use, I still think it should be removed.
>
> MM> Section 6.0.15 I'm not sure why you'd ever use a ';' by itself
> MM> instead of a newline. Explain further why you'd want to do that
> MM> if, in fact, it's valid.
>
> (Now 6.0.16)
> I read the subsequent email exchange. Should I modify the text here?
> Include an example?
Leave as is for now.
>
> MM> Section 7.3 Add explanation.
>
> I could use some direction here.
>
> MM> Sections 8.4.1 - 8.4.3 Show examples of the output that results
> MM> from using these functions.
>
> I'd like to be provided with self-contained examples that I can
> document, run and capture the output.
hist_linear example script:
global reads
probe netdev.receive { reads <<< length }
probe end { print(@hist_linear(reads, 0, 10240, 200)) }
Output from script:
value |-------------------------------------------------- count
0 | 258
200 | 3
400 | 0
600 | 1
800 | 2
1000 | 4
1200 | 1
1400 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 16685
1600 | 0
1800 | 0
hist_log example script:
global reads
probe netdev.receive { reads <<< length }
probe end { print(@hist_log(reads)) }
Output from script:
value |-------------------------------------------------- count
8 | 0
16 | 0
32 | 254
64 | 3
128 | 2
256 | 2
512 | 4
1024 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 16689
2048 | 0
4096 | 0
>
> I added a section to document dbug() in 9.1.1. If appropriate, I could
> use an example and some text for this.
dbug() is an internal function used print debug statements in
the runtime code. It shouldn't be included in the language reference.
>
> MM> Section 9.1.3 Mentions that it prints an integer, string, or
> MM> statistics value, but doesn't show how you specify them. Also
> MM> remove reference to "common trace buffer."
>
> I am confused a bit by the logging functions, their inputs and outputs,
> and syntax. Any clues here would be great.
>
> MM> Section 9.1.8 Mentions "warning stream", but says nothing about
> MM> what that is or what the result of using this function will be
> MM> (i.e, prints the string with "WARNING:" prepended).
>
> I didn't find what you were referring to here. Do you mean "error
> stream"? Is there a better place to find documentation on these
> functions?
>
> MM> Sections 9.2.4 & 9.2.5 Question for mailing list: what's the
> MM> point of having both cpu() and cpuid()? They both appear to
> MM> give the same number (current cpu #).
>
> I didn't see an answer to this. I'll be happy to change the guide to be
> more correct.
Remove any mention of cpuid().
>
> MM> Section 9.2.21 Explain what is meant by the "target process."
>
> Does this mean the PID of the program being probed?
The following stap options set the target pid:
-x <pid> target() returns the pid specified by -x
-c <command> target() returns the pid for the <command> that's
run by specifying -c.
>
> MM> Sections 9.4 & 9.5 Add a good example of how to use the queuing
> MM> functions. I've attempted to use them and found them confusing.
>
> Let me know if I've inserted a sufficient example.
>
> MM> Section 9.9 I think we should remove subsystem-specific
> MM> functions from this document. There are quite a few beyond just
> MM> TCP already and many more will be added as we expand the
> MM> tapsets. Keeping this document up-to-date with those functions
> MM> will be difficult. Instead I suggest we document the
> MM> subsystem-specific functions in the tapset-specific man pages
> MM> (stapprobes.tcp(5) in this case).
>
> I didn't see any response to your suggestion. What's the verdict on
> removing these sections?
The consensus from those who expressed an opinion is we should remove them.
>
> Thanks.
> Robb
>
>
>
> ------------------------------------------------------------------------
>
>
>
> - --
> Robb Romans (512) 838-0419
> Linux Commando T/L 678-0419
> robb@linux.vnet.ibm.com ARS NA5TT
> .-- - ..-. ..--..
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.6 (GNU/Linux)
> Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>
>
> iD8DBQFFv9xyZyOifwSFgjQRApIvAJ9mjIXdLqxwMWBGCnmEx4Qmqu1CVACeNhwN
> +hnLvV0yKHGFgUY41dP9G4k=
> =2ZFw
> -----END PGP SIGNATURE-----
More information about the Systemtap
mailing list