This is the mail archive of the mailing list for the systemtap project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Language Reference, updated


Sorry for the delay. Here's what I have so far. More to come.


Robb Romans wrote:
Hash: SHA1

"MM" == Mike Mason <> 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

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

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 ARS NA5TT
.-- - ..-. ..--..
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <>


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]