public inbox for systemtap@sourceware.org
 help / color / mirror / Atom feed
From: Robb Romans <robb@linux.vnet.ibm.com>
To: SystemTap <systemtap@sources.redhat.com>, Mike Mason <mmlnx@us.ibm.com>
Subject: Re: Language Reference, updated
Date: Mon, 12 Feb 2007 19:22:00 -0000	[thread overview]
Message-ID: <8764a7w598.fsf@skyhawk.austin.ibm.com> (raw)
In-Reply-To: <87y7nkgj2l.fsf@skyhawk.austin.ibm.com> (Robb Romans's message of "Tue, 30 Jan 2007 18:01:54 -0600")

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

  reply	other threads:[~2007-02-12 19:22 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2006-11-24 21:52 Robb Romans
2006-11-29  1:07 ` Martin Hunt
2006-11-29  7:44   ` Robb Romans
2006-12-06 17:14   ` Robb Romans
2006-12-06 18:41     ` Martin Hunt
2006-12-06 19:51       ` Robb Romans
2006-12-12 20:45 ` Mike Mason
2007-01-31  0:02   ` Robb Romans
2007-02-12 19:22     ` Robb Romans [this message]
2007-02-13 19:54       ` Frank Ch. Eigler
2007-02-16 23:59         ` Mike Mason
2007-02-17  0:39           ` Stone, Joshua I
2007-02-22 20:59         ` Robb Romans
2007-02-27 17:58     ` Mike Mason
2007-02-27 18:08       ` Robb Romans
2007-02-27 19:03         ` Robb Romans
2006-12-12 21:24 Stone, Joshua I
2006-12-12 22:19 ` Frank Ch. Eigler

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8764a7w598.fsf@skyhawk.austin.ibm.com \
    --to=robb@linux.vnet.ibm.com \
    --cc=mmlnx@us.ibm.com \
    --cc=systemtap@sources.redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).