bcachefs: docs: add docs for bch2_trans_reset

Add basic kernel docs for bch2_trans_reset and bch2_trans_begin.

Signed-off-by: Dan Robertson <dan@dlrobertson.com>
Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>

diff --git a/fs/bcachefs/btree_iter.c b/fs/bcachefs/btree_iter.c
index 1592929178bfa84659c37514a706eb9c95f0d773..13e4dea8a09b9a32564d922db3b391a0c6b30f98 100644 (file)
--- a/fs/bcachefs/btree_iter.c
+++ b/fs/bcachefs/btree_iter.c
@@ -2310,6 +2310,22 @@ inline void bch2_trans_unlink_iters(struct btree_trans *trans)
        }
 }
 
+/**
+ * bch2_trans_reset() - reset a transaction after a interrupted attempt
+ * @trans: transaction to reset
+ * @flags: transaction reset flags.
+ *
+ * While iterating over nodes or updating nodes a attempt to lock a btree
+ * node may return EINTR when the trylock fails. When this occurs
+ * bch2_trans_reset() or bch2_trans_begin() should be called and the
+ * transaction retried.
+ *
+ * Transaction reset flags include:
+ *
+ *  - TRANS_RESET_NOUNLOCK   - Do not attempt to unlock and reschedule the
+ *                            transaction.
+ *  - TRANS_RESET_NOTRAVERSE - Do not traverse all linked iters.
+ */
 void bch2_trans_reset(struct btree_trans *trans, unsigned flags)
 {
        struct btree_iter *iter;

diff --git a/fs/bcachefs/btree_iter.h b/fs/bcachefs/btree_iter.h
index 6efea281d87f6aa6ed7f83ed1e1ba455d82b3027..31175cf00c0a163e39739598e9acd7939e513857 100644 (file)
--- a/fs/bcachefs/btree_iter.h
+++ b/fs/bcachefs/btree_iter.h
@@ -319,6 +319,13 @@ static inline void set_btree_iter_dontneed(struct btree_trans *trans, struct btr
 
 void bch2_trans_reset(struct btree_trans *, unsigned);
 
+/**
+ * bch2_trans_begin() - ensure lock consistency of transaction on retry
+ * @trans: transaction to prepare
+ *
+ * Ensure lock ordering is correct before potentially retrying a transaction
+ * after a failed trylock.
+ */
 static inline void bch2_trans_begin(struct btree_trans *trans)
 {
        return bch2_trans_reset(trans, 0);