add more comments for MDAPI DLD

diff --git a/lustre/include/linux/dt_object.h b/lustre/include/linux/dt_object.h
index c58d390..70918ef 100644 (file)
--- a/lustre/include/linux/dt_object.h
+++ b/lustre/include/linux/dt_object.h
@@ -31,7 +31,7 @@
  * implement some form of garbage collection, normally reference counting
  * (nlink) based one.
  *
- * Examples: osd (lustre/osd) is am implementation of dt interface.
+ * Examples: osd (lustre/osd) is an implementation of dt interface.
  */
 
 
@@ -68,6 +68,8 @@ struct dt_device_operations {
         /*
          * Method for getting/setting device wide back stored config data,
          * like last used meta-sequence, etc.
+         *
+         * XXX this is ioctl()-like interface we want to get rid of.
          */
         int (*dt_config) (struct lu_context *ctx,
                           struct dt_device *dev, const char *name,
@@ -92,50 +94,108 @@ struct dt_device_operations {
          */
         int   (*dt_root_get)(struct lu_context *ctx,
                              struct dt_device *dev, struct lu_fid *f);
-
+        /*
+         * Create new object on this device.
+         *
+         * postcondition: ergo(result == 0,
+         *                     dt->do_lu.lo_ops->loo_object_exists(ctxt,
+         *                                                         &dt->do_lu));
+         */
         int   (*dt_object_create)(struct lu_context *ctxt, struct dt_object *dt,
                                   struct md_params *arg, struct thandle *th);
-
+        /*
+         * Destroy existing object.
+         *
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*dt_object_destroy)(struct lu_context *ctxt,
                                    struct dt_object *dt, struct thandle *th);
 
 };
 
+/*
+ * Per-dt-object operations.
+ */
 struct dt_object_operations {
         void  (*do_object_lock)(struct lu_context *ctx,
                                 struct dt_object *dt, enum dt_lock_mode mode);
         void  (*do_object_unlock)(struct lu_context *ctx,
                                   struct dt_object *dt, enum dt_lock_mode mode);
+        /*
+         * Note: following ->do_{x,}attr_{set,get}() operations are very
+         * similar to ->moo_{x,}attr_{set,get}() operations in struct
+         * md_object_operations (see md_object.h). These operations are not in
+         * lu_object_operations, because ->do_{x,}attr_set() versions take
+         * transaction handle as an argument (this transaction is started by
+         * caller). We might factor ->do_{x,}attr_get() into
+         * lu_object_operations, but that would break existing symmetry.
+         */
 
+        /*
+         * Return standard attributes.
+         *
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*do_attr_get)(struct lu_context *ctxt, struct dt_object *dt,
                              struct lu_attr *attr);
+        /*
+         * Set standard attributes.
+         *
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*do_attr_set)(struct lu_context *ctxt, struct dt_object *dt,
                              struct lu_attr *attr, struct thandle *handle);
-
+        /*
+         * Return a value of an extended attribute.
+         *
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*do_xattr_get)(struct lu_context *ctxt, struct dt_object *dt,
                               void *buf, int buf_len, const char *name,
                               struct md_params *arg);
-
+        /*
+         * Set value of an extended attribute.
+         *
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*do_xattr_set)(struct lu_context *ctxt, struct dt_object *dt,
                               void *buf, int buf_len, const char *name,
                               struct md_params *arg, struct thandle *handle);
-
 };
 
+/*
+ * Per-dt-object operations on "file body".
+ */
 struct dt_body_operations {
+        /*
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int (*dbo_read)(struct lu_context *ctxt, struct dt_object *dt, ...);
+        /*
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int (*dbo_write)(struct lu_context *ctxt, struct dt_object *dt, ...);
+        /*
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int (*dbo_truncate)(struct lu_context *ctxt, struct dt_object *dt, ...);
-        int (*dbo_seek)(struct lu_context *ctxt, struct dt_object *dt, ...);
 };
 
+/*
+ * Per-dt-object operations on object as index.
+ */
 struct dt_index_operations {
+        /*
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*dio_index_insert)(struct lu_context *ctxt,
                                   struct dt_object *dt,
                                   struct lu_fid *fid, const char *name,
                                   struct md_params *arg,
                                   struct thandle *handle);
-
+        /*
+         * precondition: dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu);
+         */
         int   (*dio_index_delete)(struct lu_context *ctxt,
                                   struct dt_object *dt,
                                   struct lu_fid *fid, const char *name,

diff --git a/lustre/include/linux/lu_object.h b/lustre/include/linux/lu_object.h
index 8983297..452b451 100644 (file)
--- a/lustre/include/linux/lu_object.h
+++ b/lustre/include/linux/lu_object.h
@@ -158,12 +158,17 @@ struct lu_device_operations {
         */
        void (*ldo_object_release)(struct lu_context *ctx, struct lu_object *o);
 
-        /* process config specific for device */
+        /*
+         * process config specific for device
+         */
         int  (*ldo_process_config)(struct lu_device *, struct lustre_cfg *);
 
 };
 
 struct lu_object_operations {
+        /*
+         * Return true off object @o exists on a storage.
+         */
         int (*loo_object_exists)(struct lu_context *ctx, struct lu_object *o);
        /*
         * Debugging helper. Print given object.
@@ -500,7 +505,9 @@ static inline struct lu_object *lu_object_top(struct lu_object_header *h)
 }
 
 /*
- * Acquire additional reference to the given object
+ * Acquire additional reference to the given object. This function is used to
+ * attain additional reference. To acquire initial reference use
+ * lu_object_find().
  */
 static inline void lu_object_get(struct lu_object *o)
 {
@@ -578,12 +585,6 @@ struct lu_context {
          */
         __u32                  lc_tags;
         /*
-         * Object attribute. This is stuffed directly into context, because we
-         * know it advance it will be needed. As an alternative, it can be
-         * allocated through special key.
-         */
-        struct lu_attr         lc_attr;
-        /*
          * Pointer to the home service thread. NULL for other execution
          * contexts.
          */

diff --git a/lustre/include/linux/md_object.h b/lustre/include/linux/md_object.h
index 4870f22..50aa01d 100644 (file)
--- a/lustre/include/linux/md_object.h
+++ b/lustre/include/linux/md_object.h
@@ -25,12 +25,29 @@
 #ifndef _LINUX_MD_OBJECT_H
 #define _LINUX_MD_OBJECT_H
 
+/*
+ * Sub-class of lu_object with methods common for "meta-data" objects in MDT
+ * stack.
+ *
+ * Meta-data objects implement namespace operations: you can link, unlink
+ * them, and treat them as directories.
+ *
+ * Examples: mdt, cmm, and mdt are implementations of md interface.
+ */
+
+
+/*
+ * super-class definitions.
+ */
 #include <linux/lu_object.h>
 
 struct md_device;
 struct md_device_operations;
 struct md_object;
 
+/*
+ * Common parameters for md operations.
+ */
 struct md_params {
         __u32 mode;
         __u32 flags;

diff --git a/lustre/osd/osd_handler.c b/lustre/osd/osd_handler.c
index fb9270b..a823482 100644 (file)
--- a/lustre/osd/osd_handler.c
+++ b/lustre/osd/osd_handler.c
@@ -228,6 +228,7 @@ static int osd_statfs(struct lu_context *ctx,
 static int osd_attr_get(struct lu_context *ctxt, struct dt_object *dt,
                         struct lu_attr *attr)
 {
+        LASSERT(dt->do_lu.lo_ops->loo_object_exists(ctxt, &dt->do_lu));
         return osd_inode_getattr(ctxt, dt2osd_obj(dt)->oo_inode, attr);
 }