Re: Language Reference, updated

[Robb Romans <robb at linux dot vnet dot ibm dot com>]

-----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?

    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

Attachment: SystemTap-Language-Ref-20070130.tex.gz
Description: SystemTap-Language-Ref-20070130.tex.gz

Attachment: SystemTap-Language-Ref-20070130.ps.gz
Description: SystemTap-Language-Ref-20070130.ps.gz

- -- 
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-----