From: Viacheslav Dubeyko <Slava.Dubeyko@xxxxxxx>
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@xxxxxxx>
cc: Alex Markuze <amarkuze@xxxxxxxxxx>
cc: Ilya Dryomov <idryomov@xxxxxxxxx>
cc: Ceph Development <ceph-devel@xxxxxxxxxxxxxxx>
---
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
