LU-4975 ofd: documenting ofd_lvb.c

Fix up GPL header block to reference proper GPLv2 license URL.
Remove mention of contacting Sun, since they don't exist anymore.
Add introductory comment block for the ofd_lvb.c file and add
function comment blocks to all functions in it.

Signed-off-by: Mikhail Pershin <mike.pershin@intel.com>
Change-Id: Ic80fc32d62c2accab3b774d6587a27621c469a6e
Reviewed-on: http://review.whamcloud.com/10854
Tested-by: Jenkins
Reviewed-by: Ned Bass <bass6@llnl.gov>
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>

diff --git a/lustre/ofd/ofd_lvb.c b/lustre/ofd/ofd_lvb.c
index 3105174..9da0300 100644 (file)
--- a/lustre/ofd/ofd_lvb.c
+++ b/lustre/ofd/ofd_lvb.c
@@ -15,11 +15,7 @@
  *
  * You should have received a copy of the GNU General Public License
  * version 2 along with this program; If not, see
- * http://www.sun.com/software/products/lustre/docs/GPLv2.pdf
- *
- * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
- * CA 95054 USA or visit www.sun.com if you need additional information or
- * have any questions.
+ * http://www.gnu.org/licenses/gpl-2.0.html
  *
  * GPL HEADER END
  */
@@ -27,7 +23,7 @@
  * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
  * Use is subject to license terms.
  *
- * Copyright (c) 2012, 2013, Intel Corporation.
+ * Copyright (c) 2012, 2014 Intel Corporation.
  */
 /*
  * This file is part of Lustre, http://www.lustre.org/
@@ -35,14 +31,33 @@
  *
  * lustre/ofd/ofd_lvb.c
  *
- * Author: Mikhail Pershin <tappro@whamcloud.com>
- * Author: Alexey Zhuravlev <bzzz@whamcloud.com>
+ * This file contains methods for OBD Filter Device (OFD)
+ * Lock Value Block (LVB) operations.
+ *
+ * LVB is special opaque (to LDLM) data that is associated with an LDLM lock
+ * and transferred from client to server and back. OFD LVBs are used to
+ * maintain current object size/times.
+ *
+ * Author: Andreas Dilger <andreas.dilger@intel.com>
+ * Author: Mikhail Pershin <mike.pershin@intel.com>
+ * Author: Alexey Zhuravlev <alexey.zhuravlev@intel.com>
  */
 
 #define DEBUG_SUBSYSTEM S_FILTER
 
 #include "ofd_internal.h"
 
+/**
+ * Implementation of ldlm_valblock_ops::lvbo_free for OFD.
+ *
+ * This function frees allocated LVB data if it associated with the given
+ * LDLM resource.
+ *
+ * \param[in] res      LDLM resource
+ *
+ * \retval             0 on successful setup
+ * \retval             negative value on error
+ */
 static int ofd_lvbo_free(struct ldlm_resource *res)
 {
        if (res->lr_lvb_data)
@@ -51,7 +66,21 @@ static int ofd_lvbo_free(struct ldlm_resource *res)
        return 0;
 }
 
-/* Called with res->lr_lvb_sem held */
+/**
+ * Implementation of ldlm_valblock_ops::lvbo_init for OFD.
+ *
+ * This function allocates and initializes new LVB data for the given
+ * LDLM resource if it is not allocated yet. New LVB is filled with attributes
+ * of the object associated with that resource. Function does nothing if LVB
+ * for the given LDLM resource is allocated already.
+ *
+ * Called with res->lr_lvb_sem held.
+ *
+ * \param[in] res      LDLM resource
+ *
+ * \retval             0 on successful setup
+ * \retval             negative value on error
+ */
 static int ofd_lvbo_init(struct ldlm_resource *res)
 {
        struct ost_lvb          *lvb;
@@ -120,12 +149,34 @@ out_env:
        return rc;
 }
 
-/* This will be called in two ways:
+/**
+ * Implementation of ldlm_valblock_ops::lvbo_update for OFD.
+ *
+ * When a client generates a glimpse enqueue, it wants to get the current
+ * file size and updated attributes for a stat() type operation, but these
+ * attributes may be writeback cached on another client. The client with
+ * the DLM extent lock at the highest offset is asked for its current
+ * attributes via a glimpse callback on its extent lock, on the assumption
+ * that it has the highest file size and the newest timestamps. The timestamps
+ * are guaranteed to be correct if there is only a single writer on the file,
+ * but may be slightly inaccurate if there are multiple concurrent writers on
+ * the same object. In order to avoid race conditions between the glimpse AST
+ * and the client cancelling the lock, ofd_lvbo_update() also updates
+ * the attributes from the local object. If the last client hasn't done any
+ * writes yet, or has already written its data and cancelled its lock before
+ * it processed the glimpse, then the local inode will have more uptodate
+ * information.
+ *
+ * This is called in two ways:
+ *  \a req != NULL : called by the DLM itself after a glimpse callback
+ *  \a req == NULL : called by the OFD after a disk write
  *
- *   r != NULL : called by the DLM itself after a glimpse callback
- *   r == NULL : called by the ofd after a disk write
+ * \param[in] res              LDLM resource
+ * \param[in] req              PTLRPC request
+ * \param[in] increase_only    don't allow LVB values to decrease
  *
- *   If 'increase_only' is true, don't allow values to move backwards.
+ * \retval             0 on successful setup
+ * \retval             negative value on error
  */
 static int ofd_lvbo_update(struct ldlm_resource *res,
                           struct ptlrpc_request *req, int increase_only)
@@ -276,6 +327,17 @@ out_env:
        return rc;
 }
 
+/**
+ * Implementation of ldlm_valblock_ops::lvbo_size for OFD.
+ *
+ * This function returns size of LVB data so appropriate RPC size will be
+ * reserved. This is used for compatibility needs between server and client
+ * of different Lustre versions.
+ *
+ * \param[in] lock     LDLM lock
+ *
+ * \retval             size of LVB data
+ */
 static int ofd_lvbo_size(struct ldlm_lock *lock)
 {
        if (lock->l_export != NULL && exp_connect_lvb_type(lock->l_export))
@@ -284,6 +346,17 @@ static int ofd_lvbo_size(struct ldlm_lock *lock)
                return sizeof(struct ost_lvb_v1);
 }
 
+/**
+ * Implementation of ldlm_valblock_ops::lvbo_fill for OFD.
+ *
+ * This function is called to fill the given RPC buffer \a buf with LVB data
+ *
+ * \param[in] lock     LDLM lock
+ * \param[in] buf      RPC buffer to fill
+ * \param[in] buflen   buffer length
+ *
+ * \retval             size of LVB data written into \a buf buffer
+ */
 static int ofd_lvbo_fill(struct ldlm_lock *lock, void *buf, int buflen)
 {
        struct ldlm_resource *res = lock->l_resource;