Add DocBook documentation for the block tracepoints.

This patch adds a simple description of the various block tracepoints available in the kernel. Signed-off-by: William Cohen <wcohen@redhat.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Jens Axboe <jens.axboe@oracle.com>

Add DocBook documentation for the block tracepoints.
This patch adds a simple description of the various block tracepoints available in the kernel. Signed-off-by: William Cohen <wcohen@redhat.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Jens Axboe <jens.axboe@oracle.com>
William Cohen · Jens Axboe
1 parent c2282adbde
Showing 2 changed files with 177 additions and 0 deletions Side-by-side Diff
Documentation/DocBook/tracepoint.tmpl
include/trace/events/block.h
@@ -16,6 +16,15 @@
      </address>
     </affiliation>
    </author>
+   <author>
+    <firstname>William</firstname>
+    <surname>Cohen</surname>
+    <affiliation>
+     <address>
+      <email>wcohen@redhat.com</email>
+     </address>
+    </affiliation>
+   </author>
   </authorgroup>
  
   <legalnotice>
@@ -91,5 +100,9 @@
 !Iinclude/trace/events/signal.h
   </chapter>
  
+  <chapter id="block">
+   <title>Block IO</title>
+!Iinclude/trace/events/block.h
+  </chapter>
 </book>
@@ -40,6 +40,16 @@
 		  __entry->nr_sector, __entry->errors)
 );
  
+/**
+ * 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.
+ */
 DEFINE_EVENT(block_rq_with_error, block_rq_abort,
  
 	TP_PROTO(struct request_queue *q, struct request *rq),
@@ -47,6 +57,15 @@
 	TP_ARGS(q, rq)
 );
  
+/**
+ * block_rq_requeue - place block IO request back on a queue
+ * @q: queue holding operation
+ * @rq: block IO operation request
+ *
+ * The block operation request @rq is being placed back into queue
+ * @q.  For some reason the request was not completed and needs to be
+ * put back in the queue.
+ */
 DEFINE_EVENT(block_rq_with_error, block_rq_requeue,
  
 	TP_PROTO(struct request_queue *q, struct request *rq),
@@ -54,6 +73,17 @@
 	TP_ARGS(q, rq)
 );
  
+/**
+ * block_rq_complete - block IO operation completed by device driver
+ * @q: queue containing the block operation request
+ * @rq: block operations request
+ *
+ * The block_rq_complete tracepoint event indicates that some portion
+ * of operation request has been completed by the device driver.  If
+ * the @rq->bio is %NULL, then there is absolutely no additional work to
+ * do for the request. If @rq->bio is non-NULL then there is
+ * additional work required to complete the request.
+ */
 DEFINE_EVENT(block_rq_with_error, block_rq_complete,
  
 	TP_PROTO(struct request_queue *q, struct request *rq),
@@ -95,6 +125,16 @@
 		  __entry->nr_sector, __entry->comm)
 );
  
+/**
+ * block_rq_insert - insert block operation request into queue
+ * @q: target queue
+ * @rq: block IO operation request
+ *
+ * Called immediately before block operation request @rq is inserted
+ * into queue @q.  The fields in the operation request @rq struct can
+ * be examined to determine which device and sectors the pending
+ * operation would access.
+ */
 DEFINE_EVENT(block_rq, block_rq_insert,
  
 	TP_PROTO(struct request_queue *q, struct request *rq),
@@ -102,6 +142,14 @@
 	TP_ARGS(q, rq)
 );
  
+/**
+ * block_rq_issue - issue pending block IO request operation to device driver
+ * @q: queue holding operation
+ * @rq: block IO operation operation request
+ *
+ * Called when block operation request @rq from queue @q is sent to a
+ * device driver for processing.
+ */
 DEFINE_EVENT(block_rq, block_rq_issue,
  
 	TP_PROTO(struct request_queue *q, struct request *rq),
@@ -109,6 +157,17 @@
 	TP_ARGS(q, rq)
 );
  
+/**
+ * block_bio_bounce - used bounce buffer when processing block operation
+ * @q: queue holding the block operation
+ * @bio: block operation
+ *
+ * A bounce buffer was used to handle the block operation @bio in @q.
+ * This occurs when hardware limitations prevent a direct transfer of
+ * data between the @bio data memory area and the IO device.  Use of a
+ * bounce buffer requires extra copying of data and decreases
+ * performance.
+ */
 TRACE_EVENT(block_bio_bounce,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio),
@@ -138,6 +197,14 @@
 		  __entry->nr_sector, __entry->comm)
 );
  
