Skip to contentSkip to conversation

add block IO documentation to tracepoint docbook

PATCH In review William Cohen 4 participants 6 messages Jul 1, 2009 – Jul 8, 2009

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 add block IO documentation to tracepoint docbook

The following patch adds block IO tracepoint documentation to the tracepoint docbook.

Documentation/DocBook/tracepoint.tmpl +13 -0
index b0756d0..41824b2 100644
@@ -16,6 +16,15 @@
      </address>
     </affiliation>
    </author>
+   <author>
+    <firstname>William</firstname>
+    <surname>Cohen</surname>
+    <affiliation>
+     <address>
+      <email>[email protected]</email>
+     </address>
+    </affiliation>
+   </author>
   </authorgroup>
 
   <legalnotice>
@@ -86,4 +95,8 @@
 !Iinclude/trace/events/irq.h
   </chapter>
 
+  <chapter id="block">
+   <title>Block IO</title>
+!Iinclude/trace/events/block.h
+  </chapter>
 </book>
include/trace/events/block.h +154 -0

256 lines not on this page · raw message

#1 lore raw
Quoted 4 lines · On Wed, 01 Jul 2009 15:53:49 -0400 William Cohen wrote:

The following patch adds block IO tracepoint documentation to the tracepoint docbook.

You probably need to cc: someone to merge this unless you already have that worked out...

and the S-O-B: needs a real email address in it.

---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon
http://linuxplumbersconf.org/2009/

Acked-by on v1 1/1
#2 lore raw
In reply to William Cohen

More CCed

Quoted 4 lines · William Cohen

The following patch adds block IO tracepoint documentation to the tracepoint docbook.

Nice, thanks!

Quoted 2 lines

+/**
+ * block_rq_abort - Abort Block Operation Request

Is it necessary to uppercase the first letter of every word?

Quoted 11 lines

+ * @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,

TP_PROTO(struct request_queue *q, struct request *rq),

#4 lore raw
In reply to William Cohen
Quoted 11 lines · William Cohen

+/**
+ * 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.

#5 lore raw
Quoted 13 lines · Christoph Hellwig
Quoted 11 lines · William Cohen

+/**
+ * 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,

Quoted 6 lines

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

#3 lore raw
In reply to Li Zefan
Quoted 8 lines · Li Zefan

More CCed

Quoted 4 lines · William Cohen

The following patch adds block IO tracepoint documentation to the tracepoint docbook.

Quoted 8 lines

Nice, thanks!

Quoted 2 lines

+/**
+ * block_rq_abort - Abort Block Operation Request

Is it necessary to uppercase the first letter of every word?

I was assuming that it was a title. However, lower case would be okay.

-Will

Quoted 14 lines
Quoted 12 lines

+ * @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,

TP_PROTO(struct request_queue *q, struct request *rq),