This is the mail archive of the systemtap@sourceware.org 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: [Bug translator/5679] inline documentation for scripts/tapsets


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
}


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