+/**
+ * block_bio_complete - completed all work on the block operation
+ * @q: queue holding the block operation
+ * @bio: block operation completed
+ *
+ * This tracepoint indicates there is no further work to do on this
+ * block IO operation @bio.
+ */
 TRACE_EVENT(block_bio_complete,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio),
@@ -193,6 +260,14 @@
 		  __entry->nr_sector, __entry->comm)
 );
  
+/**
+ * block_bio_backmerge - merging block operation to the end of an existing operation
+ * @q: queue holding operation
+ * @bio: new block operation to merge
+ *
+ * Merging block request @bio to the end of an existing block request
+ * in queue @q.
+ */
 DEFINE_EVENT(block_bio, block_bio_backmerge,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio),
@@ -200,6 +275,14 @@
 	TP_ARGS(q, bio)
 );
  
+/**
+ * block_bio_frontmerge - merging block operation to the beginning of an existing operation
+ * @q: queue holding operation
+ * @bio: new block operation to merge
+ *
+ * Merging block IO operation @bio to the beginning of an existing block
+ * operation in queue @q.
+ */
 DEFINE_EVENT(block_bio, block_bio_frontmerge,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio),
@@ -207,6 +290,13 @@
 	TP_ARGS(q, bio)
 );
  
+/**
+ * block_bio_queue - putting new block IO operation in queue
+ * @q: queue holding operation
+ * @bio: new block operation
+ *
+ * About to place the block IO operation @bio into queue @q.
+ */
 DEFINE_EVENT(block_bio, block_bio_queue,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio),
@@ -243,6 +333,15 @@
 		  __entry->nr_sector, __entry->comm)
 );
  
+/**
+ * block_getrq - get a free request entry in queue for block IO operations
+ * @q: queue for operations
+ * @bio: pending block IO operation
+ * @rw: low bit indicates a read (%0) or a write (%1)
+ *
+ * A request struct for queue @q has been allocated to handle the
+ * block IO operation @bio.
+ */
 DEFINE_EVENT(block_get_rq, block_getrq,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio, int rw),
@@ -250,6 +349,17 @@
 	TP_ARGS(q, bio, rw)
 );
  
+/**
+ * block_sleeprq - waiting to get a free request entry in queue for block IO operation
+ * @q: queue for operation
+ * @bio: pending block IO operation
+ * @rw: low bit indicates a read (%0) or a write (%1)
+ *
+ * In the case where a request struct cannot be provided for queue @q
+ * the process needs to wait for an request struct to become
+ * available.  This tracepoint event is generated each time the
+ * process goes to sleep waiting for request struct become available.
+ */
 DEFINE_EVENT(block_get_rq, block_sleeprq,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio, int rw),
@@ -257,6 +367,14 @@
 	TP_ARGS(q, bio, rw)
 );
  
+/**
+ * block_plug - keep operations requests in request queue
+ * @q: request queue to plug
+ *
+ * Plug the request queue @q.  Do not allow block operation requests
+ * to be sent to the device driver. Instead, accumulate requests in
+ * the queue to improve throughput performance of the block device.
+ */
 TRACE_EVENT(block_plug,
  
 	TP_PROTO(struct request_queue *q),
@@ -293,6 +411,13 @@
 	TP_printk("[%s] %d", __entry->comm, __entry->nr_rq)
 );
  
+/**
+ * block_unplug_timer - timed release of operations requests in queue to device driver
+ * @q: request queue to unplug
+ *
+ * Unplug the request queue @q because a timer expired and allow block
+ * operation requests to be sent to the device driver.
+ */
 DEFINE_EVENT(block_unplug, block_unplug_timer,
  
 	TP_PROTO(struct request_queue *q),
@@ -300,6 +425,13 @@
 	TP_ARGS(q)
 );
  
+/**
+ * block_unplug_io - release of operations requests in request queue
+ * @q: request queue to unplug
+ *
+ * Unplug request queue @q because device driver is scheduled to work
+ * on elements in the request queue.
+ */
 DEFINE_EVENT(block_unplug, block_unplug_io,
  
 	TP_PROTO(struct request_queue *q),
@@ -307,6 +439,17 @@
 	TP_ARGS(q)
 );
  
+/**
+ * block_split - split a single bio struct into two bio structs
+ * @q: queue containing the bio
+ * @bio: block operation being split
+ * @new_sector: The starting sector for the new bio
+ *
+ * The bio request @bio in request queue @q needs to be split into two
+ * bio requests. The newly created @bio request starts at
+ * @new_sector. This split may be required due to hardware limitation
+ * such as operation crossing device boundaries in a RAID system.
+ */
 TRACE_EVENT(block_split,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio,
@@ -337,6 +480,16 @@
 		  __entry->comm)
 );
  
