This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Language Reference, updated
- From: Robb Romans <robb at linux dot vnet dot ibm dot com>
- To: SystemTap <systemtap at sources dot redhat dot com>, Mike Mason <mmlnx at us dot ibm dot com>
- Date: Mon, 12 Feb 2007 13:22:11 -0600
- Subject: Re: Language Reference, updated
- Organization: IBM
- References: <200611221532.39260.robb@linux.vnet.ibm.com> <457EFCF6.1020001@us.ibm.com> <87y7nkgj2l.fsf@skyhawk.austin.ibm.com>
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi.
I'm resending this, as I received no response. Would anyone be able
to help?
Regards,
Robb
>>>>> "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?
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?
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?
MM> Sections 4.1.1 & 4.1.2 Need descriptions.
For prefixes and suffixes, I am not sure how to correctly document these
terms.
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.
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.
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.
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?
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.
I added a section to document dbug() in 9.1.1. If appropriate, I could
use an example and some text for this.
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.
MM> Section 9.2.21 Explain what is meant by the "target process."
Does this mean the PID of the program being probed?
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?
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/>
iD8DBQFF0L5jZyOifwSFgjQRAg6UAJ4y/ol4uDOqu16n3Q+V9ZJk4d6FSwCfa4lJ
2NR/8yA0G+29dWR1hen7y08=
=xQV+
-----END PGP SIGNATURE-----