| blob | 17e03d22c7f0557b4925b03e8e52fea511299d69 |
1 jbd2: fix sphinx kernel-doc build warnings
3 From: "Tobin C. Harding" <me@tobin.cc>
5 Sphinx emits various (26) warnings when building make target 'htmldocs'.
6 Currently struct definitions contain duplicate documentation, some as
7 kernel-docs and some as standard c89 comments. We can reduce
8 duplication while cleaning up the kernel docs.
10 Move all kernel-docs to right above each struct member. Use the set of
11 all existing comments (kernel-doc and c89). Add documentation for
12 missing struct members and function arguments.
14 Signed-off-by: Tobin C. Harding <me@tobin.cc>
15 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
16 ---
17 fs/jbd2/transaction.c | 5 +-
18 include/linux/jbd2.h | 431 ++++++++++++++++++++++++++++++++++++++++-------------------------
19 2 files changed, 272 insertions(+), 164 deletions(-)
21 diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
22 index 881a9e09ca4e..ac311037d7a5 100644
23 --- a/fs/jbd2/transaction.c
24 +++ b/fs/jbd2/transaction.c
25 @@ -492,8 +492,10 @@ void jbd2_journal_free_reserved(handle_t *handle)
26 EXPORT_SYMBOL(jbd2_journal_free_reserved);
28 /**
29 - * int jbd2_journal_start_reserved(handle_t *handle) - start reserved handle
30 + * int jbd2_journal_start_reserved() - start reserved handle
31 * @handle: handle to start
32 + * @type: for handle statistics
33 + * @line_no: for handle statistics
34 *
35 * Start handle that has been previously reserved with jbd2_journal_reserve().
36 * This attaches @handle to the running transaction (or creates one if there's
37 @@ -623,6 +625,7 @@ int jbd2_journal_extend(handle_t *handle, int nblocks)
38 * int jbd2_journal_restart() - restart a handle .
39 * @handle: handle to restart
40 * @nblocks: nr credits requested
41 + * @gfp_mask: memory allocation flags (for start_this_handle)
42 *
43 * Restart a handle for a multi-transaction filesystem
44 * operation.
45 diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
46 index 296d1e0ea87b..b708e5169d1d 100644
47 --- a/include/linux/jbd2.h
48 +++ b/include/linux/jbd2.h
49 @@ -418,26 +418,41 @@ static inline void jbd_unlock_bh_journal_head(struct buffer_head *bh)
50 #define JI_WAIT_DATA (1 << __JI_WAIT_DATA)
52 /**
53 - * struct jbd_inode is the structure linking inodes in ordered mode
54 - * present in a transaction so that we can sync them during commit.
55 + * struct jbd_inode - The jbd_inode type is the structure linking inodes in
56 + * ordered mode present in a transaction so that we can sync them during commit.
57 */
58 struct jbd2_inode {
59 - /* Which transaction does this inode belong to? Either the running
60 - * transaction or the committing one. [j_list_lock] */
61 + /**
62 + * @i_transaction:
63 + *
64 + * Which transaction does this inode belong to? Either the running
65 + * transaction or the committing one. [j_list_lock]
66 + */
67 transaction_t *i_transaction;
69 - /* Pointer to the running transaction modifying inode's data in case
70 - * there is already a committing transaction touching it. [j_list_lock] */
71 + /**
72 + * @i_next_transaction:
73 + *
74 + * Pointer to the running transaction modifying inode's data in case
75 + * there is already a committing transaction touching it. [j_list_lock]
76 + */
77 transaction_t *i_next_transaction;
79 - /* List of inodes in the i_transaction [j_list_lock] */
80 + /**
81 + * @i_list: List of inodes in the i_transaction [j_list_lock]
82 + */
83 struct list_head i_list;
85 - /* VFS inode this inode belongs to [constant during the lifetime
86 - * of the structure] */
87 + /**
88 + * @i_vfs_inode:
89 + *
90 + * VFS inode this inode belongs to [constant for lifetime of structure]
91 + */
92 struct inode *i_vfs_inode;
94 - /* Flags of inode [j_list_lock] */
95 + /**
96 + * @i_flags: Flags of inode [j_list_lock]
97 + */
98 unsigned long i_flags;
99 };
101 @@ -447,12 +462,20 @@ struct jbd2_revoke_table_s;
102 * struct handle_s - The handle_s type is the concrete type associated with
103 * handle_t.
104 * @h_transaction: Which compound transaction is this update a part of?
105 + * @h_journal: Which journal handle belongs to - used iff h_reserved set.
106 + * @h_rsv_handle: Handle reserved for finishing the logical operation.
107 * @h_buffer_credits: Number of remaining buffers we are allowed to dirty.
108 - * @h_ref: Reference count on this handle
109 - * @h_err: Field for caller's use to track errors through large fs operations
110 - * @h_sync: flag for sync-on-close
111 - * @h_jdata: flag to force data journaling
112 - * @h_aborted: flag indicating fatal error on handle
113 + * @h_ref: Reference count on this handle.
114 + * @h_err: Field for caller's use to track errors through large fs operations.
115 + * @h_sync: Flag for sync-on-close.
116 + * @h_jdata: Flag to force data journaling.
117 + * @h_reserved: Flag for handle for reserved credits.
118 + * @h_aborted: Flag indicating fatal error on handle.
119 + * @h_type: For handle statistics.
120 + * @h_line_no: For handle statistics.
121 + * @h_start_jiffies: Handle Start time.
122 + * @h_requested_credits: Holds @h_buffer_credits after handle is started.
123 + * @saved_alloc_context: Saved context while transaction is open.
124 **/
126 /* Docbook can't yet cope with the bit fields, but will leave the documentation
127 @@ -462,32 +485,23 @@ struct jbd2_revoke_table_s;
128 struct jbd2_journal_handle
129 {
130 union {
131 - /* Which compound transaction is this update a part of? */
132 transaction_t *h_transaction;
133 /* Which journal handle belongs to - used iff h_reserved set */
134 journal_t *h_journal;
135 };
137 - /* Handle reserved for finishing the logical operation */
138 handle_t *h_rsv_handle;
139 -
140 - /* Number of remaining buffers we are allowed to dirty: */
141 int h_buffer_credits;
142 -
143 - /* Reference count on this handle */
144 int h_ref;
145 -
146 - /* Field for caller's use to track errors through large fs */
147 - /* operations */
148 int h_err;
150 /* Flags [no locking] */
151 - unsigned int h_sync: 1; /* sync-on-close */
152 - unsigned int h_jdata: 1; /* force data journaling */
153 - unsigned int h_reserved: 1; /* handle with reserved credits */
154 - unsigned int h_aborted: 1; /* fatal error on handle */
155 - unsigned int h_type: 8; /* for handle statistics */
156 - unsigned int h_line_no: 16; /* for handle statistics */
157 + unsigned int h_sync: 1;
158 + unsigned int h_jdata: 1;
159 + unsigned int h_reserved: 1;
160 + unsigned int h_aborted: 1;
161 + unsigned int h_type: 8;
162 + unsigned int h_line_no: 16;
164 unsigned long h_start_jiffies;
165 unsigned int h_requested_credits;
166 @@ -729,228 +743,253 @@ jbd2_time_diff(unsigned long start, unsigned long end)
167 /**
168 * struct journal_s - The journal_s type is the concrete type associated with
169 * journal_t.
170 - * @j_flags: General journaling state flags
171 - * @j_errno: Is there an outstanding uncleared error on the journal (from a
172 - * prior abort)?
173 - * @j_sb_buffer: First part of superblock buffer
174 - * @j_superblock: Second part of superblock buffer
175 - * @j_format_version: Version of the superblock format
176 - * @j_state_lock: Protect the various scalars in the journal
177 - * @j_barrier_count: Number of processes waiting to create a barrier lock
178 - * @j_barrier: The barrier lock itself
179 - * @j_running_transaction: The current running transaction..
180 - * @j_committing_transaction: the transaction we are pushing to disk
181 - * @j_checkpoint_transactions: a linked circular list of all transactions
182 - * waiting for checkpointing
183 - * @j_wait_transaction_locked: Wait queue for waiting for a locked transaction
184 - * to start committing, or for a barrier lock to be released
185 - * @j_wait_done_commit: Wait queue for waiting for commit to complete
186 - * @j_wait_commit: Wait queue to trigger commit
187 - * @j_wait_updates: Wait queue to wait for updates to complete
188 - * @j_wait_reserved: Wait queue to wait for reserved buffer credits to drop
189 - * @j_checkpoint_mutex: Mutex for locking against concurrent checkpoints
190 - * @j_head: Journal head - identifies the first unused block in the journal
191 - * @j_tail: Journal tail - identifies the oldest still-used block in the
192 - * journal.
193 - * @j_free: Journal free - how many free blocks are there in the journal?
194 - * @j_first: The block number of the first usable block
195 - * @j_last: The block number one beyond the last usable block
196 - * @j_dev: Device where we store the journal
197 - * @j_blocksize: blocksize for the location where we store the journal.
198 - * @j_blk_offset: starting block offset for into the device where we store the
199 - * journal
200 - * @j_fs_dev: Device which holds the client fs. For internal journal this will
201 - * be equal to j_dev
202 - * @j_reserved_credits: Number of buffers reserved from the running transaction
203 - * @j_maxlen: Total maximum capacity of the journal region on disk.
204 - * @j_list_lock: Protects the buffer lists and internal buffer state.
205 - * @j_inode: Optional inode where we store the journal. If present, all journal
206 - * block numbers are mapped into this inode via bmap().
207 - * @j_tail_sequence: Sequence number of the oldest transaction in the log
208 - * @j_transaction_sequence: Sequence number of the next transaction to grant
209 - * @j_commit_sequence: Sequence number of the most recently committed
210 - * transaction
211 - * @j_commit_request: Sequence number of the most recent transaction wanting
212 - * commit
213 - * @j_uuid: Uuid of client object.
214 - * @j_task: Pointer to the current commit thread for this journal
215 - * @j_max_transaction_buffers: Maximum number of metadata buffers to allow in a
216 - * single compound commit transaction
217 - * @j_commit_interval: What is the maximum transaction lifetime before we begin
218 - * a commit?
219 - * @j_commit_timer: The timer used to wakeup the commit thread
220 - * @j_revoke_lock: Protect the revoke table
221 - * @j_revoke: The revoke table - maintains the list of revoked blocks in the
222 - * current transaction.
223 - * @j_revoke_table: alternate revoke tables for j_revoke
224 - * @j_wbuf: array of buffer_heads for jbd2_journal_commit_transaction
225 - * @j_wbufsize: maximum number of buffer_heads allowed in j_wbuf, the
226 - * number that will fit in j_blocksize
227 - * @j_last_sync_writer: most recent pid which did a synchronous write
228 - * @j_history_lock: Protect the transactions statistics history
229 - * @j_proc_entry: procfs entry for the jbd statistics directory
230 - * @j_stats: Overall statistics
231 - * @j_private: An opaque pointer to fs-private information.
232 - * @j_trans_commit_map: Lockdep entity to track transaction commit dependencies
233 */
234 -
235 struct journal_s
236 {
237 - /* General journaling state flags [j_state_lock] */
238 + /**
239 + * @j_flags: General journaling state flags [j_state_lock]
240 + */
241 unsigned long j_flags;
243 - /*
244 + /**
245 + * @j_errno:
246 + *
247 * Is there an outstanding uncleared error on the journal (from a prior
248 * abort)? [j_state_lock]
249 */
250 int j_errno;
252 - /* The superblock buffer */
253 + /**
254 + * @j_sb_buffer: The first part of the superblock buffer.
255 + */
256 struct buffer_head *j_sb_buffer;
257 +
258 + /**
259 + * @j_superblock: The second part of the superblock buffer.
260 + */
261 journal_superblock_t *j_superblock;
263 - /* Version of the superblock format */
264 + /**
265 + * @j_format_version: Version of the superblock format.
266 + */
267 int j_format_version;
269 - /*
270 - * Protect the various scalars in the journal
271 + /**
272 + * @j_state_lock: Protect the various scalars in the journal.
273 */
274 rwlock_t j_state_lock;
276 - /*
277 + /**
278 + * @j_barrier_count:
279 + *
280 * Number of processes waiting to create a barrier lock [j_state_lock]
281 */
282 int j_barrier_count;
284 - /* The barrier lock itself */
285 + /**
286 + * @j_barrier: The barrier lock itself.
287 + */
288 struct mutex j_barrier;
290 - /*
291 + /**
292 + * @j_running_transaction:
293 + *
294 * Transactions: The current running transaction...
295 * [j_state_lock] [caller holding open handle]
296 */
297 transaction_t *j_running_transaction;
299 - /*
300 + /**
301 + * @j_committing_transaction:
302 + *
303 * the transaction we are pushing to disk
304 * [j_state_lock] [caller holding open handle]
305 */
306 transaction_t *j_committing_transaction;
308 - /*
309 + /**
310 + * @j_checkpoint_transactions:
311 + *
312 * ... and a linked circular list of all transactions waiting for
313 * checkpointing. [j_list_lock]
314 */
315 transaction_t *j_checkpoint_transactions;
317 - /*
318 + /**
319 + * @j_wait_transaction_locked:
320 + *
321 * Wait queue for waiting for a locked transaction to start committing,
322 - * or for a barrier lock to be released
323 + * or for a barrier lock to be released.
324 */
325 wait_queue_head_t j_wait_transaction_locked;
327 - /* Wait queue for waiting for commit to complete */
328 + /**
329 + * @j_wait_done_commit: Wait queue for waiting for commit to complete.
330 + */
331 wait_queue_head_t j_wait_done_commit;
333 - /* Wait queue to trigger commit */
334 + /**
335 + * @j_wait_commit: Wait queue to trigger commit.
336 + */
337 wait_queue_head_t j_wait_commit;
339 - /* Wait queue to wait for updates to complete */
340 + /**
341 + * @j_wait_updates: Wait queue to wait for updates to complete.
342 + */
343 wait_queue_head_t j_wait_updates;
345 - /* Wait queue to wait for reserved buffer credits to drop */
346 + /**
347 + * @j_wait_reserved:
348 + *
349 + * Wait queue to wait for reserved buffer credits to drop.
350 + */
351 wait_queue_head_t j_wait_reserved;
353 - /* Semaphore for locking against concurrent checkpoints */
354 + /**
355 + * @j_checkpoint_mutex:
356 + *
357 + * Semaphore for locking against concurrent checkpoints.
358 + */
359 struct mutex j_checkpoint_mutex;
361 - /*
362 + /**
363 + * @j_chkpt_bhs:
364 + *
365 * List of buffer heads used by the checkpoint routine. This
366 * was moved from jbd2_log_do_checkpoint() to reduce stack
367 * usage. Access to this array is controlled by the
368 - * j_checkpoint_mutex. [j_checkpoint_mutex]
369 + * @j_checkpoint_mutex. [j_checkpoint_mutex]
370 */
371 struct buffer_head *j_chkpt_bhs[JBD2_NR_BATCH];
372 -
373 - /*
374 +
375 + /**
376 + * @j_head:
377 + *
378 * Journal head: identifies the first unused block in the journal.
379 * [j_state_lock]
380 */
381 unsigned long j_head;
383 - /*
384 + /**
385 + * @j_tail:
386 + *
387 * Journal tail: identifies the oldest still-used block in the journal.
388 * [j_state_lock]
389 */
390 unsigned long j_tail;
392 - /*
393 + /**
394 + * @j_free:
395 + *
396 * Journal free: how many free blocks are there in the journal?
397 * [j_state_lock]
398 */
399 unsigned long j_free;
401 - /*
402 - * Journal start and end: the block numbers of the first usable block
403 - * and one beyond the last usable block in the journal. [j_state_lock]
404 + /**
405 + * @j_first:
406 + *
407 + * The block number of the first usable block in the journal
408 + * [j_state_lock].
409 */
410 unsigned long j_first;
411 +
412 + /**
413 + * @j_last:
414 + *
415 + * The block number one beyond the last usable block in the journal
416 + * [j_state_lock].
417 + */
418 unsigned long j_last;
420 - /*
421 - * Device, blocksize and starting block offset for the location where we
422 - * store the journal.
423 + /**
424 + * @j_dev: Device where we store the journal.
425 */
426 struct block_device *j_dev;
427 +
428 + /**
429 + * @j_blocksize: Block size for the location where we store the journal.
430 + */
431 int j_blocksize;
432 +
433 + /**
434 + * @j_blk_offset:
435 + *
436 + * Starting block offset into the device where we store the journal.
437 + */
438 unsigned long long j_blk_offset;
439 +
440 + /**
441 + * @j_devname: Journal device name.
442 + */
443 char j_devname[BDEVNAME_SIZE+24];
445 - /*
446 + /**
447 + * @j_fs_dev:
448 + *
449 * Device which holds the client fs. For internal journal this will be
450 * equal to j_dev.
451 */
452 struct block_device *j_fs_dev;
454 - /* Total maximum capacity of the journal region on disk. */
455 + /**
456 + * @j_maxlen: Total maximum capacity of the journal region on disk.
457 + */
458 unsigned int j_maxlen;
460 - /* Number of buffers reserved from the running transaction */
461 + /**
462 + * @j_reserved_credits:
463 + *
464 + * Number of buffers reserved from the running transaction.
465 + */
466 atomic_t j_reserved_credits;
468 - /*
469 - * Protects the buffer lists and internal buffer state.
470 + /**
471 + * @j_list_lock: Protects the buffer lists and internal buffer state.
472 */
473 spinlock_t j_list_lock;
475 - /* Optional inode where we store the journal. If present, all */
476 - /* journal block numbers are mapped into this inode via */
477 - /* bmap(). */
478 + /**
479 + * @j_inode:
480 + *
481 + * Optional inode where we store the journal. If present, all
482 + * journal block numbers are mapped into this inode via bmap().
483 + */
484 struct inode *j_inode;
486 - /*
487 + /**
488 + * @j_tail_sequence:
489 + *
490 * Sequence number of the oldest transaction in the log [j_state_lock]
491 */
492 tid_t j_tail_sequence;
494 - /*
495 + /**
496 + * @j_transaction_sequence:
497 + *
498 * Sequence number of the next transaction to grant [j_state_lock]
499 */
500 tid_t j_transaction_sequence;
502 - /*
503 + /**
504 + * @j_commit_sequence:
505 + *
506 * Sequence number of the most recently committed transaction
507 * [j_state_lock].
508 */
509 tid_t j_commit_sequence;
511 - /*
512 + /**
513 + * @j_commit_request:
514 + *
515 * Sequence number of the most recent transaction wanting commit
516 * [j_state_lock]
517 */
518 tid_t j_commit_request;
520 - /*
521 + /**
522 + * @j_uuid:
523 + *
524 * Journal uuid: identifies the object (filesystem, LVM volume etc)
525 * backed by this journal. This will eventually be replaced by an array
526 * of uuids, allowing us to index multiple devices within a single
527 @@ -958,85 +997,151 @@ struct journal_s
528 */
529 __u8 j_uuid[16];
531 - /* Pointer to the current commit thread for this journal */
532 + /**
533 + * @j_task: Pointer to the current commit thread for this journal.
534 + */
535 struct task_struct *j_task;
537 - /*
538 + /**
539 + * @j_max_transaction_buffers:
540 + *
541 * Maximum number of metadata buffers to allow in a single compound
542 - * commit transaction
543 + * commit transaction.
544 */
545 int j_max_transaction_buffers;
547 - /*
548 + /**
549 + * @j_commit_interval:
550 + *
551 * What is the maximum transaction lifetime before we begin a commit?
552 */
553 unsigned long j_commit_interval;
555 - /* The timer used to wakeup the commit thread: */
556 + /**
557 + * @j_commit_timer: The timer used to wakeup the commit thread.
558 + */
559 struct timer_list j_commit_timer;
561 - /*
562 - * The revoke table: maintains the list of revoked blocks in the
563 - * current transaction. [j_revoke_lock]
564 + /**
565 + * @j_revoke_lock: Protect the revoke table.
566 */
567 spinlock_t j_revoke_lock;
568 +
569 + /**
570 + * @j_revoke:
571 + *
572 + * The revoke table - maintains the list of revoked blocks in the
573 + * current transaction.
574 + */
575 struct jbd2_revoke_table_s *j_revoke;
576 +
577 + /**
578 + * @j_revoke_table: Alternate revoke tables for j_revoke.
579 + */
580 struct jbd2_revoke_table_s *j_revoke_table[2];
582 - /*
583 - * array of bhs for jbd2_journal_commit_transaction
584 + /**
585 + * @j_wbuf: Array of bhs for jbd2_journal_commit_transaction.
586 */
587 struct buffer_head **j_wbuf;
588 +
589 + /**
590 + * @j_wbufsize:
591 + *
592 + * Size of @j_wbuf array.
593 + */
594 int j_wbufsize;
596 - /*
597 - * this is the pid of hte last person to run a synchronous operation
598 - * through the journal
599 + /**
600 + * @j_last_sync_writer:
601 + *
602 + * The pid of the last person to run a synchronous operation
603 + * through the journal.
604 */
605 pid_t j_last_sync_writer;
607 - /*
608 - * the average amount of time in nanoseconds it takes to commit a
609 + /**
610 + * @j_average_commit_time:
611 + *
612 + * The average amount of time in nanoseconds it takes to commit a
613 * transaction to disk. [j_state_lock]
614 */
615 u64 j_average_commit_time;
617 - /*
618 - * minimum and maximum times that we should wait for
619 - * additional filesystem operations to get batched into a
620 - * synchronous handle in microseconds
621 + /**
622 + * @j_min_batch_time:
623 + *
624 + * Minimum time that we should wait for additional filesystem operations
625 + * to get batched into a synchronous handle in microseconds.
626 */
627 u32 j_min_batch_time;
628 +
629 + /**
630 + * @j_max_batch_time:
631 + *
632 + * Maximum time that we should wait for additional filesystem operations
633 + * to get batched into a synchronous handle in microseconds.
634 + */
635 u32 j_max_batch_time;
637 - /* This function is called when a transaction is closed */
638 + /**
639 + * @j_commit_callback:
640 + *
641 + * This function is called when a transaction is closed.
642 + */
643 void (*j_commit_callback)(journal_t *,
644 transaction_t *);
646 /*
647 * Journal statistics
648 */
649 +
650 + /**
651 + * @j_history_lock: Protect the transactions statistics history.
652 + */
653 spinlock_t j_history_lock;
654 +
655 + /**
656 + * @j_proc_entry: procfs entry for the jbd statistics directory.
657 + */
658 struct proc_dir_entry *j_proc_entry;
659 +
660 + /**
661 + * @j_stats: Overall statistics.
662 + */
663 struct transaction_stats_s j_stats;
665 - /* Failed journal commit ID */
666 + /**
667 + * @j_failed_commit: Failed journal commit ID.
668 + */
669 unsigned int j_failed_commit;
671 - /*
672 + /**
673 + * @j_private:
674 + *
675 * An opaque pointer to fs-private information. ext3 puts its
676 - * superblock pointer here
677 + * superblock pointer here.
678 */
679 void *j_private;
681 - /* Reference to checksum algorithm driver via cryptoapi */
682 + /**
683 + * @j_chksum_driver:
684 + *
685 + * Reference to checksum algorithm driver via cryptoapi.
686 + */
687 struct crypto_shash *j_chksum_driver;
689 - /* Precomputed journal UUID checksum for seeding other checksums */
690 + /**
691 + * @j_csum_seed:
692 + *
693 + * Precomputed journal UUID checksum for seeding other checksums.
694 + */
695 __u32 j_csum_seed;
697 #ifdef CONFIG_DEBUG_LOCK_ALLOC
698 - /*
699 + /**
700 + * @j_trans_commit_map:
701 + *
702 * Lockdep entity to track transaction commit dependencies. Handles
703 * hold this "lock" for read, when we wait for commit, we acquire the
704 * "lock" for writing. This matches the properties of jbd2 journalling