+/**
+ * block_remap - map request for a partition to the raw device
+ * @q: queue holding the operation
+ * @bio: revised operation
+ * @dev: device for the operation
+ * @from: original sector for the operation
+ *
+ * An operation for a partition on a block device has been mapped to the
+ * raw block device.
+ */
 TRACE_EVENT(block_remap,
  
 	TP_PROTO(struct request_queue *q, struct bio *bio, dev_t dev,
@@ -370,6 +523,17 @@
 		  (unsigned long long)__entry->old_sector)
 );
  
+/**
+ * block_rq_remap - map request for a block operation request
+ * @q: queue holding the operation
+ * @rq: block IO operation request
+ * @dev: device for the operation
+ * @from: original sector for the operation
+ *
+ * The block operation request @rq in @q has been remapped.  The block
+ * operation request @rq holds the current information and @from hold
+ * the original sector.
+ */
 TRACE_EVENT(block_rq_remap,
  
 	TP_PROTO(struct request_queue *q, struct request *rq, dev_t dev,
...	...	@@ -16,6 +16,15 @@
16	16	</address>
17	17	</affiliation>
18	18	</author>
	19	+ <author>
	20	+ <firstname>William</firstname>
	21	+ <surname>Cohen</surname>
	22	+ <affiliation>
	23	+ <address>
	24	+ <email>wcohen@redhat.com</email>
	25	+ </address>
	26	+ </affiliation>
	27	+ </author>
19	28	</authorgroup>
20	29
21	30	<legalnotice>
...	...	@@ -91,5 +100,9 @@
91	100	!Iinclude/trace/events/signal.h
92	101	</chapter>
93	102
	103	+ <chapter id="block">
	104	+ <title>Block IO</title>
	105	+!Iinclude/trace/events/block.h
	106	+ </chapter>
94	107	</book>
...	...	@@ -40,6 +40,16 @@
40	40	__entry->nr_sector, __entry->errors)
41	41	);
42	42
	43	+/**
	44	+ * block_rq_abort - abort block operation request
	45	+ * @q: queue containing the block operation request
	46	+ * @rq: block IO operation request
	47	+ *
	48	+ * Called immediately after pending block IO operation request @rq in
	49	+ * queue @q is aborted. The fields in the operation request @rq
	50	+ * can be examined to determine which device and sectors the pending
	51	+ * operation would access.
	52	+ */
43	53	DEFINE_EVENT(block_rq_with_error, block_rq_abort,
44	54
45	55	TP_PROTO(struct request_queue q, struct request rq),
...	...	@@ -47,6 +57,15 @@
47	57	TP_ARGS(q, rq)
48	58	);
49	59
	60	+/**
	61	+ * block_rq_requeue - place block IO request back on a queue
	62	+ * @q: queue holding operation
	63	+ * @rq: block IO operation request
	64	+ *
	65	+ * The block operation request @rq is being placed back into queue
	66	+ * @q. For some reason the request was not completed and needs to be
	67	+ * put back in the queue.
	68	+ */
50	69	DEFINE_EVENT(block_rq_with_error, block_rq_requeue,
51	70
52	71	TP_PROTO(struct request_queue q, struct request rq),
...	...	@@ -54,6 +73,17 @@
54	73	TP_ARGS(q, rq)
55	74	);
56	75
	76	+/**
	77	+ * block_rq_complete - block IO operation completed by device driver
	78	+ * @q: queue containing the block operation request
	79	+ * @rq: block operations request
	80	+ *
	81	+ * The block_rq_complete tracepoint event indicates that some portion
	82	+ * of operation request has been completed by the device driver. If
	83	+ * the @rq->bio is %NULL, then there is absolutely no additional work to
	84	+ * do for the request. If @rq->bio is non-NULL then there is
	85	+ * additional work required to complete the request.
	86	+ */
57	87	DEFINE_EVENT(block_rq_with_error, block_rq_complete,
58	88
59	89	TP_PROTO(struct request_queue q, struct request rq),
...	...	@@ -95,6 +125,16 @@
95	125	__entry->nr_sector, __entry->comm)
96	126	);
97	127
	128	+/**
	129	+ * block_rq_insert - insert block operation request into queue
	130	+ * @q: target queue
	131	+ * @rq: block IO operation request
	132	+ *
	133	+ * Called immediately before block operation request @rq is inserted
	134	+ * into queue @q. The fields in the operation request @rq struct can
	135	+ * be examined to determine which device and sectors the pending
	136	+ * operation would access.
	137	+ */
