Re: [PATCH] add block IO documentation to tracepoint docbook

[William Cohen <wcohen@redhat.com>]

Christoph Hellwig wrote:
> On Wed, Jul 01, 2009 at 03:53:49PM -0400, William Cohen wrote:
>> +/**
>> + * block_rq_abort - Abort Block Operation Request
>> + * @q: queue containing the block operation request
>> + * @rq: block IO operation request
>> + *
>> + * Called immediately after pending block IO operation request @rq in
>> + * queue @q is aborted. The fields in the operation request @rq
>> + * can be examined to determine which device and sectors the pending
>> + * operation would access.
>> + */
>>  TRACE_EVENT(block_rq_abort,
> 
> Um, what's the point?  These are not function, but rather trace points.
> The paramters don't actually get exported in the trace files, but the
> printk ring buffer format and the format string do.  So please document
> the formats, and if possible make sure this documentation actually
> appears in debugfs in the trace subdirectory so people get it very easily.
> 


There is already documentation for the irq tracepoints (irq_handler_entry,
irq_handler_exit, softirq_entry, and softirq_exit) in
include/trace/events/irq.h. This was added around the end of April 2009. Threads
discussing those patches:

http://lkml.indiana.edu/hypermail/linux/kernel/0904.3/02647.html
http://lkml.indiana.edu/hypermail/linux/kernel/0904.3/02650.html
http://lkml.indiana.edu/hypermail/linux/kernel/0904.3/02648.html
http://lkml.indiana.edu/hypermail/linux/kernel/0904.3/02651.html

In those previous threads there was no discussion about documenting the printk
ring buffer. The comments in include/linux/tracepoint.h states that functions
with those parameters are generated for the tracespoints. ftrace appears to be
built on top of that mechanism.

It would be nice to have something that describes the format of ftrace output
available in debugfs.  However, there are other things that use the tracepoints
in addition to ftrace and the tracepoint comments are trying to describe what
exactly those events cause those tracepoints to occur. traces/log are useful,
but there are cases where people might prefer not to post-process a large log
file to debug a problem.

-Will