Branch HEAD

b=14010
i=Mike Pershin (tappro)
i=Andreas Dilger (adilger)

Doxygen comments (the missing ones)

diff --git a/lustre/include/obd_class.h b/lustre/include/obd_class.h
index d734870..324fa1f 100644 (file)
--- a/lustre/include/obd_class.h
+++ b/lustre/include/obd_class.h
@@ -1212,6 +1212,29 @@ static inline  int obd_prep_async_page(struct obd_export *exp,
         RETURN(ret);
 }
 
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp obd export (lov or osc)
+ * \param lsm striping information for the file
+ * \param res async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ * \retval -ENOTSUPP reget_short_lock is not exported at this layer
+ *
+ * \see obd_release_short_lock
+ */
 static inline int obd_reget_short_lock(struct obd_export *exp,
                                        struct lov_stripe_md *lsm,
                                        void **res, int rw,
@@ -1227,6 +1250,24 @@ static inline int obd_reget_short_lock(struct obd_export *exp,
                                                    start, end, cookie));
 }
 
+
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp obd export (lov or osc)
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see obd_reget_short_lock
+ */
 static inline int obd_release_short_lock(struct obd_export *exp,
                                          struct lov_stripe_md *lsm, obd_off end,
                                          void *cookie, int rw)

diff --git a/lustre/ldlm/ldlm_lock.c b/lustre/ldlm/ldlm_lock.c
index dfe1a17..6aa3953 100644 (file)
--- a/lustre/ldlm/ldlm_lock.c
+++ b/lustre/ldlm/ldlm_lock.c
@@ -919,6 +919,26 @@ void ldlm_lock_allow_match(struct ldlm_lock *lock)
         unlock_res_and_lock(lock);
 }
 
+/**
+ * Checks if requested extent lock is compatible with another owned lock.
+ *
+ * Checks if \a lock is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param lock the already owned lock
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ldlm_lock_fast_release
+ */
 int ldlm_lock_fast_match(struct ldlm_lock *lock, int rw,
                          obd_off start, obd_off end,
                          void **cookie)
@@ -936,6 +956,20 @@ int ldlm_lock_fast_match(struct ldlm_lock *lock, int rw,
         return 0;
 }
 
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ldlm_lock_fast_lock
+ */
 void ldlm_lock_fast_release(void *cookie, int rw)
 {
         struct ldlm_lock *lock = (struct ldlm_lock *)cookie;

diff --git a/lustre/llite/file.c b/lustre/llite/file.c
index 41f2723..9d90d51 100644 (file)
--- a/lustre/llite/file.c
+++ b/lustre/llite/file.c
@@ -1347,6 +1347,27 @@ out:
         return rc;
 }
 
+/**
+ * Checks if requested extent lock is compatible with a lock under a page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param page the page under which lock is considered
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ll_release_short_lock
+ */
 static int ll_reget_short_lock(struct page *page, int rw,
                                obd_off start, obd_off end,
                                void **cookie)