98	138	DEFINE_EVENT(block_rq, block_rq_insert,
99	139
100	140	TP_PROTO(struct request_queue q, struct request rq),
...	...	@@ -102,6 +142,14 @@
102	142	TP_ARGS(q, rq)
103	143	);
104	144
	145	+/**
	146	+ * block_rq_issue - issue pending block IO request operation to device driver
	147	+ * @q: queue holding operation
	148	+ * @rq: block IO operation operation request
	149	+ *
	150	+ * Called when block operation request @rq from queue @q is sent to a
	151	+ * device driver for processing.
	152	+ */
105	153	DEFINE_EVENT(block_rq, block_rq_issue,
106	154
107	155	TP_PROTO(struct request_queue q, struct request rq),
...	...	@@ -109,6 +157,17 @@
109	157	TP_ARGS(q, rq)
110	158	);
111	159
	160	+/**
	161	+ * block_bio_bounce - used bounce buffer when processing block operation
	162	+ * @q: queue holding the block operation
	163	+ * @bio: block operation
	164	+ *
	165	+ * A bounce buffer was used to handle the block operation @bio in @q.
	166	+ * This occurs when hardware limitations prevent a direct transfer of
	167	+ * data between the @bio data memory area and the IO device. Use of a
	168	+ * bounce buffer requires extra copying of data and decreases
	169	+ * performance.
	170	+ */
112	171	TRACE_EVENT(block_bio_bounce,
113	172
114	173	TP_PROTO(struct request_queue q, struct bio bio),
...	...	@@ -138,6 +197,14 @@
138	197	__entry->nr_sector, __entry->comm)
139	198	);
140	199
	200	+/**
	201	+ * block_bio_complete - completed all work on the block operation
	202	+ * @q: queue holding the block operation
	203	+ * @bio: block operation completed
	204	+ *
	205	+ * This tracepoint indicates there is no further work to do on this
	206	+ * block IO operation @bio.
	207	+ */
141	208	TRACE_EVENT(block_bio_complete,
142	209
143	210	TP_PROTO(struct request_queue q, struct bio bio),
...	...	@@ -193,6 +260,14 @@
193	260	__entry->nr_sector, __entry->comm)
194	261	);
195	262
	263	+/**
	264	+ * block_bio_backmerge - merging block operation to the end of an existing operation
	265	+ * @q: queue holding operation
	266	+ * @bio: new block operation to merge
	267	+ *
	268	+ * Merging block request @bio to the end of an existing block request
	269	+ * in queue @q.
	270	+ */
196	271	DEFINE_EVENT(block_bio, block_bio_backmerge,
197	272
198	273	TP_PROTO(struct request_queue q, struct bio bio),
...	...	@@ -200,6 +275,14 @@
200	275	TP_ARGS(q, bio)
201	276	);
202	277
	278	+/**
	279	+ * block_bio_frontmerge - merging block operation to the beginning of an existing operation
	280	+ * @q: queue holding operation
	281	+ * @bio: new block operation to merge
	282	+ *
	283	+ * Merging block IO operation @bio to the beginning of an existing block
	284	+ * operation in queue @q.
	285	+ */
203	286	DEFINE_EVENT(block_bio, block_bio_frontmerge,
204	287
205	288	TP_PROTO(struct request_queue q, struct bio bio),
...	...	@@ -207,6 +290,13 @@
207	290	TP_ARGS(q, bio)
208	291	);
209	292
	293	+/**
	294	+ * block_bio_queue - putting new block IO operation in queue
	295	+ * @q: queue holding operation
	296	+ * @bio: new block operation
	297	+ *
	298	+ * About to place the block IO operation @bio into queue @q.
	299	+ */
210	300	DEFINE_EVENT(block_bio, block_bio_queue,
211	301
212	302	TP_PROTO(struct request_queue q, struct bio bio),
...	...	@@ -243,6 +333,15 @@
243	333	__entry->nr_sector, __entry->comm)
244	334	);
245	335
	336	+/**
	337	+ * block_getrq - get a free request entry in queue for block IO operations
	338	+ * @q: queue for operations
	339	+ * @bio: pending block IO operation
	340	+ * @rw: low bit indicates a read (%0) or a write (%1)
	341	+ *
	342	+ * A request struct for queue @q has been allocated to handle the
	343	+ * block IO operation @bio.
	344	+ */
