[RFC PATCH 00/20] add comments in include/linux/ceph/*.h

[RFC PATCH 00/20] add comments in include/linux/ceph/*.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

Viacheslav Dubeyko (20):
  ceph: add comments to metadata structures in auth.h
  ceph: add comments to metadata structures in buffer.h
  ceph: add comments in ceph_debug.h
  ceph: add comments to declarations in ceph_features.h
  ceph: rework comments in ceph_frag.h
  ceph: add comments to metadata structures in ceph_fs.h
  ceph: add comments in ceph_hash.h
  ceph: add comments to metadata structures in cls_lock_client.h
  ceph: add comments to metadata structures in libceph.h
  ceph: add comments to metadata structures in messenger.h
  ceph: add comments to metadata structures in mon_client.h
  ceph: add comments to metadata structures in msgpool.h
  ceph: add comments to metadata structures in msgr.h
  ceph: add comments to metadata structures in osd_client.h
  ceph: add comments to metadata structures in osdmap.h
  ceph: add comments to metadata structures in pagelist.h
  ceph: add comments to metadata structures in rados.h
  ceph: add comments to metadata structures in string_table.h
  ceph: add comments to metadata structures in striper.h
  ceph: add comments to metadata structures in types.h

 include/linux/ceph/auth.h            |  59 +-
 include/linux/ceph/buffer.h          |   9 +-
 include/linux/ceph/ceph_debug.h      |  25 +-
 include/linux/ceph/ceph_features.h   |  47 +-
 include/linux/ceph/ceph_frag.h       |  24 +-
 include/linux/ceph/ceph_fs.h         | 792 ++++++++++++++++++---------
 include/linux/ceph/ceph_hash.h       |  21 +-
 include/linux/ceph/cls_lock_client.h |  34 +-
 include/linux/ceph/libceph.h         |  50 +-
 include/linux/ceph/messenger.h       | 449 +++++++++++----
 include/linux/ceph/mon_client.h      |  93 +++-
 include/linux/ceph/msgpool.h         |  15 +-
 include/linux/ceph/msgr.h            | 162 +++++-
 include/linux/ceph/osd_client.h      | 407 ++++++++++++--
 include/linux/ceph/osdmap.h          | 124 ++++-
 include/linux/ceph/pagelist.h        |  13 +
 include/linux/ceph/rados.h           |  91 ++-
 include/linux/ceph/string_table.h    |  11 +
 include/linux/ceph/striper.h         |  16 +
 include/linux/ceph/types.h           |  14 +-
 20 files changed, 1907 insertions(+), 549 deletions(-)

-- 
2.51.0

[RFC PATCH 01/20] ceph: add comments to metadata structures in auth.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_authorizer,
struct ceph_auth_handshake, struct ceph_auth_client_ops,
struct ceph_auth_client in /include/linux/ceph/auth.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/auth.h | 59 ++++++++++++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/include/linux/ceph/auth.h b/include/linux/ceph/auth.h
index 6b138fa97db8..339399cbabe9 100644
--- a/include/linux/ceph/auth.h
+++ b/include/linux/ceph/auth.h
@@ -15,22 +15,40 @@
 struct ceph_auth_client;
 struct ceph_msg;
 
+/*
+ * Abstract authorizer handle used for authentication with Ceph services.
+ * Each authentication protocol provides its own implementation.
+ */
 struct ceph_authorizer {
+	/* Protocol-specific cleanup function */
 	void (*destroy)(struct ceph_authorizer *);
 };
 
+/*
+ * Authentication handshake state for communicating with a specific service.
+ * Contains authorizer data and cryptographic functions for message security.
+ */
 struct ceph_auth_handshake {
+	/* The authorizer token for this service connection */
 	struct ceph_authorizer *authorizer;
+	/* Serialized authorizer data sent to the service */
 	void *authorizer_buf;
 	size_t authorizer_buf_len;
+	/* Buffer for receiving authorizer reply from service */
 	void *authorizer_reply_buf;
 	size_t authorizer_reply_buf_len;
+	/* Sign outgoing messages using session keys */
 	int (*sign_message)(struct ceph_auth_handshake *auth,
 			    struct ceph_msg *msg);
+	/* Verify signatures on incoming messages */
 	int (*check_message_signature)(struct ceph_auth_handshake *auth,
 				       struct ceph_msg *msg);
 };
 
