This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Language Reference, updated
- From: Mike Mason <mmlnx at us dot ibm dot com>
- To: Robb Romans <robb at linux dot vnet dot ibm dot com>
- Cc: SystemTap <systemtap at sources dot redhat dot com>
- Date: Tue, 27 Feb 2007 09:58:06 -0800
- Subject: Re: Language Reference, updated
- References: <200611221532.39260.robb@linux.vnet.ibm.com> <457EFCF6.1020001@us.ibm.com> <87y7nkgj2l.fsf@skyhawk.austin.ibm.com>
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-----