246	345	DEFINE_EVENT(block_get_rq, block_getrq,
247	346
248	347	TP_PROTO(struct request_queue q, struct bio bio, int rw),
...	...	@@ -250,6 +349,17 @@
250	349	TP_ARGS(q, bio, rw)
251	350	);
252	351
	352	+/**
	353	+ * block_sleeprq - waiting to get a free request entry in queue for block IO operation
	354	+ * @q: queue for operation
	355	+ * @bio: pending block IO operation
	356	+ * @rw: low bit indicates a read (%0) or a write (%1)
	357	+ *
	358	+ * In the case where a request struct cannot be provided for queue @q
	359	+ * the process needs to wait for an request struct to become
	360	+ * available. This tracepoint event is generated each time the
	361	+ * process goes to sleep waiting for request struct become available.
	362	+ */
253	363	DEFINE_EVENT(block_get_rq, block_sleeprq,
254	364
255	365	TP_PROTO(struct request_queue q, struct bio bio, int rw),
...	...	@@ -257,6 +367,14 @@
257	367	TP_ARGS(q, bio, rw)
258	368	);
259	369
	370	+/**
	371	+ * block_plug - keep operations requests in request queue
	372	+ * @q: request queue to plug
	373	+ *
	374	+ * Plug the request queue @q. Do not allow block operation requests
	375	+ * to be sent to the device driver. Instead, accumulate requests in
	376	+ * the queue to improve throughput performance of the block device.
	377	+ */
260	378	TRACE_EVENT(block_plug,
261	379
262	380	TP_PROTO(struct request_queue *q),
...	...	@@ -293,6 +411,13 @@
293	411	TP_printk("[%s] %d", __entry->comm, __entry->nr_rq)
294	412	);
295	413
	414	+/**
	415	+ * block_unplug_timer - timed release of operations requests in queue to device driver
	416	+ * @q: request queue to unplug
	417	+ *
	418	+ * Unplug the request queue @q because a timer expired and allow block
	419	+ * operation requests to be sent to the device driver.
	420	+ */
296	421	DEFINE_EVENT(block_unplug, block_unplug_timer,
297	422
298	423	TP_PROTO(struct request_queue *q),
...	...	@@ -300,6 +425,13 @@
300	425	TP_ARGS(q)
301	426	);
302	427
	428	+/**
	429	+ * block_unplug_io - release of operations requests in request queue
	430	+ * @q: request queue to unplug
	431	+ *
	432	+ * Unplug request queue @q because device driver is scheduled to work
	433	+ * on elements in the request queue.
	434	+ */
303	435	DEFINE_EVENT(block_unplug, block_unplug_io,
304	436
305	437	TP_PROTO(struct request_queue *q),
...	...	@@ -307,6 +439,17 @@
307	439	TP_ARGS(q)
308	440	);
309	441
	442	+/**
	443	+ * block_split - split a single bio struct into two bio structs
	444	+ * @q: queue containing the bio
	445	+ * @bio: block operation being split
	446	+ * @new_sector: The starting sector for the new bio
	447	+ *
	448	+ * The bio request @bio in request queue @q needs to be split into two
	449	+ * bio requests. The newly created @bio request starts at
	450	+ * @new_sector. This split may be required due to hardware limitation
	451	+ * such as operation crossing device boundaries in a RAID system.
	452	+ */
310	453	TRACE_EVENT(block_split,
311	454
312	455	TP_PROTO(struct request_queue q, struct bio bio,
...	...	@@ -337,6 +480,16 @@
337	480	__entry->comm)
338	481	);
339	482
	483	+/**
	484	+ * block_remap - map request for a partition to the raw device
	485	+ * @q: queue holding the operation
	486	+ * @bio: revised operation
	487	+ * @dev: device for the operation
	488	+ * @from: original sector for the operation
	489	+ *
	490	+ * An operation for a partition on a block device has been mapped to the
	491	+ * raw block device.
	492	+ */
340	493	TRACE_EVENT(block_remap,
341	494
342	495	TP_PROTO(struct request_queue q, struct bio bio, dev_t dev,
...	...	@@ -370,6 +523,17 @@
370	523	(unsigned long long)__entry->old_sector)
371	524	);
372	525
	526	+/**
	527	+ * block_rq_remap - map request for a block operation request
	528	+ * @q: queue holding the operation
	529	+ * @rq: block IO operation request
	530	+ * @dev: device for the operation
	531	+ * @from: original sector for the operation
	532	+ *
	533	+ * The block operation request @rq in @q has been remapped. The block
	534	+ * operation request @rq holds the current information and @from hold
	535	+ * the original sector.
	536	+ */
373	537	TRACE_EVENT(block_rq_remap,
374	538
375	539	TP_PROTO(struct request_queue q, struct request rq, dev_t dev,