+/*
+ * Protocol-specific operations for authentication with Ceph monitors.
+ * Each authentication method (cephx, etc.) implements these callbacks.
+ */
 struct ceph_auth_client_ops {
 	/*
 	 * true if we are authenticated and can connect to
@@ -87,20 +105,35 @@ struct ceph_auth_client_ops {
 				       struct ceph_msg *msg);
 };
 
+/*
+ * Main authentication client state for communicating with Ceph monitors.
+ * Manages protocol negotiation, credentials, and service authorization.
+ */
 struct ceph_auth_client {
-	u32 protocol;           /* CEPH_AUTH_* */
-	void *private;          /* for use by protocol implementation */
-	const struct ceph_auth_client_ops *ops;  /* null iff protocol==0 */
-
-	bool negotiating;       /* true if negotiating protocol */
-	const char *name;       /* entity name */
-	u64 global_id;          /* our unique id in system */
-	const struct ceph_crypto_key *key;     /* our secret key */
-	unsigned want_keys;     /* which services we want */
-
-	int preferred_mode;	/* CEPH_CON_MODE_* */
-	int fallback_mode;	/* ditto */
-
+	/* Authentication protocol in use (CEPH_AUTH_*) */
+	u32 protocol;
+	/* Protocol-specific private data */
+	void *private;
+	/* Protocol operations vtable (null if protocol==0) */
+	const struct ceph_auth_client_ops *ops;
+
+	/* true if currently negotiating authentication protocol */
+	bool negotiating;
+	/* Ceph entity name (e.g., "client.admin") */
+	const char *name;
+	/* Unique identifier assigned by monitor */
+	u64 global_id;
+	/* Secret key for authentication */
+	const struct ceph_crypto_key *key;
+	/* Bitmask of services we want tickets for */
+	unsigned want_keys;
+
+	/* Preferred connection security mode */
+	int preferred_mode;
+	/* Fallback connection security mode */
+	int fallback_mode;
+
+	/* Protects concurrent access to auth state */
 	struct mutex mutex;
 };
 
-- 
2.51.0

Re: [RFC PATCH 01/20] ceph: add comments to metadata structures in auth.h

[Max Kellermann]

On 2025/09/05 22:00, Viacheslav Dubeyko <slava@dubeyko.com> wrote:
> +	/* Sign outgoing messages using session keys */
>  	int (*sign_message)(struct ceph_auth_handshake *auth,
>  			    struct ceph_msg *msg);
> +	/* Verify signatures on incoming messages */
>  	int (*check_message_signature)(struct ceph_auth_handshake *auth,
>  				       struct ceph_msg *msg);

No, this function does not verify the signatureS of incoming messageS
(two plurals).
It verifies one signature of one message.

Same mistake on sign_message.

Apart from these plurals, the text barely adds any value because this
is obvious enough from the names.  What would really have been helpful
would be an explanation of parameters and return values.  But I guess
Claude didn't know...  and fortunately didn't hallucinate anything.

> +	/* Preferred connection security mode */
> +	int preferred_mode;
> +	/* Fallback connection security mode */
> +	int fallback_mode;

You have removed important information from the old comment about what
kinds of values are expected here.

> +	/* Protects concurrent access to auth state */
>  	struct mutex mutex;

What is "auth state"?  What exactly is being protected?  Does "auth
state" mean all fields of this struct are being protected?  I guess
Claude didn't know so it just wrote some generic text devoid of
information.

[RFC PATCH 02/20] ceph: add comments to metadata structures in buffer.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_buffer in
include/linux/ceph/buffer.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/buffer.h | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/include/linux/ceph/buffer.h b/include/linux/ceph/buffer.h
index 11cdc7c60480..e04f216d2347 100644
--- a/include/linux/ceph/buffer.h
+++ b/include/linux/ceph/buffer.h
@@ -9,13 +9,16 @@
 #include <linux/uio.h>
 
 /*
- * a simple reference counted buffer.
- *
- * use kmalloc for smaller sizes, vmalloc for larger sizes.
+ * Reference counted buffer metadata: Simple buffer management with automatic
+ * memory allocation strategy. Uses kmalloc for smaller buffers and vmalloc
+ * for larger buffers to optimize memory usage and fragmentation.
  */
 struct ceph_buffer {
+	/* Reference counting for safe shared access */
 	struct kref kref;
+	/* Kernel vector containing buffer pointer and length */
 	struct kvec vec;
+	/* Total allocated buffer size (may be larger than vec.iov_len) */
 	size_t alloc_len;
 };
 
-- 
2.51.0

Re: [RFC PATCH 02/20] ceph: add comments to metadata structures in buffer.h

[Max Kellermann]

On 2025/09/05 22:00, Viacheslav Dubeyko <slava@dubeyko.com> wrote:
> Claude AI generated comments

Is LLM-generated text acceptable in the kernel?  Last week, I was
asked to add more explanations to a patch, but it was rejected because
I was accused of having used a LLM.

I feel that asking others to review LLM-generated content is a DoS on
their time.

>  /*
> - * a simple reference counted buffer.
> - *
> - * use kmalloc for smaller sizes, vmalloc for larger sizes.
> + * Reference counted buffer metadata: Simple buffer management with automatic
> + * memory allocation strategy. Uses kmalloc for smaller buffers and vmalloc
> + * for larger buffers to optimize memory usage and fragmentation.

This rephrasing done by your LLM is wrong.  Previously, the buffer
(i.e. the struct) was "simple".  Now, the management of this data
structure is called "simple".  Can you explain why you thought
changing this meaning is an improvement?

Even ignoring this part, I don't see any other improvement here.  This
just expands the wording (requires more time to read) but adds no
value.

>   */
>  struct ceph_buffer {
> +	/* Reference counting for safe shared access */

This is not "reference counting", but a "reference counter".  But who
really needs to be taught what a "struct kref" is?

And what does "safe shared access" mean?  This wording sounds like
it's for (thread) synchronization, but it's really only about knowing
when the object can be freed because no reference exists.

>  	struct kref kref;
> +	/* Kernel vector containing buffer pointer and length */

I don't think it is helpful to add an explanation of what a "struct
kvec" consists of here.  This is just redundant noise.

>  	struct kvec vec;
> +	/* Total allocated buffer size (may be larger than vec.iov_len) */
>  	size_t alloc_len;

This is the only useful piece of information added by this patch,
albeit trivial enough for everybody to induce from the name.

I'm not so excited about what you got from Claude here.

[RFC PATCH 03/20] ceph: add comments in ceph_debug.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds clarifiying comments in
include/linux/ceph/ceph_debug.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/ceph_debug.h | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/include/linux/ceph/ceph_debug.h b/include/linux/ceph/ceph_debug.h
index 5f904591fa5f..d94865e762d1 100644
--- a/include/linux/ceph/ceph_debug.h
+++ b/include/linux/ceph/ceph_debug.h
@@ -9,11 +9,16 @@
 #ifdef CONFIG_CEPH_LIB_PRETTYDEBUG
 
 /*
- * wrap pr_debug to include a filename:lineno prefix on each line.
- * this incurs some overhead (kernel size and execution time) due to
- * the extra function call at each call site.
+ * Pretty debug output metadata: Enhanced debugging infrastructure that provides
+ * detailed context information including filenames, line numbers, and client
+ * identification. Incurs additional overhead but significantly improves debugging
+ * capabilities for complex distributed system interactions.
  */
 
+/*
+ * Active debug macros: Full-featured debugging with file/line context.
+ * Format: "MODULE FILE:LINE : message" with optional client identification.
+ */
 # if defined(DEBUG) || defined(CONFIG_DYNAMIC_DEBUG)
 #  define dout(fmt, ...)						\
 	pr_debug("%.*s %12.12s:%-4d : " fmt,				\
@@ -26,7 +31,10 @@
 		 &client->fsid, client->monc.auth->global_id,		\
 		 ##__VA_ARGS__)
 # else
-/* faux printk call just to see any compiler warnings. */
+/*
+ * Compile-time debug validation: No-op macros that preserve format string
+ * checking without generating debug output. Catches format errors at compile time.
+ */
 #  define dout(fmt, ...)					\
 		no_printk(KERN_DEBUG fmt, ##__VA_ARGS__)
 #  define doutc(client, fmt, ...)				\
@@ -39,7 +47,8 @@
 #else
 
 /*
- * or, just wrap pr_debug
+ * Simple debug output metadata: Basic debugging without filename/line context.
+ * Lighter weight alternative that includes client identification and function names.
  */
 # define dout(fmt, ...)	pr_debug(" " fmt, ##__VA_ARGS__)
 # define doutc(client, fmt, ...)					\
@@ -48,6 +57,12 @@
 
 #endif
 
+/*
+ * Client-aware logging macros: Production logging infrastructure that includes
+ * client identification (FSID + global ID) in all messages. Essential for
+ * debugging multi-client scenarios and cluster-wide issues.
+ * Format: "[FSID GLOBAL_ID]: message"
+ */
 #define pr_notice_client(client, fmt, ...)				\
 	pr_notice("[%pU %llu]: " fmt, &client->fsid,			\
 		  client->monc.auth->global_id, ##__VA_ARGS__)
-- 
2.51.0

[RFC PATCH 04/20] ceph: add comments to declarations in ceph_features.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds detailed explanation of several constants
declarations and macros in include/linux/ceph/ceph_features.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/ceph_features.h | 47 ++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 9 deletions(-)

diff --git a/include/linux/ceph/ceph_features.h b/include/linux/ceph/ceph_features.h
index 3a47acd9cc14..31a270b624fe 100644
--- a/include/linux/ceph/ceph_features.h
+++ b/include/linux/ceph/ceph_features.h
@@ -3,37 +3,60 @@
 #define __CEPH_FEATURES
 
 /*
- * Each time we reclaim bits for reuse we need to specify another bit
+ * Feature incarnation metadata: Each time we reclaim bits for reuse we need to specify another bit
  * that, if present, indicates we have the new incarnation of that
  * feature.  Base case is 1 (first use).
  */
+/* Base incarnation - original feature bit definitions */
 #define CEPH_FEATURE_INCARNATION_1 (0ull)
+/* Second incarnation - requires SERVER_JEWEL support */
 #define CEPH_FEATURE_INCARNATION_2 (1ull<<57)              // SERVER_JEWEL
+/* Third incarnation - requires both SERVER_JEWEL and SERVER_MIMIC */
 #define CEPH_FEATURE_INCARNATION_3 ((1ull<<57)|(1ull<<28)) // SERVER_MIMIC
 
+/*
+ * Feature definition macro: Creates both feature bit and feature mask constants.
+ * @bit: The feature bit position (0-63)
+ * @incarnation: Which incarnation of this bit (1, 2, or 3)
+ * @name: Feature name suffix for CEPH_FEATURE_* constants
+ */
 #define DEFINE_CEPH_FEATURE(bit, incarnation, name)			\
 	static const uint64_t __maybe_unused CEPH_FEATURE_##name = (1ULL<<bit);		\
 	static const uint64_t __maybe_unused CEPH_FEATUREMASK_##name =			\
 		(1ULL<<bit | CEPH_FEATURE_INCARNATION_##incarnation);
 
-/* this bit is ignored but still advertised by release *when* */
+/*
+ * Deprecated feature definition macro: This bit is ignored but still advertised by release *when*
+ * @bit: The feature bit position
+ * @incarnation: Which incarnation of this bit
+ * @name: Feature name suffix
+ * @when: Release version when this feature was deprecated
+ */
 #define DEFINE_CEPH_FEATURE_DEPRECATED(bit, incarnation, name, when) \
 	static const uint64_t __maybe_unused DEPRECATED_CEPH_FEATURE_##name = (1ULL<<bit);	\
 	static const uint64_t __maybe_unused DEPRECATED_CEPH_FEATUREMASK_##name =		\
 		(1ULL<<bit | CEPH_FEATURE_INCARNATION_##incarnation);
 
 /*
- * this bit is ignored by release *unused* and not advertised by
- * release *unadvertised*
+ * Retired feature definition macro: This bit is ignored by release *unused* and not advertised by
+ * release *unadvertised*. The bit can be safely reused in future incarnations.
+ * @bit: The feature bit position
+ * @inc: Which incarnation this bit was retired from
+ * @name: Feature name suffix
+ * @unused: Release version that stopped using this bit
+ * @unadvertised: Release version that stopped advertising this bit
  */
 #define DEFINE_CEPH_FEATURE_RETIRED(bit, inc, name, unused, unadvertised)
 
 
 /*
- * test for a feature.  this test is safer than a typical mask against
- * the bit because it ensures that we have the bit AND the marker for the
- * bit's incarnation.  this must be used in any case where the features
- * bits may include an old meaning of the bit.
+ * Safe feature testing macro: Test for a feature using incarnation-aware comparison.
+ * This test is safer than a typical mask against the bit because it ensures that we have
+ * the bit AND the marker for the bit's incarnation. This must be used in any case where
+ * the features bits may include an old meaning of the bit.
+ * @x: Feature bitmask to test
+ * @name: Feature name suffix to test for
+ * Returns: true if both the feature bit and its incarnation markers are present
  */
 #define CEPH_HAVE_FEATURE(x, name)			\
 	(((x) & (CEPH_FEATUREMASK_##name)) == (CEPH_FEATUREMASK_##name))
@@ -174,7 +197,9 @@ DEFINE_CEPH_FEATURE_DEPRECATED(63, 1, RESERVED_BROKEN, LUMINOUS) // client-facin
 
 
 /*
- * Features supported.
+ * Default supported features bitmask: Defines the complete set of Ceph protocol features
+ * that this kernel client implementation supports. This determines compatibility with
+ * different Ceph server versions and enables various protocol optimizations and capabilities.
  */
 #define CEPH_FEATURES_SUPPORTED_DEFAULT		\
 	(CEPH_FEATURE_NOSRCADDR |		\
@@ -219,6 +244,10 @@ DEFINE_CEPH_FEATURE_DEPRECATED(63, 1, RESERVED_BROKEN, LUMINOUS) // client-facin
 	 CEPH_FEATURE_MSG_ADDR2 |		\
 	 CEPH_FEATURE_CEPHX_V2)
 
+/*
+ * Required features bitmask: Features that must be supported by peers.
+ * Currently set to 0, meaning no features are strictly required.
+ */
 #define CEPH_FEATURES_REQUIRED_DEFAULT	0
 
 #endif
-- 
2.51.0

[RFC PATCH 05/20] ceph: rework comments in ceph_frag.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch reworks comments for ceph_frag_make() and
ceph_frag_compare() in include/linux/ceph/ceph_frag.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/ceph_frag.h | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/include/linux/ceph/ceph_frag.h b/include/linux/ceph/ceph_frag.h
index 97bab0adc58a..c88c0e68727d 100644
--- a/include/linux/ceph/ceph_frag.h
+++ b/include/linux/ceph/ceph_frag.h
@@ -3,20 +3,26 @@
 #define FS_CEPH_FRAG_H
 
 /*
+ * Directory fragment metadata encoding: CephFS uses "frags" to partition
+ * directory namespace for distributed metadata management. Each fragment
+ * represents a contiguous range of the directory's hash space, allowing
+ * directories to be split across multiple metadata servers (MDSs).
+ *
  * "Frags" are a way to describe a subset of a 32-bit number space,
- * using a mask and a value to match against that mask.  Any given frag
+ * using a mask and a value to match against that mask. Any given frag
  * (subset of the number space) can be partitioned into 2^n sub-frags.
  *
  * Frags are encoded into a 32-bit word:
- *   8 upper bits = "bits"
- *  24 lower bits = "value"
+ *   8 upper bits = "bits" (depth of partitioning)
+ *  24 lower bits = "value" (fragment identifier within the partition)
  * (We could go to 5+27 bits, but who cares.)
  *
- * We use the _most_ significant bits of the 24 bit value.  This makes
- * values logically sort.
+ * We use the _most_ significant bits of the 24 bit value. This makes
+ * values logically sort, enabling efficient traversal of the directory
+ * namespace in hash order.
  *
  * Unfortunately, because the "bits" field is still in the high bits, we
- * can't sort encoded frags numerically.  However, it does allow you
+ * can't sort encoded frags numerically. However, it does allow you
  * to feed encoded frags as values into frag_contains_value.
  */
 static inline __u32 ceph_frag_make(__u32 b, __u32 v)
@@ -67,8 +73,10 @@ static inline __u32 ceph_frag_next(__u32 f)
 }
 
 /*
- * comparator to sort frags logically, as when traversing the
- * number space in ascending order...
+ * Fragment comparison function: Comparator to sort frags logically for
+ * ordered traversal of the directory namespace. Since encoded frags cannot
+ * be sorted numerically due to the bit field layout, this function provides
+ * the correct logical ordering for directory fragment processing.
  */
 int ceph_frag_compare(__u32 a, __u32 b);
 
-- 
2.51.0

[RFC PATCH 06/20] ceph: add comments to metadata structures in ceph_fs.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_file_layout_legacy,
struct ceph_file_layout, struct ceph_dir_layout,
struct ceph_mon_request_header, struct ceph_mon_statfs,
struct ceph_statfs, struct ceph_mon_statfs_reply,
struct ceph_mon_command, struct ceph_osd_getmap,
struct ceph_mds_getmap, struct ceph_client_mount,
struct ceph_mon_subscribe_item, struct ceph_mon_subscribe_ack,
struct ceph_mds_session_head, union ceph_mds_request_args,
union ceph_mds_request_args_ext, struct ceph_mds_request_head_legacy,
struct ceph_mds_request_head, struct ceph_mds_request_release,
struct ceph_mds_reply_head, struct ceph_frag_tree_split,
struct ceph_frag_tree_head, struct ceph_mds_reply_cap,
struct ceph_mds_reply_inode, struct ceph_mds_reply_lease,
struct ceph_mds_reply_dirfrag, struct ceph_filelock,
struct ceph_mds_caps, struct ceph_mds_cap_peer,
struct ceph_mds_cap_release, struct ceph_mds_cap_item,
struct ceph_mds_lease, struct ceph_mds_cap_reconnect,
struct ceph_mds_cap_reconnect_v1, struct ceph_mds_snaprealm_reconnect,
struct ceph_mds_snap_head, struct ceph_mds_snap_realm,
struct ceph_mds_quota in /include/linux/ceph/ceph_fs.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/ceph_fs.h | 792 +++++++++++++++++++++++------------
 1 file changed, 532 insertions(+), 260 deletions(-)

diff --git a/include/linux/ceph/ceph_fs.h b/include/linux/ceph/ceph_fs.h
index c7f2c63b3bc3..8f3452439d97 100644
--- a/include/linux/ceph/ceph_fs.h
+++ b/include/linux/ceph/ceph_fs.h
@@ -35,36 +35,50 @@
 #define CEPH_MAX_MON   31
 
 /*
- * legacy ceph_file_layoute
+ * Legacy file layout metadata: Wire format for older file layout structures.
+ * Describes how a file's data is striped across RADOS objects and distributed
+ * across placement groups. Maintained for backward compatibility.
  */
 struct ceph_file_layout_legacy {
-	/* file -> object mapping */
-	__le32 fl_stripe_unit;     /* stripe unit, in bytes.  must be multiple
-				      of page size. */
-	__le32 fl_stripe_count;    /* over this many objects */
-	__le32 fl_object_size;     /* until objects are this big, then move to
-				      new objects */
-	__le32 fl_cas_hash;        /* UNUSED.  0 = none; 1 = sha256 */
-
-	/* pg -> disk layout */
-	__le32 fl_object_stripe_unit;  /* UNUSED.  for per-object parity, if any */
-
-	/* object -> pg layout */
-	__le32 fl_unused;       /* unused; used to be preferred primary for pg (-1 for none) */
-	__le32 fl_pg_pool;      /* namespace, crush ruleset, rep level */
+	/* File-to-object mapping parameters */
+	/* Stripe unit size in bytes (must be page-aligned) */
+	__le32 fl_stripe_unit;
+	/* Number of objects to stripe across */
+	__le32 fl_stripe_count;
+	/* Maximum object size before creating new objects */
+	__le32 fl_object_size;
+	/* Content-addressable storage hash (unused) */
+	__le32 fl_cas_hash;
+
+	/* Placement group to disk layout */
+	/* Per-object parity stripe unit (unused) */
+	__le32 fl_object_stripe_unit;
+
+	/* Object to placement group layout */
+	/* Unused field (was preferred primary PG) */
+	__le32 fl_unused;
+	/* Pool ID for namespace, CRUSH rules, replication level */
+	__le32 fl_pg_pool;
 } __attribute__ ((packed));
 
 struct ceph_string;
 /*
- * ceph_file_layout - describe data layout for a file/inode
+ * File layout metadata: Describes how a file's data is distributed across
+ * RADOS objects within a storage pool. Controls striping, object sizing,
+ * and namespace placement for optimal performance and data distribution.
  */
 struct ceph_file_layout {
-	/* file -> object mapping */
-	u32 stripe_unit;   /* stripe unit, in bytes */
-	u32 stripe_count;  /* over this many objects */
-	u32 object_size;   /* until objects are this big */
-	s64 pool_id;        /* rados pool id */
-	struct ceph_string __rcu *pool_ns; /* rados pool namespace */
+	/* File-to-object striping parameters */
+	/* Stripe unit size in bytes */
+	u32 stripe_unit;
+	/* Number of objects to stripe data across */
+	u32 stripe_count;
+	/* Maximum size of individual RADOS objects */
+	u32 object_size;
+	/* Target RADOS pool ID */
+	s64 pool_id;
+	/* Optional pool namespace (RCU-protected string) */
+	struct ceph_string __rcu *pool_ns;
 };
 
 extern int ceph_file_layout_is_valid(const struct ceph_file_layout *layout);
@@ -75,8 +89,15 @@ extern void ceph_file_layout_to_legacy(struct ceph_file_layout *fl,
 
 #define CEPH_MIN_STRIPE_UNIT 65536
 
+/*
+ * Directory layout metadata: Describes how directory entries are distributed
+ * and hashed for efficient lookup and enumeration. Currently minimal with
+ * most fields reserved for future expansion.
+ */
 struct ceph_dir_layout {
-	__u8   dl_dir_hash;   /* see ceph_hash.h for ids */
+	/* Directory hash function ID (see ceph_hash.h) */
+	__u8   dl_dir_hash;
+	/* Reserved fields for future use */
 	__u8   dl_unused1;
 	__u16  dl_unused2;
 	__u32  dl_unused3;
@@ -172,63 +193,137 @@ enum {
 };
 
 
+/*
+ * Monitor request header metadata: Common header for all client requests
+ * to Ceph monitors. Includes version tracking and session identification
+ * for proper request sequencing and duplicate detection.
+ */
 struct ceph_mon_request_header {
+	/* Highest map version client currently has */
 	__le64 have_version;
+	/* Monitor rank for this session */
 	__le16 session_mon;
+	/* Transaction ID for this monitor session */
 	__le64 session_mon_tid;
 } __attribute__ ((packed));
 
+/*
+ * Ceph monitor statfs request structure
+ *
+ * Sent to the monitor to request filesystem statistics information.
+ * Can request stats for the entire cluster or for a specific data pool.
+ * The monitor responds with usage, capacity, and object count information.
+ */
 struct ceph_mon_statfs {
-	struct ceph_mon_request_header monhdr;
-	struct ceph_fsid fsid;
-	__u8 contains_data_pool;
-	__le64 data_pool;
+	struct ceph_mon_request_header monhdr; /* standard monitor request header */
+	struct ceph_fsid fsid;                 /* filesystem identifier */
+	__u8 contains_data_pool;               /* whether requesting pool-specific stats */
+	__le64 data_pool;                      /* specific pool ID (if contains_data_pool) */
 } __attribute__ ((packed));
 
+/*
+ * Filesystem statistics metadata: Reports storage usage and capacity
+ * information for a Ceph filesystem or pool. Used by statfs() system call.
+ */
 struct ceph_statfs {
-	__le64 kb, kb_used, kb_avail;
+	/* Total capacity in kilobytes */
+	__le64 kb;
+	/* Used space in kilobytes */
+	__le64 kb_used;
+	/* Available space in kilobytes */
+	__le64 kb_avail;
+	/* Total number of objects stored */
 	__le64 num_objects;
 } __attribute__ ((packed));
 
+/*
+ * Ceph monitor statfs reply structure
+ *
+ * Response from the monitor containing filesystem statistics information.
+ * Sent in response to a ceph_mon_statfs request, providing current usage,
+ * capacity, and object count data for the requested filesystem or pool.
+ */
 struct ceph_mon_statfs_reply {
-	struct ceph_fsid fsid;
-	__le64 version;
-	struct ceph_statfs st;
+	struct ceph_fsid fsid;         /* filesystem identifier */
+	__le64 version;                /* statistics version/timestamp */
+	struct ceph_statfs st;         /* actual filesystem statistics */
 } __attribute__ ((packed));
 
+/*
+ * Ceph monitor command structure
+ *
+ * Used to send administrative commands to the Ceph monitor. The command
+ * is specified as a text string that follows this header structure.
+ * Monitor responds with command results or error information.
+ */
 struct ceph_mon_command {
-	struct ceph_mon_request_header monhdr;
-	struct ceph_fsid fsid;
-	__le32 num_strs;         /* always 1 */
-	__le32 str_len;
-	char str[];
+	struct ceph_mon_request_header monhdr; /* standard monitor request header */
+	struct ceph_fsid fsid;                 /* filesystem identifier */
+	__le32 num_strs;                       /* number of command strings (always 1) */
+	__le32 str_len;                        /* length of command string */
+	char str[];                            /* command string (variable length) */
 } __attribute__ ((packed));
 
+/*
+ * Ceph OSD map request structure
+ *
+ * Sent to the monitor to request OSD map updates. The client specifies
+ * a starting epoch to receive incremental map updates from that point.
+ * Essential for maintaining current cluster topology and OSD status.
+ */
 struct ceph_osd_getmap {
-	struct ceph_mon_request_header monhdr;
-	struct ceph_fsid fsid;
-	__le32 start;
+	struct ceph_mon_request_header monhdr; /* standard monitor request header */
+	struct ceph_fsid fsid;                 /* filesystem identifier */
+	__le32 start;                          /* starting epoch for map updates */
 } __attribute__ ((packed));
 
+/*
+ * Ceph MDS map request structure
+ *
+ * Sent to the monitor to request MDS map updates. Contains information
+ * about active metadata servers, their states, and filesystem layout.
+ * Critical for clients to know which MDS to contact for operations.
+ */
 struct ceph_mds_getmap {
-	struct ceph_mon_request_header monhdr;
-	struct ceph_fsid fsid;
+	struct ceph_mon_request_header monhdr; /* standard monitor request header */
+	struct ceph_fsid fsid;                 /* filesystem identifier */
 } __attribute__ ((packed));
 
+/*
+ * Ceph client mount request structure
+ *
+ * Minimal structure sent to the monitor during client mount operations.
+ * Used to signal client presence and initiate the mount handshake with
+ * the monitor. Contains only the basic monitor request header.
+ */
 struct ceph_client_mount {
-	struct ceph_mon_request_header monhdr;
+	struct ceph_mon_request_header monhdr; /* standard monitor request header */
 } __attribute__ ((packed));
 
 #define CEPH_SUBSCRIBE_ONETIME    1  /* i want only 1 update after have */
 
+/*
+ * Ceph monitor subscription item
+ *
+ * Specifies subscription parameters for receiving map updates from the
+ * monitor. Used within subscription requests to indicate starting epoch
+ * and subscription behavior (one-time vs continuous updates).
+ */
 struct ceph_mon_subscribe_item {
-	__le64 start;
-	__u8 flags;
+	__le64 start;                          /* starting epoch/version for updates */
+	__u8 flags;                            /* subscription flags (CEPH_SUBSCRIBE_*) */
 } __attribute__ ((packed));
 
+/*
+ * Ceph monitor subscription acknowledgment
+ *
+ * Response from monitor confirming subscription requests. Indicates how long
+ * the subscription will remain active and confirms the filesystem ID.
+ * Used for managing subscription renewal timing.
+ */
 struct ceph_mon_subscribe_ack {
-	__le32 duration;         /* seconds */
-	struct ceph_fsid fsid;
+	__le32 duration;                       /* subscription duration in seconds */
+	struct ceph_fsid fsid;                 /* filesystem identifier */
 } __attribute__ ((packed));
 
 #define CEPH_FS_CLUSTER_ID_NONE  -1
@@ -306,11 +401,21 @@ enum {
 
 extern const char *ceph_session_op_name(int op);
 
+/*
+ * MDS session header metadata: Header for metadata server session messages.
+ * Manages the client-MDS session lifecycle including capability and lease limits.
+ */
 struct ceph_mds_session_head {
+	/* Session operation type */
 	__le32 op;
+	/* Session sequence number */
 	__le64 seq;
+	/* Message timestamp */
 	struct ceph_timespec stamp;
-	__le32 max_caps, max_leases;
+	/* Maximum capabilities client can hold */
+	__le32 max_caps;
+	/* Maximum directory entry leases */
+	__le32 max_leases;
 } __attribute__ ((packed));
 
 /* client_request */
@@ -410,78 +515,113 @@ extern const char *ceph_mds_op_name(int op);
 #define CEPH_O_DIRECTORY	00200000
 #define CEPH_O_NOFOLLOW		00400000
 
+/*
+ * Ceph MDS request arguments union
+ *
+ * Contains operation-specific arguments for different MDS operations.
+ * Each operation type has its own structure within the union, providing
+ * the specific parameters needed for that operation while sharing the
+ * same memory space efficiently.
+ */
 union ceph_mds_request_args {
+	/* Get inode attributes operation */
 	struct {
-		__le32 mask;                 /* CEPH_CAP_* */
+		__le32 mask;                 /* attribute mask (CEPH_CAP_*) */
 	} __attribute__ ((packed)) getattr;
+
+	/* Set inode attributes operation */
 	struct {
-		__le32 mode;
-		__le32 uid;
-		__le32 gid;
-		struct ceph_timespec mtime;
-		struct ceph_timespec atime;
-		__le64 size, old_size;       /* old_size needed by truncate */
-		__le32 mask;                 /* CEPH_SETATTR_* */
+		__le32 mode;                 /* file permissions */
+		__le32 uid;                  /* user ID */
+		__le32 gid;                  /* group ID */
+		struct ceph_timespec mtime;  /* modification time */
+		struct ceph_timespec atime;  /* access time */
+		__le64 size, old_size;       /* new and old file sizes */
+		__le32 mask;                 /* which attributes to set (CEPH_SETATTR_*) */
 	} __attribute__ ((packed)) setattr;
+
+	/* Read directory entries operation */
 	struct {
-		__le32 frag;                 /* which dir fragment */
-		__le32 max_entries;          /* how many dentries to grab */
-		__le32 max_bytes;
-		__le16 flags;
-		__le32 offset_hash;
+		__le32 frag;                 /* directory fragment to read */
+		__le32 max_entries;          /* maximum number of entries to return */
+		__le32 max_bytes;            /* maximum response size in bytes */
+		__le16 flags;                /* readdir operation flags */
+		__le32 offset_hash;          /* hash offset for pagination */
 	} __attribute__ ((packed)) readdir;
+
+	/* Create device node (mknod) operation */
 	struct {
-		__le32 mode;
-		__le32 rdev;
+		__le32 mode;                 /* file type and permissions */
+		__le32 rdev;                 /* device number (major/minor) */
 	} __attribute__ ((packed)) mknod;
+
+	/* Create directory (mkdir) operation */
 	struct {
-		__le32 mode;
+		__le32 mode;                 /* directory permissions */
 	} __attribute__ ((packed)) mkdir;
+
+	/* Open/create file operation */
 	struct {
-		__le32 flags;
-		__le32 mode;
-		__le32 stripe_unit;          /* layout for newly created file */
-		__le32 stripe_count;         /* ... */
-		__le32 object_size;
-		__le32 pool;
-		__le32 mask;                 /* CEPH_CAP_* */
-		__le64 old_size;
+		__le32 flags;                /* open flags (O_RDWR, O_CREAT, etc.) */
+		__le32 mode;                 /* file permissions (for creation) */
+		__le32 stripe_unit;          /* RADOS striping unit size */
+		__le32 stripe_count;         /* number of objects to stripe across */
+		__le32 object_size;          /* RADOS object size */
+		__le32 pool;                 /* RADOS pool ID */
+		__le32 mask;                 /* capability mask for new file */
+		__le64 old_size;             /* previous file size (for truncation) */
 	} __attribute__ ((packed)) open;
+
+	/* Set extended attributes operation */
 	struct {
-		__le32 flags;
-		__le32 osdmap_epoch; /* used for setting file/dir layouts */
+		__le32 flags;                /* xattr operation flags */
+		__le32 osdmap_epoch;         /* OSD map epoch for consistency */
 	} __attribute__ ((packed)) setxattr;
+
+	/* Set file/directory layout operation */
 	struct {
-		struct ceph_file_layout_legacy layout;
+		struct ceph_file_layout_legacy layout; /* striping layout */
 	} __attribute__ ((packed)) setlayout;
+
+	/* File locking operation */
 	struct {
-		__u8 rule; /* currently fcntl or flock */
-		__u8 type; /* shared, exclusive, remove*/
-		__le64 owner; /* owner of the lock */
-		__le64 pid; /* process id requesting the lock */
-		__le64 start; /* initial location to lock */
-		__le64 length; /* num bytes to lock from start */
-		__u8 wait; /* will caller wait for lock to become available? */
+		__u8 rule;                   /* lock rule (CEPH_LOCK_FCNTL/FLOCK) */
+		__u8 type;                   /* lock type (SHARED/EXCL/UNLOCK) */
+		__le64 owner;                /* lock owner identifier */
+		__le64 pid;                  /* process ID holding the lock */
+		__le64 start;                /* byte offset where lock begins */
+		__le64 length;               /* number of bytes to lock */
+		__u8 wait;                   /* whether to wait for lock */
 	} __attribute__ ((packed)) filelock_change;
+
+	/* Lookup by inode number operation */
 	struct {
-		__le32 mask;                 /* CEPH_CAP_* */
-		__le64 snapid;
-		__le64 parent;
-		__le32 hash;
+		__le32 mask;                 /* attribute mask for returned data */
+		__le64 snapid;               /* snapshot ID */
+		__le64 parent;               /* parent inode number */
+		__le32 hash;                 /* inode hash for verification */
 	} __attribute__ ((packed)) lookupino;
 } __attribute__ ((packed));
 
+/*
+ * Ceph MDS request arguments union (extended version)
+ *
+ * This union extends the original ceph_mds_request_args with support
+ * for newer protocol features. It maintains backward compatibility
+ * while adding extended functionality like birth time support.
+ */
 union ceph_mds_request_args_ext {
-	union ceph_mds_request_args old;
+	union ceph_mds_request_args old; /* legacy argument formats */
+	/* Extended setattr arguments with birth time support */
 	struct {
-		__le32 mode;
-		__le32 uid;
-		__le32 gid;
-		struct ceph_timespec mtime;
-		struct ceph_timespec atime;
-		__le64 size, old_size;       /* old_size needed by truncate */
-		__le32 mask;                 /* CEPH_SETATTR_* */
-		struct ceph_timespec btime;
+		__le32 mode;                 /* file permissions */
+		__le32 uid;                  /* user ID */
+		__le32 gid;                  /* group ID */
+		struct ceph_timespec mtime;  /* modification time */
+		struct ceph_timespec atime;  /* access time */
+		__le64 size, old_size;       /* current and previous file sizes */
+		__le32 mask;                 /* attribute mask (CEPH_SETATTR_*) */
+		struct ceph_timespec btime;  /* birth/creation time (extended) */
 	} __attribute__ ((packed)) setattr_ext;
 };
 
@@ -489,119 +629,183 @@ union ceph_mds_request_args_ext {
 #define CEPH_MDS_FLAG_WANT_DENTRY	2 /* want dentry in reply */
 #define CEPH_MDS_FLAG_ASYNC		4 /* request is asynchronous */
 
+/*
+ * Ceph MDS request message header (legacy version)
+ *
+ * This is the original MDS request header format used before protocol
+ * version 4. It lacks the version field and extended features present
+ * in the modern header. Used for backward compatibility with older
+ * MDS servers that don't support newer protocol features.
+ */
 struct ceph_mds_request_head_legacy {
-	__le64 oldest_client_tid;
-	__le32 mdsmap_epoch;           /* on client */
-	__le32 flags;                  /* CEPH_MDS_FLAG_* */
-	__u8 num_retry, num_fwd;       /* count retry, fwd attempts */
-	__le16 num_releases;           /* # include cap/lease release records */
-	__le32 op;                     /* mds op code */
-	__le32 caller_uid, caller_gid;
-	__le64 ino;                    /* use this ino for openc, mkdir, mknod,
-					  etc. (if replaying) */
-	union ceph_mds_request_args args;
+	__le64 oldest_client_tid;      /* oldest transaction ID from client */
+	__le32 mdsmap_epoch;           /* MDS map epoch client is using */
+	__le32 flags;                  /* request flags (CEPH_MDS_FLAG_*) */
+	__u8 num_retry, num_fwd;       /* retry and forward attempt counters */
+	__le16 num_releases;           /* number of cap/lease release records */
+	__le32 op;                     /* MDS operation code to perform */
+	__le32 caller_uid, caller_gid; /* credentials of the caller */
+	__le64 ino;                    /* inode number for replay operations */
+	union ceph_mds_request_args args; /* operation-specific arguments */
 } __attribute__ ((packed));
 
 #define CEPH_MDS_REQUEST_HEAD_VERSION  3
 
+/*
+ * Ceph MDS request message header
+ *
+ * Contains the header information for all MDS request messages, including
+ * operation type, client context, retry information, and operation-specific
+ * arguments. This structure has evolved over time with different versions.
+ */
 struct ceph_mds_request_head {
-	__le16 version;                /* struct version */
-	__le64 oldest_client_tid;
-	__le32 mdsmap_epoch;           /* on client */
-	__le32 flags;                  /* CEPH_MDS_FLAG_* */
-	__u8 num_retry, num_fwd;       /* legacy count retry and fwd attempts */
-	__le16 num_releases;           /* # include cap/lease release records */
-	__le32 op;                     /* mds op code */
-	__le32 caller_uid, caller_gid;
-	__le64 ino;                    /* use this ino for openc, mkdir, mknod,
-					  etc. (if replaying) */
-	union ceph_mds_request_args_ext args;
-
-	__le32 ext_num_retry;          /* new count retry attempts */
-	__le32 ext_num_fwd;            /* new count fwd attempts */
-
-	__le32 struct_len;             /* to store size of struct ceph_mds_request_head */
-	__le32 owner_uid, owner_gid;   /* used for OPs which create inodes */
-} __attribute__ ((packed));
-
-/* cap/lease release record */
+	__le16 version;                /* header structure version */
+	__le64 oldest_client_tid;      /* oldest transaction ID from client */
+	__le32 mdsmap_epoch;           /* MDS map epoch client is using */
+	__le32 flags;                  /* request flags (CEPH_MDS_FLAG_*) */
+	__u8 num_retry, num_fwd;       /* legacy retry and forward counters */
+	__le16 num_releases;           /* number of cap/lease release records */
+	__le32 op;                     /* MDS operation code to perform */
+	__le32 caller_uid, caller_gid; /* credentials of the caller */
+	__le64 ino;                    /* inode number for replay operations */
+	union ceph_mds_request_args_ext args; /* operation-specific arguments */
+
+	__le32 ext_num_retry;          /* extended retry attempt counter */
+	__le32 ext_num_fwd;            /* extended forward attempt counter */
+
+	__le32 struct_len;             /* size of this header structure */
+	__le32 owner_uid, owner_gid;   /* ownership for inode creation operations */
+} __attribute__ ((packed));
+
+/*
+ * Ceph MDS capability/lease release record
+ *
+ * Included in MDS requests to inform the MDS about capabilities or
+ * directory leases that the client is releasing. This allows the
+ * client to proactively return unused capabilities to reduce overhead.
+ */
 struct ceph_mds_request_release {
-	__le64 ino, cap_id;            /* ino and unique cap id */
-	__le32 caps, wanted;           /* new issued, wanted */
-	__le32 seq, issue_seq, mseq;
-	__le32 dname_seq;              /* if releasing a dentry lease, a */
-	__le32 dname_len;              /* string follows. */
+	__le64 ino, cap_id;            /* inode number and capability identifier */
+	__le32 caps, wanted;           /* capabilities being released/still wanted */
+	__le32 seq, issue_seq, mseq;   /* sequence numbers for capability tracking */
+	__le32 dname_seq;              /* directory name lease sequence number */
+	__le32 dname_len;              /* length of dentry name string (follows) */
 } __attribute__ ((packed));
 
 /* client reply */
+/*
+ * Ceph MDS reply message header
+ *
+ * Contains the header information for all MDS reply messages, including
+ * operation status, result codes, and flags indicating what additional
+ * data structures follow in the message payload.
+ */
 struct ceph_mds_reply_head {
-	__le32 op;
-	__le32 result;
-	__le32 mdsmap_epoch;
-	__u8 safe;                     /* true if committed to disk */
-	__u8 is_dentry, is_target;     /* true if dentry, target inode records
-					  are included with reply */
+	__le32 op;                     /* MDS operation that was performed */
+	__le32 result;                 /* operation result code (errno) */
+	__le32 mdsmap_epoch;           /* MDS map epoch when reply was sent */
+	__u8 safe;                     /* true if operation committed to disk */
+	__u8 is_dentry, is_target;     /* flags: dentry and target inode data included */
 } __attribute__ ((packed));
 
 /* one for each node split */
+/*
+ * Ceph directory fragment tree split record
+ *
+ * Describes how a directory fragment is split into smaller fragments.
+ * Each record specifies a fragment ID and the number of bits by which
+ * it should be split to create multiple sub-fragments.
+ */
 struct ceph_frag_tree_split {
-	__le32 frag;                   /* this frag splits... */
-	__le32 by;                     /* ...by this many bits */
+	__le32 frag;                   /* fragment identifier to split */
+	__le32 by;                     /* number of bits to split by */
 } __attribute__ ((packed));
 
+/*
+ * Ceph directory fragment tree header
+ *
+ * Contains the complete fragment tree structure for a directory, describing
+ * how the directory namespace is divided among multiple fragments. Large
+ * directories are split into fragments for load distribution across MDS nodes.
+ */
 struct ceph_frag_tree_head {
-	__le32 nsplits;                /* num ceph_frag_tree_split records */
-	struct ceph_frag_tree_split splits[];
+	__le32 nsplits;                /* number of fragment split records */
+	struct ceph_frag_tree_split splits[]; /* array of split records */
 } __attribute__ ((packed));
 
 /* capability issue, for bundling with mds reply */
+/*
+ * Ceph MDS reply capability structure
+ *
+ * Contains capability information included in MDS replies, specifying
+ * what capabilities are being granted to the client for an inode.
+ */
 struct ceph_mds_reply_cap {
-	__le32 caps, wanted;           /* caps issued, wanted */
-	__le64 cap_id;
-	__le32 seq, mseq;
-	__le64 realm;                  /* snap realm */
-	__u8 flags;                    /* CEPH_CAP_FLAG_* */
+	__le32 caps, wanted;           /* capabilities issued and wanted */
+	__le64 cap_id;                 /* unique capability identifier */
+	__le32 seq, mseq;              /* sequence and migration sequence numbers */
+	__le64 realm;                  /* snapshot realm this cap belongs to */
+	__u8 flags;                    /* capability flags (CEPH_CAP_FLAG_*) */
 } __attribute__ ((packed));
 
 #define CEPH_CAP_FLAG_AUTH	(1 << 0)  /* cap is issued by auth mds */
 #define CEPH_CAP_FLAG_RELEASE	(1 << 1)  /* release the cap */
 
-/* inode record, for bundling with mds reply */
+/*
+ * Ceph MDS reply inode structure
+ *
+ * Contains complete inode metadata bundled with MDS replies. This allows
+ * the MDS to send updated inode information along with operation results
+ * to keep clients synchronized with the current inode state.
+ */
 struct ceph_mds_reply_inode {
-	__le64 ino;
-	__le64 snapid;
-	__le32 rdev;
-	__le64 version;                /* inode version */
-	__le64 xattr_version;          /* version for xattr blob */
-	struct ceph_mds_reply_cap cap; /* caps issued for this inode */
-	struct ceph_file_layout_legacy layout;
-	struct ceph_timespec ctime, mtime, atime;
-	__le32 time_warp_seq;
-	__le64 size, max_size, truncate_size;
-	__le32 truncate_seq;
-	__le32 mode, uid, gid;
-	__le32 nlink;
-	__le64 files, subdirs, rbytes, rfiles, rsubdirs;  /* dir stats */
-	struct ceph_timespec rctime;
-	struct ceph_frag_tree_head fragtree;  /* (must be at end of struct) */
+	__le64 ino;                    /* inode number */
+	__le64 snapid;                 /* snapshot ID */
+	__le32 rdev;                   /* device number for special files */
+	__le64 version;                /* inode version number */
+	__le64 xattr_version;          /* extended attributes version */
+	struct ceph_mds_reply_cap cap; /* capabilities issued for this inode */
+	struct ceph_file_layout_legacy layout; /* file striping layout */
+	struct ceph_timespec ctime, mtime, atime; /* timestamps */
+	__le32 time_warp_seq;          /* time warp sequence number */
+	__le64 size, max_size, truncate_size; /* file size information */
+	__le32 truncate_seq;           /* truncate operation sequence */
+	__le32 mode, uid, gid;         /* file permissions and ownership */
+	__le32 nlink;                  /* number of hard links */
+	__le64 files, subdirs, rbytes, rfiles, rsubdirs; /* directory statistics */
+	struct ceph_timespec rctime;   /* recursive change time */
+	struct ceph_frag_tree_head fragtree; /* fragment tree (must be at end) */
 } __attribute__ ((packed));
 /* followed by frag array, symlink string, dir layout, xattr blob */
 
-/* reply_lease follows dname, and reply_inode */
+/*
+ * Ceph MDS reply lease structure
+ *
+ * Contains directory name lease information included in MDS replies.
+ * Directory leases allow clients to cache directory entries and negative
+ * lookups to improve performance by reducing round trips to the MDS.
+ */
 struct ceph_mds_reply_lease {
-	__le16 mask;            /* lease type(s) */
-	__le32 duration_ms;     /* lease duration */
-	__le32 seq;
+	__le16 mask;            /* lease type mask (CEPH_LEASE_*) */
+	__le32 duration_ms;     /* lease duration in milliseconds */
+	__le32 seq;             /* lease sequence number */
 } __attribute__ ((packed));
 
 #define CEPH_LEASE_VALID        (1 | 2) /* old and new bit values */
 #define CEPH_LEASE_PRIMARY_LINK 4       /* primary linkage */
 
+/*
+ * Ceph MDS reply directory fragment structure
+ *
+ * Contains information about directory fragment distribution across MDS nodes.
+ * Large directories are split into fragments that can be distributed across
+ * multiple MDS nodes for load balancing and scalability.
+ */
 struct ceph_mds_reply_dirfrag {
-	__le32 frag;            /* fragment */
-	__le32 auth;            /* auth mds, if this is a delegation point */
-	__le32 ndist;           /* number of mds' this is replicated on */
-	__le32 dist[];
+	__le32 frag;            /* directory fragment identifier */
+	__le32 auth;            /* authoritative MDS for this fragment */
+	__le32 ndist;           /* number of MDS nodes this fragment is replicated on */
+	__le32 dist[];          /* array of MDS node IDs holding replicas */
 } __attribute__ ((packed));
 
 #define CEPH_LOCK_FCNTL		1
@@ -614,13 +818,20 @@ struct ceph_mds_reply_dirfrag {
 #define CEPH_LOCK_EXCL     2
 #define CEPH_LOCK_UNLOCK   4
 
+/*
+ * Ceph file lock structure
+ *
+ * Represents advisory file locks (fcntl/flock) used for coordination
+ * between clients accessing the same file. The MDS mediates these locks
+ * across the cluster to ensure consistency.
+ */
 struct ceph_filelock {
-	__le64 start;/* file offset to start lock at */
-	__le64 length; /* num bytes to lock; 0 for all following start */
-	__le64 client; /* which client holds the lock */
-	__le64 owner; /* owner the lock */
-	__le64 pid; /* process id holding the lock on the client */
-	__u8 type; /* shared lock, exclusive lock, or unlock */
+	__le64 start;   /* file byte offset where lock begins */
+	__le64 length;  /* number of bytes to lock (0 = lock to EOF) */
+	__le64 client;  /* client ID that holds the lock */
+	__le64 owner;   /* lock owner identifier (typically file pointer) */
+	__le64 pid;     /* process ID holding the lock on the client */
+	__u8 type;      /* lock type: CEPH_LOCK_SHARED/EXCL/UNLOCK */
 } __attribute__ ((packed));
 
 
@@ -762,53 +973,76 @@ extern const char *ceph_cap_op_name(int op);
 #define CEPH_CLIENT_CAPS_PENDING_CAPSNAP	(1<<2)
 
 /*
- * caps message, used for capability callbacks, acks, requests, etc.
+ * Ceph MDS capability message structure
+ *
+ * This structure represents capability-related messages exchanged between
+ * the MDS and clients. Capabilities grant permissions to perform operations
+ * on inodes and include cached metadata to reduce round trips.
  */
 struct ceph_mds_caps {
-	__le32 op;                  /* CEPH_CAP_OP_* */
-	__le64 ino, realm;
-	__le64 cap_id;
-	__le32 seq, issue_seq;
-	__le32 caps, wanted, dirty; /* latest issued/wanted/dirty */
-	__le32 migrate_seq;
-	__le64 snap_follows;
-	__le32 snap_trace_len;
-
-	/* authlock */
-	__le32 uid, gid, mode;
-
-	/* linklock */
-	__le32 nlink;
-
-	/* xattrlock */
-	__le32 xattr_len;
-	__le64 xattr_version;
-
-	/* a union of non-export and export bodies. */
-	__le64 size, max_size, truncate_size;
-	__le32 truncate_seq;
-	struct ceph_timespec mtime, atime, ctime;
-	struct ceph_file_layout_legacy layout;
-	__le32 time_warp_seq;
+	__le32 op;                  /* capability operation (CEPH_CAP_OP_*) */
+	__le64 ino, realm;          /* inode number and snapshot realm */
+	__le64 cap_id;              /* unique capability identifier */
+	__le32 seq, issue_seq;      /* sequence numbers for ordering */
+	__le32 caps, wanted, dirty; /* capability bits: granted/requested/dirty */
+	__le32 migrate_seq;         /* sequence number for cap migration */
+	__le64 snap_follows;        /* snapshot context this cap follows */
+	__le32 snap_trace_len;      /* length of snapshot trace following */
+
+	/* File ownership and permissions */
+	__le32 uid, gid, mode;      /* owner user/group ID and file mode */
+
+	/* Link count */
+	__le32 nlink;               /* number of hard links to this inode */
+
+	/* Extended attributes */
+	__le32 xattr_len;           /* length of xattr blob */
+	__le64 xattr_version;       /* version of extended attributes */
+
+	/* File data and layout (union for export/non-export operations) */
+	__le64 size, max_size, truncate_size;  /* current/max/truncate file sizes */
+	__le32 truncate_seq;        /* truncate operation sequence number */
+	struct ceph_timespec mtime, atime, ctime;  /* file timestamps */
+	struct ceph_file_layout_legacy layout;     /* file striping layout */
+	__le32 time_warp_seq;       /* sequence for time warp detection */
 } __attribute__ ((packed));
 
+/*
+ * Ceph MDS capability peer information structure
+ *
+ * This structure contains information about a capability at a peer MDS,
+ * used during capability import/export operations when capabilities are
+ * migrated between different MDS nodes.
+ */
 struct ceph_mds_cap_peer {
-	__le64 cap_id;
-	__le32 issue_seq;
-	__le32 mseq;
-	__le32 mds;
-	__u8   flags;
+	__le64 cap_id;		/* capability ID at the peer MDS */
+	__le32 issue_seq;	/* issue sequence number at peer MDS */
+	__le32 mseq;		/* migration sequence number at peer MDS */
+	__le32 mds;		/* MDS number of the peer */
+	__u8   flags;		/* capability flags at peer MDS */
 } __attribute__ ((packed));
 
-/* cap release msg head */
+/*
+ * Ceph MDS capability release message header
+ *
+ * This structure forms the header of a capability release message sent from
+ * client to MDS to inform that the client is releasing (giving up) capabilities
+ * on one or more inodes. The message contains a list of cap_item structures.
+ */
 struct ceph_mds_cap_release {
-	__le32 num;                /* number of cap_items that follow */
+	__le32 num;                /* number of ceph_mds_cap_item entries following */
 } __attribute__ ((packed));
 
+/*
+ * Ceph MDS capability release item
+ *
+ * Represents a single capability being released by the client. Multiple
+ * cap items can be batched together in a single cap release message.
+ */
 struct ceph_mds_cap_item {
-	__le64 ino;
-	__le64 cap_id;
-	__le32 migrate_seq, issue_seq;
+	__le64 ino;                /* inode number of the file */
+	__le64 cap_id;             /* unique capability identifier */
+	__le32 migrate_seq, issue_seq; /* migration and issue sequence numbers */
 } __attribute__ ((packed));
 
 #define CEPH_MDS_LEASE_REVOKE           1  /*    mds  -> client */
@@ -818,42 +1052,68 @@ struct ceph_mds_cap_item {
 
 extern const char *ceph_lease_op_name(int o);
 
-/* lease msg header */
+/*
+ * Ceph MDS lease message structure
+ *
+ * This structure represents directory name lease messages exchanged between
+ * MDS and clients. Directory leases grant clients permission to cache
+ * directory contents and negative dentries to improve performance.
+ */
 struct ceph_mds_lease {
-	__u8 action;            /* CEPH_MDS_LEASE_* */
-	__le16 mask;            /* which lease */
-	__le64 ino;
-	__le64 first, last;     /* snap range */
-	__le32 seq;
-	__le32 duration_ms;     /* duration of renewal */
+	__u8 action;            /* lease action (CEPH_MDS_LEASE_*) */
+	__le16 mask;            /* which lease type is being acted upon */
+	__le64 ino;             /* inode number of parent directory */
+	__le64 first, last;     /* snapshot range for the lease */
+	__le32 seq;             /* lease sequence number for ordering */
+	__le32 duration_ms;     /* lease duration in milliseconds (for renewals) */
 } __attribute__ ((packed));
 /* followed by a __le32+string for dname */
 
-/* client reconnect */
+/*
+ * Ceph MDS capability reconnect structure (version 2)
+ *
+ * Sent during MDS session reconnection to restore capability state
+ * after a session has been lost. This allows the client to inform
+ * the MDS about capabilities it believes it holds.
+ */
 struct ceph_mds_cap_reconnect {
-	__le64 cap_id;
-	__le32 wanted;
-	__le32 issued;
-	__le64 snaprealm;
-	__le64 pathbase;        /* base ino for our path to this ino */
-	__le32 flock_len;       /* size of flock state blob, if any */
+	__le64 cap_id;          /* unique capability identifier */
+	__le32 wanted;          /* capabilities the client wants */
+	__le32 issued;          /* capabilities the client believes are issued */
+	__le64 snaprealm;       /* snapshot realm this inode belongs to */
+	__le64 pathbase;        /* base inode number for path reconstruction */
+	__le32 flock_len;       /* size of file lock state blob following */
 } __attribute__ ((packed));
 /* followed by flock blob */
 
+/*
+ * Ceph MDS capability reconnect structure (version 1)
+ *
+ * Legacy version of the capability reconnect structure used for
+ * backwards compatibility with older MDS versions. Contains
+ * additional file metadata fields not present in version 2.
+ */
 struct ceph_mds_cap_reconnect_v1 {
-	__le64 cap_id;
-	__le32 wanted;
-	__le32 issued;
-	__le64 size;
-	struct ceph_timespec mtime, atime;
-	__le64 snaprealm;
-	__le64 pathbase;        /* base ino for our path to this ino */
+	__le64 cap_id;          /* unique capability identifier */
+	__le32 wanted;          /* capabilities the client wants */
+	__le32 issued;          /* capabilities the client believes are issued */
+	__le64 size;            /* file size */
+	struct ceph_timespec mtime, atime; /* file modification and access times */
+	__le64 snaprealm;       /* snapshot realm this inode belongs to */
+	__le64 pathbase;        /* base inode number for path reconstruction */
 } __attribute__ ((packed));
 
+/*
+ * Ceph MDS snapshot realm reconnect structure
+ *
+ * Sent during MDS session reconnection to restore snapshot realm
+ * hierarchy information. This helps the MDS reconstruct the client's
+ * view of snapshot realms after a session interruption.
+ */
 struct ceph_mds_snaprealm_reconnect {
-	__le64 ino;     /* snap realm base */
-	__le64 seq;     /* snap seq for this snap realm */
-	__le64 parent;  /* parent realm */
+	__le64 ino;     /* inode number of snapshot realm root directory */
+	__le64 seq;     /* sequence number of this snapshot realm */
+	__le64 parent;  /* inode number of parent snapshot realm */
 } __attribute__ ((packed));
 
 /*
@@ -868,44 +1128,56 @@ enum {
 
 extern const char *ceph_snap_op_name(int o);
 
-/* snap msg header */
+/*
+ * Ceph MDS snapshot message header
+ *
+ * This structure forms the header for snapshot-related messages from the MDS,
+ * containing operation type and metadata about snapshot realm operations.
+ */
 struct ceph_mds_snap_head {
-	__le32 op;                /* CEPH_SNAP_OP_* */
-	__le64 split;             /* ino to split off, if any */
-	__le32 num_split_inos;    /* # inos belonging to new child realm */
-	__le32 num_split_realms;  /* # child realms udner new child realm */
-	__le32 trace_len;         /* size of snap trace blob */
+	__le32 op;                /* snapshot operation type (CEPH_SNAP_OP_*) */
+	__le64 split;             /* inode number to split off into new realm */
+	__le32 num_split_inos;    /* number of inodes belonging to new child realm */
+	__le32 num_split_realms;  /* number of child realms under new child realm */
+	__le32 trace_len;         /* size of the snapshot trace blob following */
 } __attribute__ ((packed));
 /* followed by split ino list, then split realms, then the trace blob */
 
 /*
- * encode info about a snaprealm, as viewed by a client
+ * Ceph MDS snapshot realm information structure
+ *
+ * Encodes information about a snapshot realm as viewed by a client.
+ * A snapshot realm represents a subtree of the filesystem that shares
+ * the same snapshot history and can be snapshotted as a unit.
  */
 struct ceph_mds_snap_realm {
-	__le64 ino;           /* ino */
-	__le64 created;       /* snap: when created */
-	__le64 parent;        /* ino: parent realm */
-	__le64 parent_since;  /* snap: same parent since */
-	__le64 seq;           /* snap: version */
-	__le32 num_snaps;
-	__le32 num_prior_parent_snaps;
+	__le64 ino;           /* inode number of the realm root directory */
+	__le64 created;       /* snapshot ID when this realm was created */
+	__le64 parent;        /* inode number of parent realm (0 if root) */
+	__le64 parent_since;  /* snapshot ID since realm had same parent */
+	__le64 seq;           /* sequence number for realm version/updates */
+	__le32 num_snaps;     /* number of snapshots in this realm */
+	__le32 num_prior_parent_snaps; /* number of parent snapshots before split */
 } __attribute__ ((packed));
 /* followed by my snap list, then prior parent snap list */
 
 /*
- * quotas
+ * Ceph MDS quota information structure
+ *
+ * This structure represents quota-related metadata sent from the MDS
+ * to update directory quota limits and current usage statistics.
  */
 struct ceph_mds_quota {
-	__le64 ino;		/* ino */
-	struct ceph_timespec rctime;
-	__le64 rbytes;		/* dir stats */
-	__le64 rfiles;
-	__le64 rsubdirs;
-	__u8 struct_v;		/* compat */
-	__u8 struct_compat;
-	__le32 struct_len;
-	__le64 max_bytes;	/* quota max. bytes */
-	__le64 max_files;	/* quota max. files */
+	__le64 ino;			/* inode number of the directory */
+	struct ceph_timespec rctime;	/* recursive change time */
+	__le64 rbytes;			/* recursive bytes used in directory tree */
+	__le64 rfiles;			/* recursive file count in directory tree */
+	__le64 rsubdirs;		/* recursive subdirectory count */
+	__u8 struct_v;			/* structure version for compatibility */
+	__u8 struct_compat;		/* compatibility version */
+	__le32 struct_len;		/* length of this structure */
+	__le64 max_bytes;		/* quota limit: maximum bytes allowed */
+	__le64 max_files;		/* quota limit: maximum files allowed */
 } __attribute__ ((packed));
 
 #endif
-- 
2.51.0

[RFC PATCH 07/20] ceph: add comments in ceph_hash.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for constant and method declarations
in /include/linux/ceph/ceph_hash.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/ceph_hash.h | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/include/linux/ceph/ceph_hash.h b/include/linux/ceph/ceph_hash.h
index fda474c7a5d6..8ea203f6fbfa 100644
--- a/include/linux/ceph/ceph_hash.h
+++ b/include/linux/ceph/ceph_hash.h
@@ -2,13 +2,30 @@
 #ifndef FS_CEPH_HASH_H
 #define FS_CEPH_HASH_H
 
-#define CEPH_STR_HASH_LINUX      0x1  /* linux dcache hash */
-#define CEPH_STR_HASH_RJENKINS   0x2  /* robert jenkins' */
+/*
+ * String hashing algorithm type constants used for Ceph directory layout hashing.
+ * These determine how directory entries are distributed across metadata servers.
+ */
+/* Linux dcache hash algorithm - matches kernel dcache string hashing */
+#define CEPH_STR_HASH_LINUX      0x1
+/* Robert Jenkins' hash algorithm - provides good distribution properties */
+#define CEPH_STR_HASH_RJENKINS   0x2
 
+/*
+ * String hashing function interfaces for Ceph filesystem operations.
+ * Used primarily for consistent directory entry placement across MDS nodes.
+ */
+
+/* Compute Linux dcache-style hash of a string */
 extern unsigned ceph_str_hash_linux(const char *s, unsigned len);
+
+/* Compute Robert Jenkins hash of a string */
 extern unsigned ceph_str_hash_rjenkins(const char *s, unsigned len);
 
+/* Generic hash function dispatcher - calls appropriate algorithm based on type */
 extern unsigned ceph_str_hash(int type, const char *s, unsigned len);
+
+/* Get human-readable name for a hash algorithm type */
 extern const char *ceph_str_hash_name(int type);
 
 #endif
-- 
2.51.0

[RFC PATCH 08/20] ceph: add comments to metadata structures in cls_lock_client.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for enum ceph_cls_lock_type,
struct ceph_locker_id, struct ceph_locker_info,
struct ceph_locker in /include/linux/ceph/cls_lock_client.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/cls_lock_client.h | 34 +++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/include/linux/ceph/cls_lock_client.h b/include/linux/ceph/cls_lock_client.h
index 17bc7584d1fe..8eae9f6ee8b6 100644
--- a/include/linux/ceph/cls_lock_client.h
+++ b/include/linux/ceph/cls_lock_client.h
@@ -4,23 +4,51 @@
 
 #include <linux/ceph/osd_client.h>
 
+/*
+ * Object class lock types: Defines the types of locks that can be acquired
+ * on RADOS objects through the lock object class. Supports both exclusive
+ * and shared locking semantics for distributed coordination.
+ */
 enum ceph_cls_lock_type {
+	/* No lock held */
 	CEPH_CLS_LOCK_NONE = 0,
+	/* Exclusive lock - only one holder allowed */
 	CEPH_CLS_LOCK_EXCLUSIVE = 1,
+	/* Shared lock - multiple readers allowed */
 	CEPH_CLS_LOCK_SHARED = 2,
 };
 
+/*
+ * Lock holder identifier metadata: Uniquely identifies a client that holds
+ * or is requesting a lock on a RADOS object. Combines client entity name
+ * with a session-specific cookie for disambiguation.
+ */
 struct ceph_locker_id {
-	struct ceph_entity_name name;	/* locker's client name */
-	char *cookie;			/* locker's cookie */
+	/* Client entity name (type and number) */
+	struct ceph_entity_name name;
+	/* Unique session cookie for this lock holder */
+	char *cookie;
 };
 
+/*
+ * Lock holder information metadata: Contains additional information about
+ * a lock holder, primarily the network address for client identification
+ * and potential communication.
+ */
 struct ceph_locker_info {
-	struct ceph_entity_addr addr;	/* locker's address */
+	/* Network address of the lock holder */
+	struct ceph_entity_addr addr;
 };
 
+/*
+ * Complete lock holder metadata: Combines lock holder identification and
+ * network information into a complete description of a client that holds
+ * a lock on a RADOS object. Used for lock enumeration and management.
+ */
 struct ceph_locker {
+	/* Lock holder identification (name + cookie) */
 	struct ceph_locker_id id;
+	/* Lock holder network information */
 	struct ceph_locker_info info;
 };
 
-- 
2.51.0

[RFC PATCH 09/20] ceph: add comments to metadata structures in libceph.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_options,
struct ceph_client, struct ceph_snap_context
in /include/linux/ceph/libceph.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/libceph.h | 50 ++++++++++++++++++++++++++++++++----
 1 file changed, 45 insertions(+), 5 deletions(-)

diff --git a/include/linux/ceph/libceph.h b/include/linux/ceph/libceph.h
index 733e7f93db66..f7edef4fcc54 100644
--- a/include/linux/ceph/libceph.h
+++ b/include/linux/ceph/libceph.h
@@ -44,15 +44,29 @@
 #define ceph_test_opt(client, opt) \
 	(!!((client)->options->flags & CEPH_OPT_##opt))
 
+/*
+ * Ceph client options metadata: Configuration parameters for connecting to
+ * and operating with a Ceph cluster. Contains network settings, timeouts,
+ * authentication details, and cluster topology information.
+ */
 struct ceph_options {
+	/* Feature and behavior flags (CEPH_OPT_*) */
 	int flags;
+	/* Cluster filesystem identifier */
 	struct ceph_fsid fsid;
+	/* Client's network address */
 	struct ceph_entity_addr my_addr;
+	/* Timeout for initial cluster connection */
 	unsigned long mount_timeout;		/* jiffies */
+	/* How long to keep idle OSD connections */
 	unsigned long osd_idle_ttl;		/* jiffies */
+	/* OSD keepalive message interval */
 	unsigned long osd_keepalive_timeout;	/* jiffies */
+	/* Timeout for OSD requests (0 = no timeout) */
 	unsigned long osd_request_timeout;	/* jiffies */
+	/* Read from replica policy flags */
 	u32 read_from_replica;  /* CEPH_OSD_FLAG_BALANCE/LOCALIZE_READS */
+	/* Connection modes for msgr1/msgr2 protocols */
 	int con_modes[2];  /* CEPH_CON_MODE_* */
 
 	/*
@@ -61,11 +75,16 @@ struct ceph_options {
 	 * ceph_compare_options() should be updated accordingly
 	 */
 
+	/* Array of monitor addresses */
 	struct ceph_entity_addr *mon_addr; /* should be the first
 					      pointer type of args */
+	/* Number of monitors configured */
 	int num_mon;
+	/* Client authentication name */
 	char *name;
+	/* Authentication key */
 	struct ceph_crypto_key *key;
+	/* CRUSH map location constraints */
 	struct rb_root crush_locs;
 };
 
@@ -109,31 +128,46 @@ struct ceph_mds_client;
 /*
  * per client state
  *
- * possibly shared by multiple mount points, if they are
- * mounting the same ceph filesystem/cluster.
+ * Ceph client state metadata: Central state for a connection to a Ceph cluster.
+ * Manages authentication, messaging, and communication with monitors and OSDs.
+ * Can be shared by multiple mount points accessing the same cluster.
  */
 struct ceph_client {
+	/* Cluster filesystem identifier */
 	struct ceph_fsid fsid;
+	/* Whether we have received the cluster FSID */
 	bool have_fsid;
 
+	/* Private data for specific client types (RBD, CephFS, etc.) */
 	void *private;
 
+	/* Client configuration options */
 	struct ceph_options *options;
 
-	struct mutex mount_mutex;      /* serialize mount attempts */
+	/* Serializes mount and authentication attempts */
+	struct mutex mount_mutex;
+	/* Wait queue for authentication completion */
 	wait_queue_head_t auth_wq;
+	/* Latest authentication error code */
 	int auth_err;
 
+	/* Optional callback for extra monitor message handling */
 	int (*extra_mon_dispatch)(struct ceph_client *, struct ceph_msg *);
 
+	/* Feature flags supported by this client */
 	u64 supported_features;
+	/* Feature flags required by this client */
 	u64 required_features;
 
+	/* Network messaging subsystem */
 	struct ceph_messenger msgr;   /* messenger instance */
+	/* Monitor client for cluster map updates */
 	struct ceph_mon_client monc;
+	/* OSD client for data operations */
 	struct ceph_osd_client osdc;
 
 #ifdef CONFIG_DEBUG_FS
+	/* Debug filesystem entries */
 	struct dentry *debugfs_dir;
 	struct dentry *debugfs_monmap;
 	struct dentry *debugfs_osdmap;
@@ -153,17 +187,23 @@ static inline bool ceph_msgr2(struct ceph_client *client)
  */
 
 /*
- * A "snap context" is the set of existing snapshots when we
- * write data.  It is used by the OSD to guide its COW behavior.
+ * Snapshot context metadata: Represents the set of existing snapshots at the
+ * time data was written. Used by OSDs to guide copy-on-write (COW) behavior
+ * and ensure snapshot consistency. Reference-counted and attached to dirty
+ * pages to track the snapshot state when data was dirtied.
  *
  * The ceph_snap_context is refcounted, and attached to each dirty
  * page, indicating which context the dirty data belonged when it was
  * dirtied.
  */
 struct ceph_snap_context {
+	/* Reference count for safe sharing */
 	refcount_t nref;
+	/* Snapshot sequence number */
 	u64 seq;
+	/* Number of snapshots in the array */
 	u32 num_snaps;
+	/* Array of snapshot IDs (variable length) */
 	u64 snaps[];
 };
 
-- 
2.51.0

[RFC PATCH 10/20] ceph: add comments to metadata structures in messenger.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_connection_operations,
struct ceph_messenger, enum ceph_msg_data_type,
struct ceph_bio_iter, struct ceph_bvec_iter, struct ceph_msg_data,
struct ceph_msg_data_cursor, struct ceph_msg,
struct ceph_connection_v1_info, struct ceph_frame_desc,
struct ceph_gcm_nonce, struct ceph_connection_v2_info,
struct ceph_connection in /include/linux/ceph/messenger.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/messenger.h | 449 ++++++++++++++++++++++++---------
 1 file changed, 332 insertions(+), 117 deletions(-)

diff --git a/include/linux/ceph/messenger.h b/include/linux/ceph/messenger.h
index 1717cc57cdac..d0573b228d4e 100644
--- a/include/linux/ceph/messenger.h
+++ b/include/linux/ceph/messenger.h
@@ -20,53 +20,70 @@ struct ceph_connection;
 struct ceph_msg_data_cursor;
 
 /*
- * Ceph defines these callbacks for handling connection events.
+ * Connection operations metadata: Callback interface for handling network
+ * connection events and message processing. Allows different Ceph subsystems
+ * (monitors, OSDs, MDS) to customize connection behavior.
  */
 struct ceph_connection_operations {
+	/* Connection reference management */
 	struct ceph_connection *(*get)(struct ceph_connection *);
 	void (*put)(struct ceph_connection *);
 
-	/* handle an incoming message. */
+	/* Handle incoming message dispatch to appropriate handler */
 	void (*dispatch) (struct ceph_connection *con, struct ceph_msg *m);
 
-	/* authorize an outgoing connection */
+	/* Authentication and authorization callbacks */
+	/* Get authorizer for outgoing connection */
 	struct ceph_auth_handshake *(*get_authorizer) (
 				struct ceph_connection *con,
 			       int *proto, int force_new);
+	/* Handle authentication challenge */
 	int (*add_authorizer_challenge)(struct ceph_connection *con,
 					void *challenge_buf,
 					int challenge_buf_len);
+	/* Verify authorizer reply */
 	int (*verify_authorizer_reply) (struct ceph_connection *con);
+	/* Invalidate current authorizer */
 	int (*invalidate_authorizer)(struct ceph_connection *con);
 
-	/* there was some error on the socket (disconnect, whatever) */
+	/* Network error handling */
+	/* Socket error occurred (disconnect, etc.) */
 	void (*fault) (struct ceph_connection *con);
 
+	/* Peer reset connection, potential message loss */
 	/* a remote host as terminated a message exchange session, and messages
 	 * we sent (or they tried to send us) may be lost. */
 	void (*peer_reset) (struct ceph_connection *con);
 
+	/* Message allocation and processing */
+	/* Allocate message for incoming data */
 	struct ceph_msg * (*alloc_msg) (struct ceph_connection *con,
 					struct ceph_msg_header *hdr,
 					int *skip);
 
+	/* Re-encode message for retransmission */
 	void (*reencode_message) (struct ceph_msg *msg);
 
+	/* Message signing and verification */
 	int (*sign_message) (struct ceph_msg *msg);
 	int (*check_message_signature) (struct ceph_msg *msg);
 
-	/* msgr2 authentication exchange */
+	/* Messenger v2 authentication exchange */
+	/* Get initial authentication request */
 	int (*get_auth_request)(struct ceph_connection *con,
 				void *buf, int *buf_len,
 				void **authorizer, int *authorizer_len);
+	/* Handle multi-round authentication */
 	int (*handle_auth_reply_more)(struct ceph_connection *con,
 				      void *reply, int reply_len,
 				      void *buf, int *buf_len,
 				      void **authorizer, int *authorizer_len);
+	/* Authentication completed successfully */
 	int (*handle_auth_done)(struct ceph_connection *con,
 				u64 global_id, void *reply, int reply_len,
 				u8 *session_key, int *session_key_len,
 				u8 *con_secret, int *con_secret_len);
+	/* Authentication failed with unsupported method */
 	int (*handle_auth_bad_method)(struct ceph_connection *con,
 				      int used_proto, int result,
 				      const int *allowed_protos, int proto_cnt,
@@ -100,21 +117,37 @@ struct ceph_connection_operations {
 /* use format string %s%lld */
 #define ENTITY_NAME(n) ceph_entity_type_name((n).type), le64_to_cpu((n).num)
 
+/*
+ * Ceph messenger metadata: Core messaging infrastructure that manages network
+ * connections and message routing. Handles connection multiplexing, sequencing,
+ * and provides the foundation for all Ceph network communication.
+ */
 struct ceph_messenger {
-	struct ceph_entity_inst inst;    /* my name+address */
+	/* Messenger identity (entity name + network address) */
+	struct ceph_entity_inst inst;
+	/* Encoded network address for this messenger */
 	struct ceph_entity_addr my_enc_addr;
 
+	/* Shutdown coordination */
 	atomic_t stopping;
+	/* Network namespace for socket operations */
 	possible_net_t net;
 
 	/*
+	 * Global connection sequence number for race disambiguation:
 	 * the global_seq counts connections i (attempt to) initiate
 	 * in order to disambiguate certain connect race conditions.
 	 */
 	u32 global_seq;
+	/* Protects global_seq updates */
 	spinlock_t global_seq_lock;
 };
 
+/*
+ * Message data container types: Defines different ways message payload data
+ * can be stored and transmitted. Supports various kernel memory management
+ * patterns for efficient zero-copy I/O operations.
+ */
 enum ceph_msg_data_type {
 	CEPH_MSG_DATA_NONE,	/* message contains no data payload */
 	CEPH_MSG_DATA_PAGES,	/* data source/destination is a page array */
@@ -128,8 +161,15 @@ enum ceph_msg_data_type {
 
 #ifdef CONFIG_BLOCK
 
+/*
+ * Bio iterator metadata: Tracks position within a chain of bio structures
+ * for efficient traversal during network I/O operations. Maintains current
+ * bio and position within that bio's vector array.
+ */
 struct ceph_bio_iter {
+	/* Current bio in the chain */
 	struct bio *bio;
+	/* Current position within the bio */
 	struct bvec_iter iter;
 };
 
@@ -172,8 +212,15 @@ struct ceph_bio_iter {
 
 #endif /* CONFIG_BLOCK */
 
+/*
+ * Bio vector iterator metadata: Tracks position within an array of bio_vec
+ * structures for efficient memory region traversal during network operations.
+ * Provides unified interface for vectored I/O.
+ */
 struct ceph_bvec_iter {
+	/* Array of bio vectors */
 	struct bio_vec *bvecs;
+	/* Current position within the array */
 	struct bvec_iter iter;
 };
 
@@ -208,84 +255,151 @@ struct ceph_bvec_iter {
 	(it)->iter.bi_size = (n);					      \
 } while (0)
 
+/*
+ * Message data container metadata: Flexible container for message payload data
+ * using different storage methods. Supports various kernel memory management
+ * patterns for efficient zero-copy network operations.
+ */
 struct ceph_msg_data {
+	/* Type of data container */
 	enum ceph_msg_data_type		type;
+	/* Type-specific data container */
 	union {
 #ifdef CONFIG_BLOCK
+		/* Block I/O bio container */
 		struct {
+			/* Bio chain position and iterator */
 			struct ceph_bio_iter	bio_pos;
+			/* Total data length in bio chain */
 			u32			bio_length;
 		};
 #endif /* CONFIG_BLOCK */
+		/* Bio vector array container */
 		struct ceph_bvec_iter	bvec_pos;
+		/* Page array container */
 		struct {
+			/* Array of page pointers */
 			struct page	**pages;
-			size_t		length;		/* total # bytes */
-			unsigned int	alignment;	/* first page */
+			/* Total data length in bytes */
+			size_t		length;
+			/* Alignment offset in first page */
+			unsigned int	alignment;
+			/* Whether we own and must free the pages */
 			bool		own_pages;
 		};
+		/* Pagelist container */
 		struct ceph_pagelist	*pagelist;
+		/* Generic iterator container */
 		struct iov_iter		iter;
 	};
 };
 
+/*
+ * Message data cursor metadata: Tracks progress through message data during
+ * network transmission or reception. Maintains position across multiple data
+ * items and handles different container types efficiently.
+ */
 struct ceph_msg_data_cursor {
-	size_t			total_resid;	/* across all data items */
-
-	struct ceph_msg_data	*data;		/* current data item */
-	size_t			resid;		/* bytes not yet consumed */
-	int			sr_resid;	/* residual sparse_read len */
-	bool			need_crc;	/* crc update needed */
+	/* Total bytes remaining across all data items */
+	size_t			total_resid;
+
+	/* Current data item being processed */
+	struct ceph_msg_data	*data;
+	/* Bytes remaining in current data item */
+	size_t			resid;
+	/* Residual sparse read length */
+	int			sr_resid;
+	/* Whether CRC calculation is needed */
+	bool			need_crc;
+	/* Type-specific position tracking */
 	union {
 #ifdef CONFIG_BLOCK
+		/* Bio iterator for block I/O */
 		struct ceph_bio_iter	bio_iter;
 #endif /* CONFIG_BLOCK */
+		/* Bio vector iterator */
 		struct bvec_iter	bvec_iter;
-		struct {				/* pages */
-			unsigned int	page_offset;	/* offset in page */
-			unsigned short	page_index;	/* index in array */
-			unsigned short	page_count;	/* pages in array */
+		/* Page array position tracking */
+		struct {
+			/* Byte offset within current page */
+			unsigned int	page_offset;
+			/* Current page index in array */
+			unsigned short	page_index;
+			/* Total pages in array */
+			unsigned short	page_count;
 		};
-		struct {				/* pagelist */
-			struct page	*page;		/* page from list */
-			size_t		offset;		/* bytes from list */
+		/* Pagelist position tracking */
+		struct {
+			/* Current page from pagelist */
+			struct page	*page;
+			/* Byte offset from start of pagelist */
+			size_t		offset;
 		};
+		/* Iterator position tracking */
 		struct {
+			/* Current iov_iter state */
 			struct iov_iter		iov_iter;
+			/* Length of last operation */
 			unsigned int		lastlen;
 		};
 	};
 };
 
 /*
+ * Ceph network message metadata: Complete network message structure containing
+ * header, payload data, and transmission state. Supports various data container
+ * types for efficient zero-copy operations and handles message lifecycle.
+ *
  * a single message.  it contains a header (src, dest, message type, etc.),
  * footer (crc values, mainly), a "front" message body, and possibly a
  * data payload (stored in some number of pages).
  */
 struct ceph_msg {
-	struct ceph_msg_header hdr;	/* header */
+	/* Message header with routing and type information */
+	struct ceph_msg_header hdr;
+	/* Message footer with CRC and other metadata */
 	union {
-		struct ceph_msg_footer footer;		/* footer */
-		struct ceph_msg_footer_old old_footer;	/* old format footer */
+		/* Current footer format */
+		struct ceph_msg_footer footer;
+		/* Legacy footer format for compatibility */
+		struct ceph_msg_footer_old old_footer;
 	};
-	struct kvec front;              /* unaligned blobs of message */
+	/* Front payload (small, inline message data) */
+	struct kvec front;
+	/* Middle payload (optional, variable-length) */
 	struct ceph_buffer *middle;
 
+	/* Data payload information */
+	/* Total length of all data items */
 	size_t				data_length;
+	/* Array of data containers */
 	struct ceph_msg_data		*data;
+	/* Current number of data items */
 	int				num_data_items;
+	/* Maximum data items allocated */
 	int				max_data_items;
+	/* Current position for data processing */
 	struct ceph_msg_data_cursor	cursor;
 
+	/* Connection and list management */
+	/* Connection this message belongs to */
 	struct ceph_connection *con;
-	struct list_head list_head;	/* links for connection lists */
+	/* Linkage for connection message queues */
+	struct list_head list_head;
 
+	/* Message lifecycle and state */
+	/* Reference counting for safe cleanup */
 	struct kref kref;
+	/* More messages follow this one */
 	bool more_to_follow;
+	/* Message needs output sequence number */
 	bool needs_out_seq;
+	/* Total bytes expected for sparse read */
 	u64 sparse_read_total;
+	/* Allocated length of front buffer */
 	int front_alloc_len;
 
+	/* Memory pool this message came from */
 	struct ceph_msgpool *pool;
 };
 
@@ -321,45 +435,75 @@ struct ceph_msg {
 #define BASE_DELAY_INTERVAL	(HZ / 4)
 #define MAX_DELAY_INTERVAL	(15 * HZ)
 
+/*
+ * Messenger v1 connection info metadata: Protocol-specific state for messenger
+ * version 1 connections. Handles legacy wire protocol, authentication handshake,
+ * and connection negotiation with older Ceph versions.
+ */
 struct ceph_connection_v1_info {
-	struct kvec out_kvec[8],         /* sending header/footer data */
-		*out_kvec_cur;
-	int out_kvec_left;   /* kvec's left in out_kvec */
-	int out_skip;        /* skip this many bytes */
-	int out_kvec_bytes;  /* total bytes left */
-	bool out_more;       /* there is more data after the kvecs */
+	/* Output vector management for sending */
+	/* Array of vectors for header/footer data */
+	struct kvec out_kvec[8], *out_kvec_cur;
+	/* Number of kvecs remaining to send */
+	int out_kvec_left;
+	/* Bytes to skip in current operation */
+	int out_skip;
+	/* Total bytes left in kvec array */
+	int out_kvec_bytes;
+	/* More data follows the kvecs */
+	bool out_more;
+	/* Current message send complete */
 	bool out_msg_done;
 
+	/* Authentication state */
+	/* Current authentication handshake */
 	struct ceph_auth_handshake *auth;
+	/* Need to retry authentication */
 	int auth_retry;       /* true if we need a newer authorizer */
 
-	/* connection negotiation temps */
+	/* Connection negotiation temporary storage */
+	/* Received protocol banner */
 	u8 in_banner[CEPH_BANNER_MAX_LEN];
+	/* Peer's actual network address */
 	struct ceph_entity_addr actual_peer_addr;
+	/* Address peer should use for us */
 	struct ceph_entity_addr peer_addr_for_me;
+	/* Our outgoing connection message */
 	struct ceph_msg_connect out_connect;
+	/* Peer's connection reply */
 	struct ceph_msg_connect_reply in_reply;
 
+	/* Input stream position tracking */
 	int in_base_pos;     /* bytes read */
 
-	/* sparse reads */
+	/* Sparse read support */
+	/* Current receive vector for sparse data */
 	struct kvec in_sr_kvec; /* current location to receive into */
+	/* Length of current sparse extent */
 	u64 in_sr_len;		/* amount of data in this extent */
 
-	/* message in temps */
-	u8 in_tag;           /* protocol control byte */
+	/* Incoming message temporary storage */
+	/* Protocol control byte */
+	u8 in_tag;
+	/* Incoming message header */
 	struct ceph_msg_header in_hdr;
-	__le64 in_temp_ack;  /* for reading an ack */
+	/* Temporary acknowledgment storage */
+	__le64 in_temp_ack;
 
-	/* message out temps */
+	/* Outgoing message temporary storage */
+	/* Outgoing message header */
 	struct ceph_msg_header out_hdr;
-	__le64 out_temp_ack;  /* for writing an ack */
-	struct ceph_timespec out_temp_keepalive2;  /* for writing keepalive2
-						      stamp */
+	/* Temporary acknowledgment for sending */
+	__le64 out_temp_ack;
+	/* Keepalive timestamp */
+	struct ceph_timespec out_temp_keepalive2;
 
+	/* Connection sequence tracking */
+	/* Our connection attempt sequence */
 	u32 connect_seq;      /* identify the most recent connection
 				 attempt for this session */
-	u32 peer_global_seq;  /* peer's global seq for this connection */
+	/* Peer's global sequence for this connection */
+	u32 peer_global_seq;
 };
 
 #define CEPH_CRC_LEN			4
@@ -379,88 +523,126 @@ struct ceph_connection_v1_info {
 
 #define CEPH_FRAME_MAX_SEGMENT_COUNT	4
 
+/*
+ * Frame descriptor metadata: Describes the structure of a messenger v2 frame
+ * including segment count, lengths, and alignment requirements. Used for
+ * efficient frame parsing and construction.
+ */
 struct ceph_frame_desc {
-	int fd_tag;  /* FRAME_TAG_* */
+	/* Frame type tag identifier */
+	int fd_tag;
+	/* Number of segments in this frame */
 	int fd_seg_cnt;
-	int fd_lens[CEPH_FRAME_MAX_SEGMENT_COUNT];  /* logical */
+	/* Logical length of each segment */
+	int fd_lens[CEPH_FRAME_MAX_SEGMENT_COUNT];
+	/* Alignment requirements for each segment */
 	int fd_aligns[CEPH_FRAME_MAX_SEGMENT_COUNT];
 };
 
+/*
+ * GCM nonce metadata: Nonce structure for AES-GCM encryption in messenger v2.
+ * Combines a fixed portion with an incrementing counter for cryptographic
+ * uniqueness across encrypted frames.
+ */
 struct ceph_gcm_nonce {
+	/* Fixed portion of the nonce */
 	__le32 fixed;
+	/* Incrementing counter portion */
 	__le64 counter __packed;
 };
 
+/*
+ * Ceph connection version 2 protocol state
+ *
+ * Contains all state information specific to the Ceph messenger v2 protocol.
+ * Version 2 adds significant security enhancements including on-wire encryption,
+ * authentication signatures, and secure session establishment over v1.
+ */
 struct ceph_connection_v2_info {
-	struct iov_iter in_iter;
-	struct kvec in_kvecs[5];  /* recvmsg */
-	struct bio_vec in_bvec;  /* recvmsg (in_cursor) */
-	int in_kvec_cnt;
-	int in_state;  /* IN_S_* */
-
-	struct iov_iter out_iter;
-	struct kvec out_kvecs[8];  /* sendmsg */
-	struct bio_vec out_bvec;  /* sendpage (out_cursor, out_zero),
-				     sendmsg (out_enc_pages) */
-	int out_kvec_cnt;
-	int out_state;  /* OUT_S_* */
-
-	int out_zero;  /* # of zero bytes to send */
-	bool out_iter_sendpage;  /* use sendpage if possible */
-
-	struct ceph_frame_desc in_desc;
-	struct ceph_msg_data_cursor in_cursor;
-	struct ceph_msg_data_cursor out_cursor;
-
-	struct crypto_shash *hmac_tfm;  /* post-auth signature */
-	struct crypto_aead *gcm_tfm;  /* on-wire encryption */
-	struct aead_request *gcm_req;
-	struct crypto_wait gcm_wait;
-	struct ceph_gcm_nonce in_gcm_nonce;
-	struct ceph_gcm_nonce out_gcm_nonce;
-
-	struct page **in_enc_pages;
-	int in_enc_page_cnt;
-	int in_enc_resid;
-	int in_enc_i;
-	struct page **out_enc_pages;
-	int out_enc_page_cnt;
-	int out_enc_resid;
-	int out_enc_i;
-
-	int con_mode;  /* CEPH_CON_MODE_* */
-
-	void *conn_bufs[16];
-	int conn_buf_cnt;
-	int data_len_remain;
-
-	struct kvec in_sign_kvecs[8];
-	struct kvec out_sign_kvecs[8];
-	int in_sign_kvec_cnt;
-	int out_sign_kvec_cnt;
-
-	u64 client_cookie;
-	u64 server_cookie;
-	u64 global_seq;
-	u64 connect_seq;
-	u64 peer_global_seq;
-
-	u8 in_buf[CEPH_PREAMBLE_SECURE_LEN];
-	u8 out_buf[CEPH_PREAMBLE_SECURE_LEN];
+	/* Incoming message processing state */
+	struct iov_iter in_iter;                /* iterator for incoming data */
+	struct kvec in_kvecs[5];                /* scatter-gather vectors for recvmsg */
+	struct bio_vec in_bvec;                 /* bio vector for cursor-based receives */
+	int in_kvec_cnt;                        /* number of active input kvecs */
+	int in_state;                           /* current input state (IN_S_*) */
+
+	/* Outgoing message processing state */
+	struct iov_iter out_iter;               /* iterator for outgoing data */
+	struct kvec out_kvecs[8];               /* scatter-gather vectors for sendmsg */
+	struct bio_vec out_bvec;                /* bio vector for cursor/zero sends */
+	int out_kvec_cnt;                       /* number of active output kvecs */
+	int out_state;                          /* current output state (OUT_S_*) */
+
+	int out_zero;                           /* number of zero bytes to send */
+	bool out_iter_sendpage;                 /* use sendpage optimization when possible */
+
+	/* Message data handling */
+	struct ceph_frame_desc in_desc;         /* incoming frame descriptor */
+	struct ceph_msg_data_cursor in_cursor;  /* cursor for incoming message data */
+	struct ceph_msg_data_cursor out_cursor; /* cursor for outgoing message data */
+
+	/* Cryptographic subsystem for v2 security features */
+	struct crypto_shash *hmac_tfm;          /* HMAC transform for post-auth signatures */
+	struct crypto_aead *gcm_tfm;            /* AES-GCM transform for wire encryption */
+	struct aead_request *gcm_req;           /* GCM request structure */
+	struct crypto_wait gcm_wait;            /* wait queue for crypto operations */
+	struct ceph_gcm_nonce in_gcm_nonce;     /* GCM nonce for incoming data */
+	struct ceph_gcm_nonce out_gcm_nonce;    /* GCM nonce for outgoing data */
+
+	/* Encrypted data page management */
+	struct page **in_enc_pages;             /* pages for incoming encrypted data */
+	int in_enc_page_cnt;                    /* number of incoming encrypted pages */
+	int in_enc_resid;                       /* remaining bytes in incoming encryption */
+	int in_enc_i;                           /* current incoming encryption page index */
+	struct page **out_enc_pages;            /* pages for outgoing encrypted data */
+	int out_enc_page_cnt;                   /* number of outgoing encrypted pages */
+	int out_enc_resid;                      /* remaining bytes in outgoing encryption */
+	int out_enc_i;                          /* current outgoing encryption page index */
+
+	int con_mode;                           /* connection mode (CEPH_CON_MODE_*) */
+
+	/* Connection buffer management */
+	void *conn_bufs[16];                    /* connection-specific buffers */
+	int conn_buf_cnt;                       /* number of active connection buffers */
+	int data_len_remain;                    /* remaining data length to process */
+
+	/* Signature generation vectors */
+	struct kvec in_sign_kvecs[8];           /* vectors for incoming signature calculation */
+	struct kvec out_sign_kvecs[8];          /* vectors for outgoing signature calculation */
+	int in_sign_kvec_cnt;                   /* number of incoming signature vectors */
+	int out_sign_kvec_cnt;                  /* number of outgoing signature vectors */
+
+	/* Session and sequence management */
+	u64 client_cookie;                      /* client session cookie */
+	u64 server_cookie;                      /* server session cookie */
+	u64 global_seq;                         /* global sequence number */
+	u64 connect_seq;                        /* connection sequence number */
+	u64 peer_global_seq;                    /* peer's global sequence number */
+
+	/* Protocol buffers */
+	u8 in_buf[CEPH_PREAMBLE_SECURE_LEN];    /* buffer for incoming preambles */
+	u8 out_buf[CEPH_PREAMBLE_SECURE_LEN];   /* buffer for outgoing preambles */
+
+	/* Frame epilogue for integrity checking */
 	struct {
-		u8 late_status;  /* FRAME_LATE_STATUS_* */
+		u8 late_status;                 /* late frame status (FRAME_LATE_STATUS_*) */
 		union {
 			struct {
-				u32 front_crc;
-				u32 middle_crc;
-				u32 data_crc;
+				u32 front_crc;  /* CRC of front portion */
+				u32 middle_crc; /* CRC of middle portion */
+				u32 data_crc;   /* CRC of data portion */
 			} __packed;
-			u8 pad[CEPH_GCM_BLOCK_LEN - 1];
+			u8 pad[CEPH_GCM_BLOCK_LEN - 1]; /* padding for GCM alignment */
 		};
 	} out_epil;
 };
 
 /*
+ * Ceph network connection metadata: Represents a single network connection
+ * to another Ceph entity (monitor, OSD, MDS). Manages message queuing,
+ * sequencing, authentication, and connection state to ensure reliable,
+ * ordered message delivery even across network interruptions.
+ *
  * A single connection with another host.
  *
  * We maintain a queue of outgoing messages, and some session state to
@@ -468,46 +650,79 @@ struct ceph_connection_v2_info {
  * messages in the case of a TCP disconnect.
  */
 struct ceph_connection {
+	/* Private data for connection owner (mon_client, osd_client, etc.) */
 	void *private;
 
+	/* Callback operations for connection events */
 	const struct ceph_connection_operations *ops;
 
+	/* Parent messenger instance */
 	struct ceph_messenger *msgr;
 
-	int state;  /* CEPH_CON_S_* */
+	/* Connection state management */
+	/* Current protocol state */
+	int state;
+	/* Atomic socket state */
 	atomic_t sock_state;
+	/* Network socket */
 	struct socket *sock;
 
-	unsigned long flags;  /* CEPH_CON_F_* */
-	const char *error_msg;  /* error message, if any */
-
-	struct ceph_entity_name peer_name; /* peer name */
-	struct ceph_entity_addr peer_addr; /* peer address */
+	/* Connection flags and error state */
+	unsigned long flags;
+	/* Human-readable error message */
+	const char *error_msg;
+
+	/* Peer identification */
+	/* Peer entity name (type + ID) */
+	struct ceph_entity_name peer_name;
+	/* Peer network address */
+	struct ceph_entity_addr peer_addr;
+	/* Feature flags supported by peer */
 	u64 peer_features;
 
+	/* Connection serialization */
 	struct mutex mutex;
 
-	/* out queue */
+	/* Message queue management */
+	/* Queue of messages waiting to be sent */
 	struct list_head out_queue;
-	struct list_head out_sent;   /* sending or sent but unacked */
-	u64 out_seq;		     /* last message queued for send */
+	/* Messages sent but not yet acknowledged */
+	struct list_head out_sent;
+	/* Last message sequence number queued */
+	u64 out_seq;
 
-	u64 in_seq, in_seq_acked;  /* last message received, acked */
+	/* Sequence number tracking for reliable delivery */
+	/* Last message received, last message acknowledged */
+	u64 in_seq, in_seq_acked;
 
+	/* Current message processing */
+	/* Message currently being received */
 	struct ceph_msg *in_msg;
+	/* Message currently being sent */
 	struct ceph_msg *out_msg;        /* sending message (== tail of
 					    out_sent) */
 
+	/* I/O processing support */
+	/* Temporary page for small I/O operations */
 	struct page *bounce_page;
-	u32 in_front_crc, in_middle_crc, in_data_crc;  /* calculated crc */
+	/* CRC values for incoming message verification */
+	u32 in_front_crc, in_middle_crc, in_data_crc;
 
-	struct timespec64 last_keepalive_ack; /* keepalive2 ack stamp */
+	/* Keepalive and connection health */
+	/* Timestamp of last keepalive acknowledgment */
+	struct timespec64 last_keepalive_ack;
 
-	struct delayed_work work;	    /* send|recv work */
+	/* Work queue processing */
+	/* Delayed work for send/receive operations */
+	struct delayed_work work;
+	/* Current exponential backoff delay */
 	unsigned long       delay;          /* current delay interval */
 
+	/* Protocol version-specific information */
 	union {
+		/* Messenger v1 protocol state */
 		struct ceph_connection_v1_info v1;
+		/* Messenger v2 protocol state */
 		struct ceph_connection_v2_info v2;
 	};
 };
-- 
2.51.0

[RFC PATCH 11/20] ceph: add comments to metadata structures in mon_client.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_monmap,
struct ceph_mon_request, struct ceph_mon_generic_request,
struct ceph_mon_client in /include/linux/ceph/mon_client.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/mon_client.h | 93 +++++++++++++++++++++++++++------
 1 file changed, 78 insertions(+), 15 deletions(-)

diff --git a/include/linux/ceph/mon_client.h b/include/linux/ceph/mon_client.h
index 7a9a40163c0f..057bd1eed1d6 100644
--- a/include/linux/ceph/mon_client.h
+++ b/include/linux/ceph/mon_client.h
@@ -13,12 +13,17 @@ struct ceph_mount_args;
 struct ceph_auth_client;
 
 /*
- * The monitor map enumerates the set of all monitors.
+ * Monitor map metadata: Enumerates the set of all Ceph monitors in the cluster.
+ * Used to track available monitors and their network addresses for failover.
  */
 struct ceph_monmap {
+	/* Unique filesystem identifier for this Ceph cluster */
 	struct ceph_fsid fsid;
+	/* Monitor map version/epoch number */
 	u32 epoch;
+	/* Number of monitors in the cluster */
 	u32 num_mon;
+	/* Array of monitor instances (address + name) */
 	struct ceph_entity_inst mon_inst[] __counted_by(num_mon);
 };
 
@@ -27,79 +32,129 @@ struct ceph_mon_generic_request;
 
 
 /*
- * Generic mechanism for resending monitor requests.
+ * Monitor request callback metadata: Generic mechanism for resending monitor requests.
+ * Called when switching to a new monitor or retrying failed requests.
  */
 typedef void (*ceph_monc_request_func_t)(struct ceph_mon_client *monc,
 					 int newmon);
 
-/* a pending monitor request */
+/*
+ * Pending monitor request metadata: Represents a monitor request that may need
+ * to be retried or resent if the current monitor becomes unavailable.
+ */
 struct ceph_mon_request {
+	/* Monitor client this request belongs to */
 	struct ceph_mon_client *monc;
+	/* Delayed work for request retry/resend */
 	struct delayed_work delayed_work;
+	/* Current retry delay in jiffies */
 	unsigned long delay;
+	/* Callback to execute the request */
 	ceph_monc_request_func_t do_request;
 };
 
+/*
+ * Generic request completion callback metadata: Called when a generic monitor
+ * request completes, allowing the caller to process the response.
+ */
 typedef void (*ceph_monc_callback_t)(struct ceph_mon_generic_request *);
 
 /*
- * ceph_mon_generic_request is being used for the statfs and
- * mon_get_version requests which are being done a bit differently
- * because we need to get data back to the caller
+ * Generic monitor request metadata: Used for statfs and mon_get_version requests
+ * that need to return data to the caller. Provides synchronous and asynchronous
+ * request patterns with proper cleanup and response handling.
  */
 struct ceph_mon_generic_request {
+	/* Monitor client this request belongs to */
 	struct ceph_mon_client *monc;
+	/* Reference counting for safe cleanup */
 	struct kref kref;
+	/* Transaction ID for request tracking */
 	u64 tid;
+	/* Red-black tree node for efficient lookup */
 	struct rb_node node;
+	/* Request completion result code */
 	int result;
 
+	/* Synchronous completion notification */
 	struct completion completion;
+	/* Asynchronous completion callback */
 	ceph_monc_callback_t complete_cb;
-	u64 private_data;          /* r_tid/linger_id */
+	/* Caller-specific data (request ID/linger ID) */
+	u64 private_data;
 
-	struct ceph_msg *request;  /* original request */
-	struct ceph_msg *reply;    /* and reply */
+	/* Original request message sent to monitor */
+	struct ceph_msg *request;
+	/* Reply message received from monitor */
+	struct ceph_msg *reply;
 
+	/* Request-specific response data */
 	union {
+		/* For statfs requests: filesystem statistics */
 		struct ceph_statfs *st;
+		/* For version requests: newest available version */
 		u64 newest;
 	} u;
 };
 
+/*
+ * Monitor client state metadata: Manages communication with Ceph monitor cluster.
+ * Handles monitor discovery, failover, authentication, subscriptions, and request routing.
+ * Provides high availability by automatically switching between available monitors.
+ */
 struct ceph_mon_client {
+	/* Parent Ceph client instance */
 	struct ceph_client *client;
+	/* Current monitor map with available monitors */
 	struct ceph_monmap *monmap;
 
+	/* Serializes monitor client operations */
 	struct mutex mutex;
+	/* Delayed work for periodic operations and retries */
 	struct delayed_work delayed_work;
 
+	/* Authentication client for monitor authentication */
 	struct ceph_auth_client *auth;
+	/* Pre-allocated messages for auth and subscription protocols */
 	struct ceph_msg *m_auth, *m_auth_reply, *m_subscribe, *m_subscribe_ack;
+	/* Authentication request in progress flag */
 	int pending_auth;
 
+	/* Currently searching for available monitors */
 	bool hunting;
-	int cur_mon;                       /* last monitor i contacted */
+	/* Index of last monitor contacted */
+	int cur_mon;
+	/* Time when subscriptions should be renewed */
 	unsigned long sub_renew_after;
+	/* Time when subscription renewal was last sent */
 	unsigned long sub_renew_sent;
+	/* Network connection to current monitor */
 	struct ceph_connection con;
 
+	/* Ever successfully connected to any monitor */
 	bool had_a_connection;
-	int hunt_mult; /* [1..CEPH_MONC_HUNT_MAX_MULT] */
+	/* Hunt backoff multiplier [1..CEPH_MONC_HUNT_MAX_MULT] */
+	int hunt_mult;
 
-	/* pending generic requests */
+	/* Tree of pending generic requests awaiting responses */
 	struct rb_root generic_request_tree;
+	/* Last transaction ID assigned to generic requests */
 	u64 last_tid;
 
-	/* subs, indexed with CEPH_SUB_* */
+	/* Map subscriptions indexed by CEPH_SUB_* constants */
 	struct {
+		/* Subscription request details */
 		struct ceph_mon_subscribe_item item;
+		/* Want to receive updates for this map type */
 		bool want;
-		u32 have; /* epoch */
+		/* Current epoch/version we have */
+		u32 have;
 	} subs[4];
-	int fs_cluster_id; /* "mdsmap.<id>" sub */
+	/* Filesystem cluster ID for "mdsmap.<id>" subscription */
+	int fs_cluster_id;
 
 #ifdef CONFIG_DEBUG_FS
+	/* Debug filesystem entry for monitoring state */
 	struct dentry *debugfs_file;
 #endif
 };
@@ -111,10 +166,18 @@ extern int ceph_monc_init(struct ceph_mon_client *monc, struct ceph_client *cl);
 extern void ceph_monc_stop(struct ceph_mon_client *monc);
 extern void ceph_monc_reopen_session(struct ceph_mon_client *monc);
 
+/*
+ * Map subscription type constants: Indices for different types of cluster maps
+ * that can be subscribed to for receiving updates from monitors.
+ */
 enum {
+	/* Monitor map - tracks available monitors */
 	CEPH_SUB_MONMAP = 0,
+	/* OSD map - tracks available storage daemons and placement groups */
 	CEPH_SUB_OSDMAP,
+	/* Filesystem map - tracks CephFS filesystems */
 	CEPH_SUB_FSMAP,
+	/* MDS map - tracks metadata server daemons */
 	CEPH_SUB_MDSMAP,
 };
 
-- 
2.51.0

[RFC PATCH 12/20] ceph: add comments to metadata structures in msgpool.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_msgpool
in /include/linux/ceph/msgpool.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/msgpool.h | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/include/linux/ceph/msgpool.h b/include/linux/ceph/msgpool.h
index 729cdf700eae..27e6a53a014d 100644
--- a/include/linux/ceph/msgpool.h
+++ b/include/linux/ceph/msgpool.h
@@ -5,14 +5,21 @@
 #include <linux/mempool.h>
 
 /*
- * we use memory pools for preallocating messages we may receive, to
- * avoid unexpected OOM conditions.
+ * Ceph message pool metadata: Memory pool for preallocating network messages
+ * to avoid out-of-memory conditions during critical operations. Maintains
+ * a reserve of messages with specific types and sizes for reliable operation
+ * under memory pressure.
  */
 struct ceph_msgpool {
+	/* Descriptive name for debugging and identification */
 	const char *name;
+	/* Underlying kernel memory pool */
 	mempool_t *pool;
-	int type;               /* preallocated message type */
-	int front_len;          /* preallocated payload size */
+	/* Message type for preallocated messages */
+	int type;
+	/* Size of preallocated front payload */
+	int front_len;
+	/* Maximum number of data items in preallocated messages */
 	int max_data_items;
 };
 
-- 
2.51.0

[RFC PATCH 13/20] ceph: add comments to metadata structures in msgr.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_entity_name,
struct ceph_entity_addr, struct ceph_entity_inst,
struct ceph_msg_connect, struct ceph_msg_connect_reply,
struct ceph_msg_header_old, struct ceph_msg_header,
struct ceph_msg_header2, struct ceph_msg_footer_old,
struct ceph_msg_footer in /include/linux/ceph/msgr.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/msgr.h | 162 +++++++++++++++++++++++++++++++-------
 1 file changed, 132 insertions(+), 30 deletions(-)

diff --git a/include/linux/ceph/msgr.h b/include/linux/ceph/msgr.h
index 3989dcb94d3d..69b0a50f1453 100644
--- a/include/linux/ceph/msgr.h
+++ b/include/linux/ceph/msgr.h
@@ -60,11 +60,17 @@ static inline __s32 ceph_seq_cmp(__u32 a, __u32 b)
 
 
 /*
+ * Entity name metadata: Logical identifier for a Ceph process participating
+ * in the cluster network. Combines entity type (monitor, OSD, MDS, client)
+ * with a unique number to create globally unique process identifiers.
+ *
  * entity_name -- logical name for a process participating in the
  * network, e.g. 'mds0' or 'osd3'.
  */
 struct ceph_entity_name {
+	/* Entity type (monitor, OSD, MDS, client, etc.) */
 	__u8 type;      /* CEPH_ENTITY_TYPE_* */
+	/* Unique number within the entity type */
 	__le64 num;
 } __attribute__ ((packed));
 
@@ -79,11 +85,16 @@ struct ceph_entity_name {
 extern const char *ceph_entity_type_name(int type);
 
 /*
- * entity_addr -- network address
+ * Entity address metadata: Network address information for a Ceph entity.
+ * Contains address type, process nonce for disambiguation, and the actual
+ * network socket address for establishing connections.
  */
 struct ceph_entity_addr {
+	/* Address type identifier */
 	__le32 type;  /* CEPH_ENTITY_ADDR_TYPE_* */
-	__le32 nonce;  /* unique id for process (e.g. pid) */
+	/* Unique process identifier (typically PID) */
+	__le32 nonce;
+	/* Socket address (IPv4/IPv6) */
 	struct sockaddr_storage in_addr;
 } __attribute__ ((packed));
 
@@ -94,8 +105,15 @@ static inline bool ceph_addr_equal_no_type(const struct ceph_entity_addr *lhs,
 	       lhs->nonce == rhs->nonce;
 }
 
+/*
+ * Entity instance metadata: Complete identification of a Ceph entity
+ * combining logical name with network address. Uniquely identifies
+ * a specific process instance in the cluster.
+ */
 struct ceph_entity_inst {
+	/* Logical entity name (type + number) */
 	struct ceph_entity_name name;
+	/* Network address for this entity */
 	struct ceph_entity_addr addr;
 } __attribute__ ((packed));
 
@@ -122,26 +140,48 @@ struct ceph_entity_inst {
 #define CEPH_MSGR_TAG_CHALLENGE_AUTHORIZER 16  /* cephx v2 doing server challenge */
 
 /*
- * connection negotiation
+ * Connection negotiation request metadata: Initial message sent to establish
+ * a connection with another Ceph entity. Contains feature negotiation,
+ * authentication details, and connection sequencing information.
  */
 struct ceph_msg_connect {
-	__le64 features;     /* supported feature bits */
+	/* Feature flags supported by this client */
+	__le64 features;
+	/* Entity type of the connecting host */
 	__le32 host_type;    /* CEPH_ENTITY_TYPE_* */
-	__le32 global_seq;   /* count connections initiated by this host */
+	/* Global connection sequence (across all sessions) */
+	__le32 global_seq;
+	/* Connection sequence within current session */
 	__le32 connect_seq;  /* count connections initiated in this session */
+	/* Wire protocol version */
 	__le32 protocol_version;
+	/* Authentication protocol identifier */
 	__le32 authorizer_protocol;
+	/* Length of authentication data */
 	__le32 authorizer_len;
+	/* Connection flags (lossy, etc.) */
 	__u8  flags;         /* CEPH_MSG_CONNECT_* */
 } __attribute__ ((packed));
 
+/*
+ * Connection negotiation reply metadata: Response to connection request
+ * indicating whether connection was accepted, feature set negotiated,
+ * and any authentication challenges or requirements.
+ */
 struct ceph_msg_connect_reply {
+	/* Reply tag (ready, retry, error, etc.) */
 	__u8 tag;
-	__le64 features;     /* feature bits for this session */
+	/* Feature flags enabled for this session */
+	__le64 features;
+	/* Server's global sequence number */
 	__le32 global_seq;
+	/* Server's connection sequence number */
 	__le32 connect_seq;
+	/* Negotiated protocol version */
 	__le32 protocol_version;
+	/* Length of authorization challenge data */
 	__le32 authorizer_len;
+	/* Connection reply flags */
 	__u8 flags;
 } __attribute__ ((packed));
 
@@ -149,60 +189,111 @@ struct ceph_msg_connect_reply {
 
 
 /*
- * message header
+ * Legacy message header metadata: Original wire format for message headers
+ * in older Ceph versions. Contains complete routing information, payload
+ * lengths, and both source and original source for message forwarding.
  */
 struct ceph_msg_header_old {
-	__le64 seq;       /* message seq# for this session */
-	__le64 tid;       /* transaction id */
-	__le16 type;      /* message type */
-	__le16 priority;  /* priority.  higher value == higher priority */
-	__le16 version;   /* version of message encoding */
-
+	/* Message sequence number for this session */
+	__le64 seq;
+	/* Transaction identifier for request/reply correlation */
+	__le64 tid;
+	/* Message type identifier */
+	__le16 type;
+	/* Message priority (higher value = higher priority) */
+	__le16 priority;
+	/* Version of message encoding/format */
+	__le16 version;
+
+	/* Payload section lengths */
+	/* Length of front payload section */
 	__le32 front_len; /* bytes in main payload */
+	/* Length of middle payload section */
 	__le32 middle_len;/* bytes in middle payload */
+	/* Length of data payload section */
 	__le32 data_len;  /* bytes of data payload */
+	/* Data offset (sender: full offset, receiver: page-masked) */
 	__le16 data_off;  /* sender: include full offset;
 			     receiver: mask against ~PAGE_MASK */
 
+	/* Message routing information */
+	/* Current source and original source entities */
 	struct ceph_entity_inst src, orig_src;
+	/* Reserved field */
 	__le32 reserved;
-	__le32 crc;       /* header crc32c */
+	/* Header CRC32c checksum */
+	__le32 crc;
 } __attribute__ ((packed));
 
+/*
+ * Standard message header metadata: Current wire format for message headers.
+ * Streamlined compared to legacy format, containing essential routing and
+ * payload information with compatibility version support.
+ */
 struct ceph_msg_header {
-	__le64 seq;       /* message seq# for this session */
-	__le64 tid;       /* transaction id */
-	__le16 type;      /* message type */
-	__le16 priority;  /* priority.  higher value == higher priority */
-	__le16 version;   /* version of message encoding */
-
+	/* Message sequence number for this session */
+	__le64 seq;
+	/* Transaction identifier for request/reply correlation */
+	__le64 tid;
+	/* Message type identifier */
+	__le16 type;
+	/* Message priority (higher value = higher priority) */
+	__le16 priority;
+	/* Version of message encoding/format */
+	__le16 version;
+
+	/* Payload section lengths */
+	/* Length of front payload section */
 	__le32 front_len; /* bytes in main payload */
+	/* Length of middle payload section */
 	__le32 middle_len;/* bytes in middle payload */
+	/* Length of data payload section */
 	__le32 data_len;  /* bytes of data payload */
+	/* Data offset (sender: full offset, receiver: page-masked) */
 	__le16 data_off;  /* sender: include full offset;
 			     receiver: mask against ~PAGE_MASK */
 
+	/* Message source entity name */
 	struct ceph_entity_name src;
+	/* Compatibility version for backward compatibility */
 	__le16 compat_version;
+	/* Reserved field */
 	__le16 reserved;
-	__le32 crc;       /* header crc32c */
+	/* Header CRC32c checksum */
+	__le32 crc;
 } __attribute__ ((packed));
 
+/*
+ * Messenger v2 header metadata: Enhanced message header for messenger v2
+ * protocol with improved padding support, acknowledgment sequencing, and
+ * extended compatibility information.
+ */
 struct ceph_msg_header2 {
-	__le64 seq;       /* message seq# for this session */
-	__le64 tid;       /* transaction id */
-	__le16 type;      /* message type */
-	__le16 priority;  /* priority.  higher value == higher priority */
-	__le16 version;   /* version of message encoding */
-
+	/* Message sequence number for this session */
+	__le64 seq;
+	/* Transaction identifier for request/reply correlation */
+	__le64 tid;
+	/* Message type identifier */
+	__le16 type;
+	/* Message priority (higher value = higher priority) */
+	__le16 priority;
+	/* Version of message encoding/format */
+	__le16 version;
+
+	/* Data padding and alignment */
+	/* Length of pre-padding before data payload */
 	__le32 data_pre_padding_len;
+	/* Data offset (sender: full offset, receiver: page-masked) */
 	__le16 data_off;  /* sender: include full offset;
 			     receiver: mask against ~PAGE_MASK */
 
+	/* Acknowledgment sequence number */
 	__le64 ack_seq;
+	/* Message flags */
 	__u8 flags;
-	/* oldest code we think can decode this.  unknown if zero. */
+	/* Oldest code version that can decode this message.  unknown if zero. */
 	__le16 compat_version;
+	/* Reserved field */
 	__le16 reserved;
 } __attribute__ ((packed));
 
@@ -212,17 +303,28 @@ struct ceph_msg_header2 {
 #define CEPH_MSG_PRIO_HIGHEST 255
 
 /*
- * follows data payload
+ * Legacy message footer metadata: Integrity validation for older message format.
+ * Contains CRC checksums for each payload section to detect transmission errors
+ * and corruption. Used with legacy message headers for backward compatibility.
  */
 struct ceph_msg_footer_old {
+	/* CRC32c checksums for payload integrity validation */
 	__le32 front_crc, middle_crc, data_crc;
+	/* Message completion and validation flags */
 	__u8 flags;
 } __attribute__ ((packed));
 
+/*
+ * Standard message footer metadata: Enhanced integrity validation with digital
+ * signatures. Includes CRC checksums for each payload section plus optional
+ * cryptographic signature for message authenticity and non-repudiation.
+ */
 struct ceph_msg_footer {
+	/* CRC32c checksums for payload integrity validation */
 	__le32 front_crc, middle_crc, data_crc;
-	// sig holds the 64 bits of the digital signature for the message PLR
+	/* 64-bit digital signature for message authenticity (PLR) */
 	__le64  sig;
+	/* Message completion and validation flags */
 	__u8 flags;
 } __attribute__ ((packed));
 
-- 
2.51.0

Re: [RFC PATCH 13/20] ceph: add comments to metadata structures in msgr.h

[Max Kellermann]

On 2025/09/05 22:01, Viacheslav Dubeyko <slava@dubeyko.com> wrote:
> Claude AI generated comments for CephFS metadata structure
> declarations in include/linux/ceph/*.h. These comments
> have been reviewed, checked, and corrected.

After looking at several of your patches, I doubt the value of this
effort.  This is mostly just redundant noise being added.

>  struct ceph_entity_addr {
> +	/* Address type identifier */
>  	__le32 type;  /* CEPH_ENTITY_ADDR_TYPE_* */

The old comment, which you (accidently?) left in there, is better than
your new comment.  It specifies what values are possible.

"Address type identifier" means nothing to me, no more than "type" of
"ceph_entity_addr".

> -	__le32 nonce;  /* unique id for process (e.g. pid) */
> +	/* Unique process identifier (typically PID) */
> +	__le32 nonce;

No improvement here.  Just rephrased to be a bit more verbose without
adding any information.

> +	/* Socket address (IPv4/IPv6) */
>  	struct sockaddr_storage in_addr;

Surprise - a "struct sockaddr_storage" is a socket address?  Does this
need to be explained?

What is the value of pointing out that it can be IPv4 or IPv6?  You
asked Claude to generate tokens, and so it did.  But do these tokens
add any value?  I don't think so.

>  struct ceph_entity_inst {
> +	/* Logical entity name (type + number) */
>  	struct ceph_entity_name name;

I don't understand this comment.  Okay, so the entity name is an
entity name, but what does it mean for a name to be "logical"?  What
is this "type" and "number" and how do you add them?

> +	/* Network address for this entity */
>  	struct ceph_entity_addr addr;

Oh well.  The address is an address.

> +	/* Wire protocol version */
>  	__le32 protocol_version;

The protocol version is one for the wire.  A-ha.

> +	/* Connection flags (lossy, etc.) */
>  	__u8  flags;         /* CEPH_MSG_CONNECT_* */

The old comment looked fine.  I can "git grep CEPH_MSG_CONNECT_" and
see possible values.

The new comment says these flags are for the connection.  Okay.  And
the flags can be lossy, can't they?  No, one of the possibly flags is
just "CEPH_MSG_CONNECT_LOSSY" and Claude confusingly rephrased this to
"lossy".  And "etc.", but what is "etc."?  Nothing, there are no other
flags.  The "etc." is just noise.

What would have been valuable pointing out is that this is a bit mask
(but this can be guessed easily).

Just leave the old comment, it's fine and enough.

>  struct ceph_msg_connect_reply {
> +	/* Reply tag (ready, retry, error, etc.) */
>  	__u8 tag;

How does "ready", "retry" etc. fit into a __u8?  Claude unhelpfully
omitted technical details by rephrasing the macro names.


(That's all I'm going to comment on now.  I could go on for hours, but
I feel this is a waste of time.)

[RFC PATCH 14/20] ceph: add comments to metadata structures in osd_client.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_sparse_extent,
enum ceph_sparse_read_state, struct ceph_sparse_read,
struct ceph_osd, enum ceph_osd_data_type, struct ceph_osd_data,
struct ceph_osd_req_op, struct ceph_osd_request_target,
struct ceph_osd_request, struct ceph_request_redirect,
struct ceph_osd_reqid, struct ceph_blkin_trace_info,
struct ceph_osd_linger_request, struct ceph_watch_item,
struct ceph_spg_mapping, struct ceph_hobject_id,
struct ceph_osd_backoff, struct ceph_osd_client
in /include/linux/ceph/osd_client.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/osd_client.h | 407 +++++++++++++++++++++++++++-----
 1 file changed, 354 insertions(+), 53 deletions(-)

diff --git a/include/linux/ceph/osd_client.h b/include/linux/ceph/osd_client.h
index 50b14a5661c7..1278368b16fc 100644
--- a/include/linux/ceph/osd_client.h
+++ b/include/linux/ceph/osd_client.h
@@ -23,33 +23,48 @@ struct ceph_osd_request;
 struct ceph_osd_client;
 
 /*
- * completion callback for async writepages
+ * Completion callback for async operations: Called when OSD request completes
+ * to notify the submitter of success or failure. Used for writepages and other
+ * asynchronous I/O operations that need completion notification.
  */
 typedef void (*ceph_osdc_callback_t)(struct ceph_osd_request *);
 
 #define CEPH_HOMELESS_OSD	-1
 
 /*
- * A single extent in a SPARSE_READ reply.
+ * Sparse read extent metadata: Describes a single data extent in a SPARSE_READ reply.
+ * Sparse reads allow efficient retrieval of files with holes by only transferring
+ * data regions, skipping over sparse (zero) areas.
  *
  * Note that these come from the OSD as little-endian values. On BE arches,
  * we convert them in-place after receipt.
  */
 struct ceph_sparse_extent {
+	/* Offset of this extent within the object */
 	u64	off;
+	/* Length of data in this extent */
 	u64	len;
 } __packed;
 
-/* Sparse read state machine state values */
+/*
+ * Sparse read state machine values: Tracks the parsing progress through
+ * a SPARSE_READ reply message, which contains header, extent array, and data.
+ */
 enum ceph_sparse_read_state {
+	/* Reading sparse read reply header */
 	CEPH_SPARSE_READ_HDR	= 0,
+	/* Reading extent array (offset/length pairs) */
 	CEPH_SPARSE_READ_EXTENTS,
+	/* Reading data length field */
 	CEPH_SPARSE_READ_DATA_LEN,
+	/* Pre-processing before reading actual data */
 	CEPH_SPARSE_READ_DATA_PRE,
+	/* Reading the actual file data */
 	CEPH_SPARSE_READ_DATA,
 };
 
 /*
+ * Sparse read parser metadata: Tracks the state of parsing a SPARSE_READ reply.
  * A SPARSE_READ reply is a 32-bit count of extents, followed by an array of
  * 64-bit offset/length pairs, and then all of the actual file data
  * concatenated after it (sans holes).
@@ -60,324 +75,573 @@ enum ceph_sparse_read_state {
  * or if the caller doesn't.
  */
 struct ceph_sparse_read {
-	enum ceph_sparse_read_state	sr_state;    /* state machine state */
-	u64				sr_req_off;  /* orig request offset */
-	u64				sr_req_len;  /* orig request length */
-	u64				sr_pos;      /* current pos in buffer */
-	int				sr_index;    /* current extent index */
-	u32				sr_datalen;  /* length of actual data */
-	u32				sr_count;    /* extent count in reply */
-	int				sr_ext_len;  /* length of extent array */
-	struct ceph_sparse_extent	*sr_extent;  /* extent array */
+	/* Current state in the parsing state machine */
+	enum ceph_sparse_read_state	sr_state;
+	/* Original request offset for validation */
+	u64				sr_req_off;
+	/* Original request length for validation */
+	u64				sr_req_len;
+	/* Current position in the receive buffer */
+	u64				sr_pos;
+	/* Current extent being processed */
+	int				sr_index;
+	/* Total length of actual data (excluding holes) */
+	u32				sr_datalen;
+	/* Number of extents in the reply */
+	u32				sr_count;
+	/* Allocated length of extent array */
+	int				sr_ext_len;
+	/* Dynamic array of extent descriptors */
+	struct ceph_sparse_extent	*sr_extent;
 };
 
 /*
- * A given osd we're communicating with.
+ * OSD connection metadata: Represents a single Object Storage Daemon (OSD)
+ * that we're actively communicating with. Manages the network connection,
+ * pending requests, authentication, and sparse read state for this OSD.
  *
  * Note that the o_requests tree can be searched while holding the "lock" mutex
  * or the "o_requests_lock" spinlock. Insertion or removal requires both!
  */
 struct ceph_osd {
+	/* Reference counting for safe cleanup */
 	refcount_t o_ref;
+	/* Index of current sparse read operation */
 	int o_sparse_op_idx;
+	/* Back-reference to OSD client */
 	struct ceph_osd_client *o_osdc;
+	/* OSD identifier number in the cluster */
 	int o_osd;
+	/* OSD incarnation number for detecting restarts */
 	int o_incarnation;
+	/* Red-black tree node in osdc->osds tree */
 	struct rb_node o_node;
+	/* Network connection to this OSD */
 	struct ceph_connection o_con;
+	/* Protects request trees (fast path) */
 	spinlock_t o_requests_lock;
+	/* Tree of regular requests to this OSD */
 	struct rb_root o_requests;
+	/* Tree of linger requests (watches/notifies) */
 	struct rb_root o_linger_requests;
+	/* Backoff mappings by placement group */
 	struct rb_root o_backoff_mappings;
+	/* Backoff mappings by backoff ID */
 	struct rb_root o_backoffs_by_id;
+	/* LRU list node for idle OSD cleanup */
 	struct list_head o_osd_lru;
+	/* Authentication handshake state */
 	struct ceph_auth_handshake o_auth;
+	/* Time when this OSD should be considered for LRU eviction */
 	unsigned long lru_ttl;
+	/* Keepalive processing list */
 	struct list_head o_keepalive_item;
+	/* Serializes OSD operations (slow path) */
 	struct mutex lock;
+	/* Sparse read parsing state for this OSD */
 	struct ceph_sparse_read	o_sparse_read;
 };
 
 #define CEPH_OSD_SLAB_OPS	2
 #define CEPH_OSD_MAX_OPS	16
 
+/*
+ * OSD data container types: Defines the different ways data can be provided
+ * to OSD operations, allowing flexible memory management for different I/O patterns.
+ */
 enum ceph_osd_data_type {
+	/* No data attached */
 	CEPH_OSD_DATA_TYPE_NONE = 0,
+	/* Array of struct page pointers */
 	CEPH_OSD_DATA_TYPE_PAGES,
+	/* Ceph pagelist structure */
 	CEPH_OSD_DATA_TYPE_PAGELIST,
 #ifdef CONFIG_BLOCK
+	/* Block I/O bio structure */
 	CEPH_OSD_DATA_TYPE_BIO,
 #endif /* CONFIG_BLOCK */
+	/* Array of bio_vec structures */
 	CEPH_OSD_DATA_TYPE_BVECS,
+	/* Iterator over memory regions */
 	CEPH_OSD_DATA_TYPE_ITER,
 };
 
+/*
+ * OSD data container metadata: Flexible container for different types of data
+ * that can be sent to or received from OSDs. Supports various memory layouts
+ * for efficient I/O without unnecessary copying.
+ */
 struct ceph_osd_data {
+	/* Type of data container being used */
 	enum ceph_osd_data_type	type;
 	union {
+		/* Page array data container */
 		struct {
+			/* Array of page pointers */
 			struct page	**pages;
+			/* Total data length */
 			u64		length;
+			/* Alignment requirement for first page */
 			u32		alignment;
+			/* Pages allocated from mempool */
 			bool		pages_from_pool;
+			/* We own the pages and must free them */
 			bool		own_pages;
 		};
+		/* Ceph pagelist container */
 		struct ceph_pagelist	*pagelist;
 #ifdef CONFIG_BLOCK
+		/* Block I/O bio container */
 		struct {
+			/* Bio iterator position */
 			struct ceph_bio_iter	bio_pos;
+			/* Length of bio data */
 			u32			bio_length;
 		};
 #endif /* CONFIG_BLOCK */
+		/* Bio vector array container */
 		struct {
+			/* Bio vector iterator position */
 			struct ceph_bvec_iter	bvec_pos;
+			/* Number of bio vectors */
 			u32			num_bvecs;
 		};
+		/* Generic iterator over memory */
 		struct iov_iter		iter;
 	};
 };
 
+/*
+ * OSD request operation metadata: Describes a single operation within an OSD request.
+ * Each request can contain multiple operations that are executed atomically.
+ * Supports various operation types like read/write, class methods, xattrs, etc.
+ */
 struct ceph_osd_req_op {
-	u16 op;           /* CEPH_OSD_OP_* */
-	u32 flags;        /* CEPH_OSD_OP_FLAG_* */
-	u32 indata_len;   /* request */
-	u32 outdata_len;  /* reply */
+	/* Operation type (CEPH_OSD_OP_*) */
+	u16 op;
+	/* Operation flags (CEPH_OSD_OP_FLAG_*) */
+	u32 flags;
+	/* Length of input data */
+	u32 indata_len;
+	/* Length of expected output data */
+	u32 outdata_len;
+	/* Operation result/error code */
 	s32 rval;
 
+	/* Operation-specific parameters */
 	union {
+		/* Raw data input for simple operations */
 		struct ceph_osd_data raw_data_in;
+		/* Extent-based operations (read/write) */
 		struct {
+			/* Offset within object + length of extent */
 			u64 offset, length;
+			/* Truncation parameters */
 			u64 truncate_size;
 			u32 truncate_seq;
+			/* Sparse extent information */
 			int sparse_ext_cnt;
 			struct ceph_sparse_extent *sparse_ext;
+			/* Data payload */
 			struct ceph_osd_data osd_data;
 		} extent;
+		/* Extended attribute operations */
 		struct {
+			/* Attribute name and value lengths */
 			u32 name_len;
 			u32 value_len;
+			/* Comparison operation type */
 			__u8 cmp_op;       /* CEPH_OSD_CMPXATTR_OP_* */
+			/* Comparison mode */
 			__u8 cmp_mode;     /* CEPH_OSD_CMPXATTR_MODE_* */
+			/* Attribute data */
 			struct ceph_osd_data osd_data;
 		} xattr;
+		/* Object class method invocation */
 		struct {
+			/* Class and method names */
 			const char *class_name;
 			const char *method_name;
+			/* Method call data */
 			struct ceph_osd_data request_info;
 			struct ceph_osd_data request_data;
 			struct ceph_osd_data response_data;
+			/* Name lengths */
 			__u8 class_len;
 			__u8 method_len;
+			/* Input data length */
 			u32 indata_len;
 		} cls;
+		/* Watch operations for object monitoring */
 		struct {
+			/* Watch cookie for identification */
 			u64 cookie;
+			/* Watch operation type */
 			__u8 op;           /* CEPH_OSD_WATCH_OP_ */
+			/* Generation number */
 			u32 gen;
 		} watch;
+		/* Notify acknowledgment */
 		struct {
+			/* Acknowledgment data */
 			struct ceph_osd_data request_data;
 		} notify_ack;
+		/* Object notification */
 		struct {
+			/* Notification cookie */
 			u64 cookie;
+			/* Notification payload */
 			struct ceph_osd_data request_data;
 			struct ceph_osd_data response_data;
 		} notify;
+		/* List current watchers */
 		struct {
+			/* Watcher list response */
 			struct ceph_osd_data response_data;
 		} list_watchers;
+		/* Allocation hint for object sizing */
 		struct {
+			/* Expected object and write sizes */
 			u64 expected_object_size;
 			u64 expected_write_size;
+			/* Allocation flags */
 			u32 flags;  /* CEPH_OSD_OP_ALLOC_HINT_FLAG_* */
 		} alloc_hint;
+		/* Copy from another object */
 		struct {
+			/* Source snapshot ID */
 			u64 snapid;
+			/* Source object version */
 			u64 src_version;
+			/* Copy operation flags */
 			u8 flags;
+			/* Source fadvise flags */
 			u32 src_fadvise_flags;
+			/* Destination data */
 			struct ceph_osd_data osd_data;
 		} copy_from;
+		/* Assert object version */
 		struct {
+			/* Expected version */
 			u64 ver;
 		} assert_ver;
 	};
 };
 
+/*
+ * OSD request target metadata: Contains object location and placement group
+ * mapping information for routing requests to the correct OSD. Includes both
+ * the original target and the resolved placement information.
+ */
 struct ceph_osd_request_target {
+	/* Original object identifier */
 	struct ceph_object_id base_oid;
+	/* Original object locator (pool, namespace) */
 	struct ceph_object_locator base_oloc;
+	/* Resolved target object identifier */
 	struct ceph_object_id target_oid;
+	/* Resolved target object locator */
 	struct ceph_object_locator target_oloc;
 
-	struct ceph_pg pgid;               /* last raw pg we mapped to */
-	struct ceph_spg spgid;             /* last actual spg we mapped to */
+	/* Last raw placement group we mapped to */
+	struct ceph_pg pgid;
+	/* Last actual sharded placement group */
+	struct ceph_spg spgid;
+	/* Number of placement groups in pool */
 	u32 pg_num;
+	/* Bitmask for PG number calculation */
 	u32 pg_num_mask;
+	/* Acting OSD set for this PG */
 	struct ceph_osds acting;
+	/* Up OSD set for this PG */
 	struct ceph_osds up;
+	/* Replication size */
 	int size;
+	/* Minimum replicas required */
 	int min_size;
+	/* Use bitwise sorting for object names */
 	bool sort_bitwise;
+	/* Recovery can delete objects */
 	bool recovery_deletes;
 
-	unsigned int flags;                /* CEPH_OSD_FLAG_* */
+	/* Request flags (CEPH_OSD_FLAG_*) */
+	unsigned int flags;
+	/* Whether we used a replica OSD */
 	bool used_replica;
+	/* Request is paused */
 	bool paused;
 
+	/* OSD map epoch used for this mapping */
 	u32 epoch;
+	/* Last epoch we force-resent this request */
 	u32 last_force_resend;
 
+	/* Target OSD number */
 	int osd;
 };
 
-/* an in-flight request */
+/*
+ * In-flight OSD request metadata: Represents a complete request to an OSD,
+ * including target information, operations, timing, and completion handling.
+ * Tracks the full lifecycle from submission to completion.
+ */
 struct ceph_osd_request {
-	u64             r_tid;              /* unique for this client */
+	/* Unique transaction ID for this client */
+	u64             r_tid;
+	/* Red-black tree node for OSD's request tree */
 	struct rb_node  r_node;
-	struct rb_node  r_mc_node;          /* map check */
+	/* Red-black tree node for map check tree */
+	struct rb_node  r_mc_node;
+	/* Work item for completion processing */
 	struct work_struct r_complete_work;
+	/* Target OSD for this request */
 	struct ceph_osd *r_osd;
 
+	/* Request targeting and placement information */
 	struct ceph_osd_request_target r_t;
 #define r_base_oid	r_t.base_oid
 #define r_base_oloc	r_t.base_oloc
 #define r_flags		r_t.flags
 
+	/* Network messages for request and reply */
 	struct ceph_msg  *r_request, *r_reply;
-	u32               r_sent;      /* >0 if r_request is sending/sent */
+	/* >0 if r_request is sending/sent */
+	u32               r_sent;
 
-	/* request osd ops array  */
+	/* Number of operations in this request */
 	unsigned int		r_num_ops;
 
+	/* Overall result code for the request */
 	int               r_result;
 
+	/* Back-reference to OSD client */
 	struct ceph_osd_client *r_osdc;
+	/* Reference counting for safe cleanup */
 	struct kref       r_kref;
+	/* Request allocated from mempool */
 	bool              r_mempool;
-	bool		  r_linger;           /* don't resend on failure */
-	struct completion r_completion;       /* private to osd_client.c */
+	/* Linger request - don't resend on failure */
+	bool		  r_linger;
+	/* Completion notification (private to osd_client.c) */
+	struct completion r_completion;
+	/* Callback function for async completion */
 	ceph_osdc_callback_t r_callback;
 
-	struct inode *r_inode;         	      /* for use by callbacks */
-	struct list_head r_private_item;      /* ditto */
-	void *r_priv;			      /* ditto */
-
-	/* set by submitter */
-	u64 r_snapid;                         /* for reads, CEPH_NOSNAP o/w */
-	struct ceph_snap_context *r_snapc;    /* for writes */
-	struct timespec64 r_mtime;            /* ditto */
-	u64 r_data_offset;                    /* ditto */
-
-	/* internal */
-	u64 r_version;			      /* data version sent in reply */
+	/* Context information for callbacks */
+	struct inode *r_inode;
+	struct list_head r_private_item;
+	void *r_priv;
+
+	/* Request parameters set by submitter */
+	/* Snapshot ID for reads, CEPH_NOSNAP otherwise */
+	u64 r_snapid;
+	/* Snapshot context for writes */
+	struct ceph_snap_context *r_snapc;
+	/* Modification time for writes */
+	struct timespec64 r_mtime;
+	/* Data offset within object */
+	u64 r_data_offset;
+
+	/* Internal tracking fields */
+	/* Data version returned in reply */
+	u64 r_version;
+	/* Timestamp when sent or last checked */
 	unsigned long r_stamp;                /* jiffies, send or check time */
+	/* Timestamp when request started */
 	unsigned long r_start_stamp;          /* jiffies */
+	/* Latency measurement start time */
 	ktime_t r_start_latency;              /* ktime_t */
+	/* Latency measurement end time */
 	ktime_t r_end_latency;                /* ktime_t */
+	/* Number of send attempts */
 	int r_attempts;
+	/* Map epoch bound for "does not exist" errors */
 	u32 r_map_dne_bound;
 
+	/* Array of operations in this request */
 	struct ceph_osd_req_op r_ops[] __counted_by(r_num_ops);
 };
 
+/*
+ * Request redirect metadata: Contains the new object location when an OSD
+ * request is redirected to a different pool or namespace.
+ */
 struct ceph_request_redirect {
+	/* New object locator (pool, namespace) */
 	struct ceph_object_locator oloc;
 };
 
 /*
- * osd request identifier
+ * OSD request identifier metadata: Uniquely identifies a request across
+ * the cluster by combining client identity, incarnation, and transaction ID.
+ * Used for request deduplication and tracking.
  *
- * caller name + incarnation# + tid to unique identify this request
+ * Format: caller name + incarnation# + tid to uniquely identify this request
  */
 struct ceph_osd_reqid {
+	/* Client entity name (type + number) */
 	struct ceph_entity_name name;
+	/* Transaction ID */
 	__le64 tid;
+	/* Client incarnation number */
 	__le32 inc;
 } __packed;
 
+/*
+ * Blkin tracing metadata: Distributed tracing information for performance
+ * analysis and debugging. Compatible with Zipkin/Jaeger tracing systems.
+ */
 struct ceph_blkin_trace_info {
+	/* Unique trace identifier */
 	__le64 trace_id;
+	/* Span identifier within the trace */
 	__le64 span_id;
+	/* Parent span identifier */
 	__le64 parent_span_id;
 } __packed;
 
+/*
+ * Watch notification callback: Called when a watched object receives a notification.
+ * Provides the notification data and identifies the notifier.
+ */
 typedef void (*rados_watchcb2_t)(void *arg, u64 notify_id, u64 cookie,
 				 u64 notifier_id, void *data, size_t data_len);
+/*
+ * Watch error callback: Called when a watch encounters an error condition
+ * such as connection loss or object deletion.
+ */
 typedef void (*rados_watcherrcb_t)(void *arg, u64 cookie, int err);
 
+/*
+ * Long-running OSD request metadata: Represents watch and notify operations
+ * that persist beyond normal request completion. Handles connection recovery
+ * and maintains state for ongoing object monitoring.
+ */
 struct ceph_osd_linger_request {
+	/* Parent OSD client */
 	struct ceph_osd_client *osdc;
+	/* Unique linger request identifier */
 	u64 linger_id;
+	/* Registration has been committed */
 	bool committed;
-	bool is_watch;                  /* watch or notify */
+	/* True for watch, false for notify */
+	bool is_watch;
 
+	/* Target OSD for this linger request */
 	struct ceph_osd *osd;
+	/* Registration request */
 	struct ceph_osd_request *reg_req;
+	/* Keepalive ping request */
 	struct ceph_osd_request *ping_req;
+	/* When last ping was sent */
 	unsigned long ping_sent;
+	/* Watch validity expiration time */
 	unsigned long watch_valid_thru;
+	/* List of pending linger work items */
 	struct list_head pending_lworks;
 
+	/* Target object and placement information */
 	struct ceph_osd_request_target t;
+	/* Map epoch bound for "does not exist" errors */
 	u32 map_dne_bound;
 
+	/* Modification time */
 	struct timespec64 mtime;
 
+	/* Reference counting for safe cleanup */
 	struct kref kref;
+	/* Serializes linger request operations */
 	struct mutex lock;
-	struct rb_node node;            /* osd */
-	struct rb_node osdc_node;       /* osdc */
-	struct rb_node mc_node;         /* map check */
+	/* Red-black tree node in OSD's linger tree */
+	struct rb_node node;
+	/* Red-black tree node in OSDC's linger tree */
+	struct rb_node osdc_node;
+	/* Red-black tree node in map check tree */
+	struct rb_node mc_node;
+	/* List item for scanning operations */
 	struct list_head scan_item;
 
+	/* Completion synchronization */
 	struct completion reg_commit_wait;
 	struct completion notify_finish_wait;
+	/* Error codes */
 	int reg_commit_error;
 	int notify_finish_error;
 	int last_error;
 
+	/* Registration generation number */
 	u32 register_gen;
+	/* Notification identifier */
 	u64 notify_id;
 
+	/* Callback functions */
 	rados_watchcb2_t wcb;
 	rados_watcherrcb_t errcb;
+	/* Callback context data */
 	void *data;
 
+	/* Request data structures */
 	struct ceph_pagelist *request_pl;
 	struct page **notify_id_pages;
 
+	/* Reply handling */
 	struct page ***preply_pages;
 	size_t *preply_len;
 };
 
+/*
+ * Watch item metadata: Describes a single watcher on an object,
+ * including the client identity and network address.
+ */
 struct ceph_watch_item {
+	/* Watcher client entity name */
 	struct ceph_entity_name name;
+	/* Unique watch cookie */
 	u64 cookie;
+	/* Watcher's network address */
 	struct ceph_entity_addr addr;
 };
 
+/*
+ * Sharded placement group mapping metadata: Maps a sharded placement group
+ * to its associated backoff requests. Used for managing flow control when
+ * OSDs request clients to back off from certain operations.
+ */
 struct ceph_spg_mapping {
+	/* Red-black tree node for efficient lookup */
 	struct rb_node node;
+	/* Sharded placement group identifier */
 	struct ceph_spg spgid;
 
+	/* Tree of backoff requests for this PG */
 	struct rb_root backoffs;
 };
 
+/*
+ * RADOS object identifier metadata: Complete identification of an object
+ * in the RADOS system, including pool, namespace, name, and snapshot.
+ * Used for precise object addressing and comparison operations.
+ */
 struct ceph_hobject_id {
+	/* Object key for special objects */
 	void *key;
 	size_t key_len;
+	/* Object identifier string */
 	void *oid;
 	size_t oid_len;
+	/* Snapshot identifier */
 	u64 snapid;
+	/* Object hash value for placement */
 	u32 hash;
+	/* Maximum object marker */
 	u8 is_max;
+	/* Object namespace */
 	void *nspace;
 	size_t nspace_len;
+	/* Pool identifier */
 	s64 pool;
 
-	/* cache */
+	/* Cached bit-reversed hash for efficient comparisons */
 	u32 hash_reverse_bits;
 };
 
@@ -387,51 +651,88 @@ static inline void ceph_hoid_build_hash_cache(struct ceph_hobject_id *hoid)
 }
 
 /*
- * PG-wide backoff: [begin, end)
- * per-object backoff: begin == end
+ * OSD backoff metadata: Represents a request from an OSD for the client
+ * to temporarily cease operations on a range of objects. Used for flow
+ * control during recovery, rebalancing, or overload conditions.
+ *
+ * PG-wide backoff: [begin, end) covers a range
+ * per-object backoff: begin == end covers single object
  */
 struct ceph_osd_backoff {
+	/* Red-black tree node indexed by PG */
 	struct rb_node spg_node;
+	/* Red-black tree node indexed by backoff ID */
 	struct rb_node id_node;
 
+	/* Sharded placement group this backoff applies to */
 	struct ceph_spg spgid;
+	/* Unique backoff identifier */
 	u64 id;
+	/* Beginning of object range (inclusive) */
 	struct ceph_hobject_id *begin;
+	/* End of object range (exclusive) */
 	struct ceph_hobject_id *end;
 };
 
 #define CEPH_LINGER_ID_START	0xffff000000000000ULL
 
+/*
+ * OSD client metadata: Main interface for communicating with Ceph OSDs.
+ * Manages OSD connections, request routing, map updates, and provides
+ * high-level APIs for object operations, watches, and notifications.
+ */
 struct ceph_osd_client {
+	/* Parent Ceph client instance */
 	struct ceph_client     *client;
 
-	struct ceph_osdmap     *osdmap;       /* current map */
+	/* Current OSD cluster map */
+	struct ceph_osdmap     *osdmap;
+	/* Protects OSD client state */
 	struct rw_semaphore    lock;
 
-	struct rb_root         osds;          /* osds */
-	struct list_head       osd_lru;       /* idle osds */
+	/* Tree of active OSD connections */
+	struct rb_root         osds;
+	/* LRU list of idle OSD connections */
+	struct list_head       osd_lru;
+	/* Protects OSD LRU operations */
 	spinlock_t             osd_lru_lock;
+	/* Minimum map epoch for request processing */
 	u32		       epoch_barrier;
+	/* Placeholder OSD for unmapped requests */
 	struct ceph_osd        homeless_osd;
-	atomic64_t             last_tid;      /* tid of last request */
+	/* Last transaction ID assigned */
+	atomic64_t             last_tid;
+	/* Last linger request ID assigned */
 	u64                    last_linger_id;
-	struct rb_root         linger_requests; /* lingering requests */
+	/* Tree of active linger requests */
+	struct rb_root         linger_requests;
+	/* Requests pending map check */
 	struct rb_root         map_checks;
+	/* Linger requests pending map check */
 	struct rb_root         linger_map_checks;
+	/* Total number of active requests */
 	atomic_t               num_requests;
+	/* Number of homeless (unmapped) requests */
 	atomic_t               num_homeless;
+	/* Error code for aborting all requests */
 	int                    abort_err;
+	/* Work item for request timeout processing */
 	struct delayed_work    timeout_work;
+	/* Work item for OSD connection timeouts */
 	struct delayed_work    osds_timeout_work;
 #ifdef CONFIG_DEBUG_FS
+	/* Debug filesystem entry for monitoring */
 	struct dentry 	       *debugfs_file;
 #endif
 
+	/* Memory pool for request allocation */
 	mempool_t              *req_mempool;
 
+	/* Message pools for efficient memory management */
 	struct ceph_msgpool	msgpool_op;
 	struct ceph_msgpool	msgpool_op_reply;
 
+	/* Work queues for async processing */
 	struct workqueue_struct	*notify_wq;
 	struct workqueue_struct	*completion_wq;
 };
-- 
2.51.0

[RFC PATCH 15/20] ceph: add comments to metadata structures in osdmap.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_pg,
struct ceph_spg, struct ceph_pg_pool_info,
struct ceph_object_locator, struct ceph_object_id,
struct workspace_manager, struct ceph_pg_mapping,
struct ceph_osdmap, struct ceph_osds, struct crush_loc,
struct crush_loc_node in /include/linux/ceph/osdmap.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/osdmap.h | 124 ++++++++++++++++++++++++++++++++++--
 1 file changed, 118 insertions(+), 6 deletions(-)

diff --git a/include/linux/ceph/osdmap.h b/include/linux/ceph/osdmap.h
index 5553019c3f07..51ca13d18364 100644
--- a/include/linux/ceph/osdmap.h
+++ b/include/linux/ceph/osdmap.h
@@ -19,15 +19,29 @@
  * The map can be updated either via an incremental map (diff) describing
  * the change between two successive epochs, or as a fully encoded map.
  */
+/*
+ * Placement group identifier metadata: Identifies a placement group within
+ * the RADOS system. PGs group objects together for replication and distribution
+ * across OSDs using a deterministic mapping based on pool and placement seed.
+ */
 struct ceph_pg {
+	/* Pool identifier this PG belongs to */
 	uint64_t pool;
+	/* Placement seed for object distribution within the pool */
 	uint32_t seed;
 };
 
 #define CEPH_SPG_NOSHARD	-1
 
+/*
+ * Sharded placement group metadata: Extends placement group identification
+ * with shard information for erasure-coded pools. Each PG can be split
+ * into multiple shards for parallel processing and distribution.
+ */
 struct ceph_spg {
+	/* Base placement group identifier */
 	struct ceph_pg pgid;
+	/* Shard number within the PG (CEPH_SPG_NOSHARD for replicated pools) */
 	s8 shard;
 };
 
@@ -41,22 +55,42 @@ int ceph_spg_compare(const struct ceph_spg *lhs, const struct ceph_spg *rhs);
 							will set FULL too */
 #define CEPH_POOL_FLAG_NEARFULL		(1ULL << 11) /* pool is nearfull */
 
+/*
+ * Pool information metadata: Complete description of a RADOS storage pool
+ * including replication settings, placement group configuration, and tiering
+ * information. Contains all parameters needed for object placement decisions.
+ */
 struct ceph_pg_pool_info {
+	/* Red-black tree node for efficient lookup */
 	struct rb_node node;
+	/* Unique pool identifier */
 	s64 id;
+	/* Pool type (replicated, erasure-coded) */
 	u8 type; /* CEPH_POOL_TYPE_* */
+	/* Number of replicas or erasure coding width */
 	u8 size;
+	/* Minimum replicas required for I/O */
 	u8 min_size;
+	/* CRUSH rule for object placement */
 	u8 crush_ruleset;
+	/* Hash function for object name hashing */
 	u8 object_hash;
+	/* Last epoch when force resend was required */
 	u32 last_force_request_resend;
+	/* Number of placement groups and placement groups for placement */
 	u32 pg_num, pgp_num;
+	/* Bitmasks derived from pg_num and pgp_num */
 	int pg_num_mask, pgp_num_mask;
+	/* Read tier pool (for cache tiering) */
 	s64 read_tier;
+	/* Write tier pool (takes precedence for read+write) */
 	s64 write_tier; /* wins for read+write ops */
+	/* Pool status and behavior flags */
 	u64 flags; /* CEPH_POOL_FLAG_* */
+	/* Human-readable pool name */
 	char *name;
 
+	/* Previous full state (for map change handling) */
 	bool was_full;  /* for handle_one_map() */
 };
 
@@ -72,8 +106,15 @@ static inline bool ceph_can_shift_osds(struct ceph_pg_pool_info *pool)
 	}
 }
 
+/*
+ * Object locator metadata: Specifies the storage location for an object
+ * within the RADOS cluster. Combines pool identification with optional
+ * namespace for fine-grained object organization.
+ */
 struct ceph_object_locator {
+	/* Target pool ID (-1 for unspecified) */
 	s64 pool;
+	/* Optional namespace within the pool */
 	struct ceph_string *pool_ns;
 };
 
@@ -106,10 +147,17 @@ void ceph_oloc_destroy(struct ceph_object_locator *oloc);
  * Both inline and external buffers have space for a NUL-terminator,
  * which is carried around.  It's not required though - RADOS object
  * names don't have to be NUL-terminated and may contain NULs.
+ *
+ * Object identifier metadata: Flexible object naming with inline optimization.
+ * Uses inline storage for short names (common case) and dynamic allocation
+ * for longer names. Supports arbitrary byte sequences including NUL bytes.
  */
 struct ceph_object_id {
+	/* Pointer to object name (may point to inline_name) */
 	char *name;
+	/* Inline storage for short object names */
 	char inline_name[CEPH_OID_INLINE_LEN];
+	/* Length of object name in bytes */
 	int name_len;
 };
 
@@ -137,64 +185,105 @@ int ceph_oid_aprintf(struct ceph_object_id *oid, gfp_t gfp,
 		     const char *fmt, ...);
 void ceph_oid_destroy(struct ceph_object_id *oid);
 
+/*
+ * Workspace manager metadata: Manages a pool of compression workspaces
+ * for CRUSH map processing. Provides efficient allocation and reuse of
+ * workspaces to avoid frequent memory allocation during map calculations.
+ */
 struct workspace_manager {
+	/* List of idle workspaces ready for use */
 	struct list_head idle_ws;
+	/* Spinlock protecting workspace list operations */
 	spinlock_t ws_lock;
-	/* Number of free workspaces */
+	/* Number of free workspaces available */
 	int free_ws;
 	/* Total number of allocated workspaces */
 	atomic_t total_ws;
-	/* Waiters for a free workspace */
+	/* Wait queue for threads waiting for free workspace */
 	wait_queue_head_t ws_wait;
 };
 
+/*
+ * Placement group mapping override metadata: Allows administrators to override
+ * the default CRUSH-generated OSD mappings for specific placement groups.
+ * Supports various override types for operational flexibility.
+ */
 struct ceph_pg_mapping {
+	/* Red-black tree node for efficient lookup */
 	struct rb_node node;
+	/* Placement group this mapping applies to */
 	struct ceph_pg pgid;
 
+	/* Different types of mapping overrides */
 	union {
+		/* Temporary OSD set override */
 		struct {
+			/* Number of OSDs in override set */
 			int len;
+			/* Array of OSD IDs */
 			int osds[];
 		} pg_temp, pg_upmap;
+		/* Temporary primary OSD override */
 		struct {
+			/* Primary OSD ID */
 			int osd;
 		} primary_temp;
+		/* Item-by-item OSD remapping */
 		struct {
+			/* Number of from->to mappings */
 			int len;
+			/* Array of [from_osd, to_osd] pairs */
 			int from_to[][2];
 		} pg_upmap_items;
 	};
 };
 
+/*
+ * OSD cluster map metadata: Complete description of the RADOS cluster topology
+ * and configuration. Contains all information needed to locate objects, determine
+ * OSD health, and route requests. Updated with each cluster state change.
+ */
 struct ceph_osdmap {
+	/* Cluster filesystem identifier */
 	struct ceph_fsid fsid;
+	/* Map version number (monotonically increasing) */
 	u32 epoch;
+	/* Timestamps for map creation and modification */
 	struct ceph_timespec created, modified;
 
+	/* Global cluster flags */
 	u32 flags;         /* CEPH_OSDMAP_* */
 
+	/* OSD array size and state information */
 	u32 max_osd;       /* size of osd_state, _offload, _addr arrays */
+	/* Per-OSD state flags (exists, up, etc.) */
 	u32 *osd_state;    /* CEPH_OSD_* */
-	u32 *osd_weight;   /* 0 = failed, 0x10000 = 100% normal */
+	/* Per-OSD weight (0=failed, 0x10000=100% normal) */
+	u32 *osd_weight;
+	/* Per-OSD network addresses */
 	struct ceph_entity_addr *osd_addr;
 
+	/* Temporary PG to OSD mappings */
 	struct rb_root pg_temp;
 	struct rb_root primary_temp;
 
-	/* remap (post-CRUSH, pre-up) */
+	/* Post-CRUSH, pre-up remappings for load balancing */
 	struct rb_root pg_upmap;	/* PG := raw set */
 	struct rb_root pg_upmap_items;	/* from -> to within raw set */
 
+	/* Per-OSD primary affinity weights */
 	u32 *osd_primary_affinity;
 
+	/* Storage pool definitions */
 	struct rb_root pg_pools;
 	u32 pool_max;
 
-	/* the CRUSH map specifies the mapping of placement groups to
+	/* CRUSH map for object placement calculations.
+	 * The CRUSH map specifies the mapping of placement groups to
 	 * the list of osds that store+replicate them. */
 	struct crush_map *crush;
 
+	/* Workspace manager for CRUSH calculations */
 	struct workspace_manager crush_wsm;
 };
 
@@ -256,9 +345,17 @@ struct ceph_osdmap *osdmap_apply_incremental(void **p, void *end, bool msgr2,
 					     struct ceph_osdmap *map);
 extern void ceph_osdmap_destroy(struct ceph_osdmap *map);
 
+/*
+ * OSD set metadata: Represents a set of OSDs that store replicas of a
+ * placement group. Contains the ordered list of OSDs and identifies
+ * the primary OSD responsible for coordinating operations.
+ */
 struct ceph_osds {
+	/* Array of OSD IDs in preference order */
 	int osds[CEPH_PG_MAX_SIZE];
+	/* Number of OSDs in the set */
 	int size;
+	/* Primary OSD ID (not array index) */
 	int primary; /* id, NOT index */
 };
 
@@ -312,14 +409,29 @@ bool ceph_pg_to_primary_shard(struct ceph_osdmap *osdmap,
 int ceph_pg_to_acting_primary(struct ceph_osdmap *osdmap,
 			      const struct ceph_pg *raw_pgid);
 
+/*
+ * CRUSH location constraint metadata: Specifies a location constraint
+ * for CRUSH map placement. Used to restrict object placement to specific
+ * parts of the cluster hierarchy (e.g., specific racks, hosts).
+ */
 struct crush_loc {
+	/* CRUSH hierarchy level type (e.g., "rack", "host") */
 	char *cl_type_name;
+	/* Name of the specific location within that type */
 	char *cl_name;
 };
 
+/*
+ * CRUSH location node metadata: Red-black tree node for efficient storage
+ * and lookup of CRUSH location constraints. Contains the location data
+ * inline for memory efficiency.
+ */
 struct crush_loc_node {
+	/* Red-black tree linkage */
 	struct rb_node cl_node;
-	struct crush_loc cl_loc;  /* pointers into cl_data */
+	/* Location constraint (pointers into cl_data) */
+	struct crush_loc cl_loc;
+	/* Inline storage for location strings */
 	char cl_data[];
 };
 
-- 
2.51.0

[RFC PATCH 16/20] ceph: add comments to metadata structures in pagelist.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_pagelist
in /include/linux/ceph/pagelist.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/pagelist.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/include/linux/ceph/pagelist.h b/include/linux/ceph/pagelist.h
index 879bec0863aa..1954366ea71b 100644
--- a/include/linux/ceph/pagelist.h
+++ b/include/linux/ceph/pagelist.h
@@ -7,13 +7,26 @@
 #include <linux/list.h>
 #include <linux/types.h>
 
+/*
+ * Page list container metadata: Manages a list of memory pages for efficient
+ * data serialization and transmission. Provides append-only interface with
+ * automatic page allocation, reference counting, and optimized tail access
+ * for building large data structures without memory copies.
+ */
 struct ceph_pagelist {
+	/* Linked list of allocated pages containing data */
 	struct list_head head;
+	/* Memory mapping of current tail page for efficient appends */
 	void *mapped_tail;
+	/* Total data length across all pages */
 	size_t length;
+	/* Available space remaining in current tail page */
 	size_t room;
+	/* List of pre-allocated pages available for future use */
 	struct list_head free_list;
+	/* Count of pages in the free list */
 	size_t num_pages_free;
+	/* Reference count for safe sharing and cleanup */
 	refcount_t refcnt;
 };
 
-- 
2.51.0

[RFC PATCH 17/20] ceph: add comments to metadata structures in rados.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_fsid,
struct ceph_timespec, struct ceph_pg_v1,
struct ceph_object_layout, struct ceph_eversion,
struct ceph_osd_op in /include/linux/ceph/rados.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/rados.h | 91 ++++++++++++++++++++++++++++++++------
 1 file changed, 77 insertions(+), 14 deletions(-)

diff --git a/include/linux/ceph/rados.h b/include/linux/ceph/rados.h
index 73c3efbec36c..1850ef439bf6 100644
--- a/include/linux/ceph/rados.h
+++ b/include/linux/ceph/rados.h
@@ -10,9 +10,12 @@
 #include <linux/ceph/msgr.h>
 
 /*
- * fs id
+ * Filesystem identifier metadata: Unique 128-bit identifier for a Ceph cluster.
+ * All clients and daemons in the same cluster share this FSID, used to prevent
+ * accidental cross-cluster communication and data corruption.
  */
 struct ceph_fsid {
+	/* 16-byte unique cluster identifier */
 	unsigned char fsid[16];
 };
 
@@ -30,8 +33,15 @@ typedef __le64 ceph_snapid_t;
 #define CEPH_NOSNAP  ((__u64)(-2))  /* "head", "live" revision */
 #define CEPH_MAXSNAP ((__u64)(-3))  /* largest valid snapid */
 
+/*
+ * RADOS timespec metadata: Network-endian time representation used in
+ * RADOS protocol messages. Provides nanosecond precision timestamps
+ * for object modification times and other temporal data.
+ */
 struct ceph_timespec {
+	/* Seconds since Unix epoch (little-endian) */
 	__le32 tv_sec;
+	/* Nanoseconds within the second (little-endian) */
 	__le32 tv_nsec;
 } __attribute__ ((packed));
 
@@ -54,13 +64,17 @@ struct ceph_timespec {
 #define CEPH_PG_MAX_SIZE      32  /* max # osds in a single pg */
 
 /*
- * placement group.
- * we encode this into one __le64.
+ * Placement group identifier (version 1): Identifies a placement group within
+ * the RADOS system. PGs group objects together for replication and distribution.
+ * This version is encoded into a single __le64 for efficient storage and comparison.
  */
 struct ceph_pg_v1 {
-	__le16 preferred; /* preferred primary osd */
-	__le16 ps;        /* placement seed */
-	__le32 pool;      /* object pool */
+	/* Preferred primary OSD for this PG */
+	__le16 preferred;
+	/* Placement seed for object distribution */
+	__le16 ps;
+	/* Pool identifier this PG belongs to */
+	__le32 pool;
 } __attribute__ ((packed));
 
 /*
@@ -104,18 +118,26 @@ static inline int ceph_stable_mod(int x, int b, int bmask)
 }
 
 /*
- * object layout - how a given object should be stored.
+ * Object layout metadata: Describes how a specific object should be stored
+ * and distributed within the RADOS cluster. Contains placement group mapping
+ * and striping information for optimal data distribution.
  */
 struct ceph_object_layout {
-	struct ceph_pg_v1 ol_pgid;   /* raw pg, with _full_ ps precision. */
-	__le32 ol_stripe_unit;    /* for per-object parity, if any */
+	/* Raw placement group ID with full placement seed precision */
+	struct ceph_pg_v1 ol_pgid;
+	/* Stripe unit size for per-object parity (erasure coding) */
+	__le32 ol_stripe_unit;
 } __attribute__ ((packed));
 
 /*
- * compound epoch+version, used by storage layer to serialize mutations
+ * Extended version metadata: Compound epoch and version number used by the
+ * storage layer to serialize mutations and ensure consistency. Combines
+ * cluster-wide epoch with object-specific version for total ordering.
  */
 struct ceph_eversion {
+	/* Object version number within the epoch */
 	__le64 version;
+	/* Cluster epoch number (map generation) */
 	__le32 epoch;
 } __attribute__ ((packed));
 
@@ -484,61 +506,101 @@ enum {
 };
 
 /*
- * an individual object operation.  each may be accompanied by some data
- * payload
+ * Individual OSD operation metadata: Wire format for a single operation within
+ * an OSD request. Each operation may be accompanied by data payload and contains
+ * operation-specific parameters in a discriminated union.
  */
 struct ceph_osd_op {
-	__le16 op;           /* CEPH_OSD_OP_* */
-	__le32 flags;        /* CEPH_OSD_OP_FLAG_* */
+	/* Operation type code (CEPH_OSD_OP_*) */
+	__le16 op;
+	/* Operation-specific flags (CEPH_OSD_OP_FLAG_*) */
+	__le32 flags;
+	/* Operation-specific parameters */
 	union {
+		/* Extent-based operations (read, write, truncate) */
 		struct {
+			/* Byte offset and length within object */
 			__le64 offset, length;
+			/* Truncation parameters */
 			__le64 truncate_size;
 			__le32 truncate_seq;
 		} __attribute__ ((packed)) extent;
+		/* Extended attribute operations */
 		struct {
+			/* Attribute name and value lengths */
 			__le32 name_len;
 			__le32 value_len;
+			/* Comparison operation type */
 			__u8 cmp_op;       /* CEPH_OSD_CMPXATTR_OP_* */
+			/* Comparison mode (string/numeric) */
 			__u8 cmp_mode;     /* CEPH_OSD_CMPXATTR_MODE_* */
 		} __attribute__ ((packed)) xattr;
+		/* Object class method invocation */
 		struct {
+			/* Class and method name lengths */
 			__u8 class_len;
 			__u8 method_len;
+			/* Number of method arguments */
 			__u8 argc;
+			/* Input data length */
 			__le32 indata_len;
 		} __attribute__ ((packed)) cls;
+		/* Placement group listing */
 		struct {
+			/* Listing cookie and count */
 			__le64 cookie, count;
 		} __attribute__ ((packed)) pgls;
+		/* Snapshot operations */
 	        struct {
+			/* Snapshot identifier */
 		        __le64 snapid;
 	        } __attribute__ ((packed)) snap;
+		/* Watch/notify operations */
 		struct {
+			/* Unique watch cookie */
 			__le64 cookie;
+			/* Version (deprecated) */
 			__le64 ver;     /* no longer used */
+			/* Watch operation type */
 			__u8 op;	/* CEPH_OSD_WATCH_OP_* */
+			/* Watch generation number */
 			__le32 gen;     /* registration generation */
 		} __attribute__ ((packed)) watch;
+		/* Notification operations */
 		struct {
+			/* Notification cookie */
 			__le64 cookie;
 		} __attribute__ ((packed)) notify;
+		/* Version assertion */
 		struct {
+			/* Unused field */
 			__le64 unused;
+			/* Expected version */
 			__le64 ver;
 		} __attribute__ ((packed)) assert_ver;
+		/* Object cloning operations */
 		struct {
+			/* Destination offset and length */
 			__le64 offset, length;
+			/* Source offset */
 			__le64 src_offset;
 		} __attribute__ ((packed)) clonerange;
+		/* Allocation hints for object sizing */
 		struct {
+			/* Expected final object size */
 			__le64 expected_object_size;
+			/* Expected write size */
 			__le64 expected_write_size;
+			/* Allocation hint flags */
 			__le32 flags;  /* CEPH_OSD_OP_ALLOC_HINT_FLAG_* */
 		} __attribute__ ((packed)) alloc_hint;
+		/* Copy from another object */
 		struct {
+			/* Source snapshot ID */
 			__le64 snapid;
+			/* Source object version */
 			__le64 src_version;
+			/* Copy operation flags */
 			__u8 flags; /* CEPH_OSD_COPY_FROM_FLAG_* */
 			/*
 			 * CEPH_OSD_OP_FLAG_FADVISE_*: fadvise flags
@@ -548,6 +610,7 @@ struct ceph_osd_op {
 			__le32 src_fadvise_flags;
 		} __attribute__ ((packed)) copy_from;
 	};
+	/* Length of accompanying data payload */
 	__le32 payload_len;
 } __attribute__ ((packed));
 
-- 
2.51.0

[RFC PATCH 18/20] ceph: add comments to metadata structures in string_table.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_string
in /include/linux/ceph/string_table.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/string_table.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/include/linux/ceph/string_table.h b/include/linux/ceph/string_table.h
index a4a9962d1e14..ac75feb58007 100644
--- a/include/linux/ceph/string_table.h
+++ b/include/linux/ceph/string_table.h
@@ -7,13 +7,24 @@
 #include <linux/rbtree.h>
 #include <linux/rcupdate.h>
 
+/*
+ * Reference-counted string metadata: Interned string with automatic memory
+ * management and deduplication. Uses red-black tree for efficient lookup and
+ * RCU for safe concurrent access. Strings are immutable and shared across
+ * multiple users to reduce memory usage.
+ */
 struct ceph_string {
+	/* Reference counting for automatic cleanup */
 	struct kref kref;
 	union {
+		/* Red-black tree node for string table lookup */
 		struct rb_node node;
+		/* RCU head for safe deferred cleanup */
 		struct rcu_head rcu;
 	};
+	/* Length of the string in bytes */
 	size_t len;
+	/* Variable-length string data (NUL-terminated) */
 	char str[];
 };
 
-- 
2.51.0

Re: [RFC PATCH 18/20] ceph: add comments to metadata structures in string_table.h

[Max Kellermann]

On 2025/09/05 22:01, Viacheslav Dubeyko <slava@dubeyko.com> wrote:
> +/*
> + * Reference-counted string metadata: Interned string with automatic memory
> + * management and deduplication. Uses red-black tree for efficient lookup and
> + * RCU for safe concurrent access. Strings are immutable and shared across
> + * multiple users to reduce memory usage.
> + */

No, it doesn't use rbtree AND rcu.  It uses rbtree OR rcu - it's a
union, it cannot use both.  But when does it use one or the other?
That would have been helpful to know.

>  struct ceph_string {
> +	/* Reference counting for automatic cleanup */
>  	struct kref kref;

In the other patch, you wrote that reference counting is "for safe
shared access", and now it's "for automatic cleanup".  But it's really
neither.  Reference counters do not do automatic cleanup.  They are a
tool to be able to detect when the last reference is dropped.  And
then you can do the cleanup.  But that is not automatic.  You have to
implement it manually for eac use of struct kref.

This comment is confusing and adds no value.

>  	union {
> +		/* Red-black tree node for string table lookup */
>  		struct rb_node node;
> +		/* RCU head for safe deferred cleanup */
>  		struct rcu_head rcu;

These two comments add no value, they don't explain anything that
isn't already obvious from looking at the struct types.  Explaining
that "rb_node" is a "Red-black tree node" is just noise that doesn't
belong here; if anything, it belongs to the rbtree_node documentation.
Repeating such text everywhere has a negative impact on people's time.

>  	};
> +	/* Length of the string in bytes */
>  	size_t len;
> +	/* Variable-length string data (NUL-terminated) */
>  	char str[];

The "[]" and the "NUL-terminated" and the "len" field already imply
that it's variable-length.  Writing this again is just noise.

[RFC PATCH 19/20] ceph: add comments to metadata structures in striper.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_object_extent,
struct ceph_file_extent in /include/linux/ceph/striper.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/striper.h | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/include/linux/ceph/striper.h b/include/linux/ceph/striper.h
index 3486636c0e6e..b59c055ce562 100644
--- a/include/linux/ceph/striper.h
+++ b/include/linux/ceph/striper.h
@@ -11,10 +11,19 @@ void ceph_calc_file_object_mapping(struct ceph_file_layout *l,
 				   u64 off, u64 len,
 				   u64 *objno, u64 *objoff, u32 *xlen);
 
+/*
+ * Object extent metadata: Represents a contiguous range within a RADOS object
+ * that maps to part of a file. Used by the striping layer to break file I/O
+ * operations into object-level operations distributed across the cluster.
+ */
 struct ceph_object_extent {
+	/* Linkage for lists of extents */
 	struct list_head oe_item;
+	/* RADOS object number containing this extent */
 	u64 oe_objno;
+	/* Byte offset within the object */
 	u64 oe_off;
+	/* Length of the extent in bytes */
 	u64 oe_len;
 };
 
@@ -44,8 +53,15 @@ int ceph_iterate_extents(struct ceph_file_layout *l, u64 off, u64 len,
 			 ceph_object_extent_fn_t action_fn,
 			 void *action_arg);
 
+/*
+ * File extent metadata: Represents a contiguous range within a file.
+ * Used to describe logical file ranges that correspond to object extents
+ * after stripe mapping calculations.
+ */
 struct ceph_file_extent {
+	/* Byte offset within the file */
 	u64 fe_off;
+	/* Length of the extent in bytes */
 	u64 fe_len;
 };
 
-- 
2.51.0

[RFC PATCH 20/20] ceph: add comments to metadata structures in types.h

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

We have a lot of declarations and not enough good
comments on it.

Claude AI generated comments for CephFS metadata structure
declarations in include/linux/ceph/*.h. These comments
have been reviewed, checked, and corrected.

This patch adds comments for struct ceph_vino,
struct ceph_cap_reservation in /include/linux/ceph/types.h.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
cc: Alex Markuze <amarkuze@redhat.com>
cc: Ilya Dryomov <idryomov@gmail.com>
cc: Ceph Development <ceph-devel@vger.kernel.org>
---
 include/linux/ceph/types.h | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/include/linux/ceph/types.h b/include/linux/ceph/types.h
index bd3d532902d7..beda96d2c872 100644
--- a/include/linux/ceph/types.h
+++ b/include/linux/ceph/types.h
@@ -13,17 +13,27 @@
 #include <linux/ceph/ceph_hash.h>
 
 /*
- * Identify inodes by both their ino AND snapshot id (a u64).
+ * Virtual inode identifier metadata: Uniquely identifies an inode within
+ * the CephFS namespace by combining the inode number with a snapshot ID.
+ * This allows the same inode to exist in multiple snapshots simultaneously.
  */
 struct ceph_vino {
+	/* Inode number within the filesystem */
 	u64 ino;
+	/* Snapshot ID (CEPH_NOSNAP for head/live version) */
 	u64 snap;
 };
 
 
-/* context for the caps reservation mechanism */
+/*
+ * Capability reservation context metadata: Tracks reserved capabilities
+ * for atomic operations that require multiple caps. Prevents deadlocks
+ * by pre-reserving the required capabilities before starting operations.
+ */
 struct ceph_cap_reservation {
+	/* Total number of capabilities reserved */
 	int count;
+	/* Number of reserved capabilities already consumed */
 	int used;
 };
 
-- 
2.51.0