This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: [Bug translator/5679] inline documentation for scripts/tapsets
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: systemtap at sources dot redhat dot com
- Date: Fri, 8 Feb 2008 19:04:24 -0500
- Subject: Re: [Bug translator/5679] inline documentation for scripts/tapsets
- References: <20080126023636.5679.fche@redhat.com> <20080208232658.17393.qmail@sourceware.org>
Hi -
mhiramat wrote:
> I have a question about this syntax.
>
> What happened in following case?
> if (cond) {
> var = $var1 @@ "this is var1"
> } else {
> var = $var2 @@ "this is var2"
> }
Good question. The "@@" binds at elaboration time (i.e., not at run
time, so ordinary conditions cannot be evaluated, but preprocessor
conditionals are). Multiple "@@" operators on the same variable are
additive. So this would result in "var" being documented with both
strings.
> AFAIK, some probe alias (ex. syscall.fork) set variables like as
> above...
Indeed. But remember, we want to document the purpose of the variable
(rather than its actual value on one actual control flow branch, which
is in any case invisible to the user), so one string is enough:
if (cond) { name = "foo" @@ "System call name." }
else { name = "bar" }
By the way, here are some excerpts from what a converted tapset may
look like. It combines information currently in the man pages and in
previous comment blocks, so is best compared to a union of the tapset
source code AND the man page.
----------------------------------------
// IO scheduler tapset
// [...]
probe ioscheduler.elv_next_request
= kernel.function("elv_next_request")
@@ "Probe the retrieval of a I/O request from request queue."
{
elevator_name =
%( kernel_v >= "2.6.10" %?
kernel_string($q->elevator->elevator_type->elevator_name) %:
kernel_string($q->elevator->elevator_name) %)
@@ "The elevator name."
}
probe ioscheduler.elv_add_request
= kernel.function("__elv_add_request")
@@ "Probe adding a request into the I/O request queue."
{
%( kernel_v >= "2.6.10" %?
elevator_name = kernel_string($q->elevator->elevator_type->elevator_name)
%:
elevator_name = kernel_string($q->elevator->elevator_name)
%) @@ "The elevator name."
if($rq == 0) {
disk_major = -1 @@ "Disk major number of the request."
disk_minor = -1 @@ "Disk minor number of the request."
} else {
if($rq->rq_disk == 0) {
disk_major = -1
disk_minor = -1
} else {
disk_major = $rq->rq_disk->major
disk_minor = $rq->rq_disk->first_minor
}
}
req = $rq @@ "Address of the request."
%( kernel_v >= "2.6.19" %?
req_flags = $rq==0? 0:$rq->cmd_flags
%:
req_flags = $rq==0? 0:$rq->flags
%) @@ "Request flags."
}
----------------------------------------
// context tapset
// [...]
function print_regs
@@ "Print a register dump (for kprobes, uprobes, profiling)."
()
%{
if (CONTEXT->regs) {
_stp_print_regs (CONTEXT->regs);
}
%}
function print_backtrace
@@ "Equivalent to print_stack(backtrace()), except that"
@@ "deeper stack nesting may be supported."
()
%{
if (CONTEXT->regs) {
_stp_stack_print(CONTEXT->regs, 1, CONTEXT->pi);
} else {
_stp_printf("Systemtap probe: %s\n", CONTEXT->probe_point);
}
%}
----------------------------------------
// queue_stats.stp
function qsq_utilization
@@ "Return the fraction of time that any request was being serviced."
(qname @@ "Queue name", scale @@ "Time scaling factor") {
elapsed = qs_time() - qs_stime[qname]
return (scale * qs_rtime[qname]) / elapsed
}