add patch save-error-to-disk-in-ext4_grp_locked_error
[ext4-patch-queue.git] / jbd2-fix-sphinx-kernel-doc-build-warnings
blob17e03d22c7f0557b4925b03e8e52fea511299d69
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
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;
140 -       /* Number of remaining buffers we are allowed to dirty: */
141         int                     h_buffer_credits;
143 -       /* Reference count on this handle */
144         int                     h_ref;
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   */
235  struct journal_s
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;
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 -       /*
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;
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;
428 +       /**
429 +        * @j_blocksize: Block size for the location where we store the journal.
430 +        */
431         int                     j_blocksize;
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;
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;
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;
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;
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;
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          */
650 +       /**
651 +        * @j_history_lock: Protect the transactions statistics history.
652 +        */
653         spinlock_t              j_history_lock;
655 +       /**
656 +        * @j_proc_entry: procfs entry for the jbd statistics directory.
657 +        */
658         struct proc_dir_entry   *j_proc_entry;
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