@@ -1370,6 +1391,22 @@ static int ll_reget_short_lock(struct page *page, int rw,
                                     cookie));
 }
 
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_reget_short_lock
+ */
 static void ll_release_short_lock(struct inode *inode, obd_off end,
                                   void *cookie, int rw)
 {
@@ -1386,6 +1423,29 @@ static void ll_release_short_lock(struct inode *inode, obd_off end,
                 CERROR("unlock failed (%d)\n", rc);
 }
 
+/**
+ * Checks if requested extent lock is compatible
+ * with a lock under a page in page cache.
+ *
+ * Checks if a lock under some \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param file the file under which lock is considered
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param ppos start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ * \param buf userspace buffer for the data
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced
+ * \post retuls == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ll_file_put_fast_lock
+ */
 static inline int ll_file_get_fast_lock(struct file *file,
                                         obd_off ppos, obd_off end,
                                         char *buf, void **cookie, int rw)
@@ -1410,6 +1470,22 @@ static inline int ll_file_get_fast_lock(struct file *file,
         RETURN(rc);
 }
 
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_file_get_fast_lock
+ */
 static inline void ll_file_put_fast_lock(struct inode *inode, obd_off end,
                                          void *cookie, int rw)
 {
@@ -1422,6 +1498,29 @@ enum ll_lock_style {
         LL_LOCK_STYLE_TREELOCK = 2
 };
 
+/**
+ * Checks if requested extent lock is compatible with a lock 
+ * under a page cache page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param file file under which I/O is processed
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param ppos start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *           (only used with LL_LOCK_STYLE_FASTLOCK)
+ * \param tree lock tree (only used with LL_LOCK_STYLE_TREELOCK)
+ * \param buf userspace buffer for the data
+ *
+ * \retval LL_LOCK_STYLE_FASTLOCK owned lock is reused through fast lock
+ * \retval LL_LOCK_STYLE_TREELOCK got a lock through tree lock
+ * \retval LL_LOCK_STYLE_NOLOCK got no lock
+ *
+ * \see ll_file_put_lock
+ */
 static inline int ll_file_get_lock(struct file *file, obd_off ppos,
                                    obd_off end, char *buf, void **cookie,
                                    struct ll_lock_tree *tree, int rw)
@@ -1446,6 +1545,25 @@ static inline int ll_file_get_lock(struct file *file, obd_off ppos,
         RETURN(rc);
 }
 
+/**
+ * Drops the lock taken by ll_file_get_lock.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a tree or \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param lockstyle facility through which the lock was taken
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *           (only used with LL_LOCK_STYLE_FASTLOCK)
+ * \param tree lock tree (only used with LL_LOCK_STYLE_TREELOCK)
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_file_get_lock
+ */
 static inline void ll_file_put_lock(struct inode *inode, obd_off end,
                                     enum ll_lock_style lock_style,
                                     void *cookie, struct ll_lock_tree *tree,

diff --git a/lustre/lov/lov_obd.c b/lustre/lov/lov_obd.c
index b4b4263..3c8de91 100644 (file)
--- a/lustre/lov/lov_obd.c
+++ b/lustre/lov/lov_obd.c
@@ -2832,6 +2832,29 @@ void lov_stripe_unlock(struct lov_stripe_md *md)
 }
 EXPORT_SYMBOL(lov_stripe_unlock);
 
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp lov export
+ * \param lsm striping information for the file
+ * \param res lov_async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see lov_release_short_lock
+ */
 static int lov_reget_short_lock(struct obd_export *exp,
                                 struct lov_stripe_md *lsm,
                                 void **res, int rw,
@@ -2858,6 +2881,23 @@ static int lov_reget_short_lock(struct obd_export *exp,
                                     rw, stripe_start, stripe_end, cookie));
 }
 
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp lov export
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see lov_reget_short_lock
+ */
 static int lov_release_short_lock(struct obd_export *exp,
                                   struct lov_stripe_md *lsm, obd_off end,
                                   void *cookie, int rw)

diff --git a/lustre/osc/osc_request.c b/lustre/osc/osc_request.c
index 24f7530..ec59eb9 100644 (file)
--- a/lustre/osc/osc_request.c
+++ b/lustre/osc/osc_request.c
@@ -2554,6 +2554,29 @@ static int osc_enter_cache(struct client_obd *cli, struct lov_oinfo *loi,
         RETURN(-EDQUOT);
 }
 
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp osc export
+ * \param lsm striping information for the file
+ * \param res osc_async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see osc_release_short_lock
+ */
 static int osc_reget_short_lock(struct obd_export *exp,
                                 struct lov_stripe_md *lsm,
                                 void **res, int rw,
@@ -2573,6 +2596,23 @@ static int osc_reget_short_lock(struct obd_export *exp,
         RETURN(rc);
 }
 
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp osc export
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ *           OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see osc_reget_short_lock
+ */
 static int osc_release_short_lock(struct obd_export *exp,
                                   struct lov_stripe_md *lsm, obd_off end,
                                   void *cookie, int rw)