From: Mikhail Pershin Date: Thu, 26 Jun 2014 18:43:51 +0000 (+0400) Subject: LU-4975 ofd: documenting ofd_lvb.c X-Git-Tag: 2.6.51~50 X-Git-Url: https://git.whamcloud.com/?p=fs%2Flustre-release.git;a=commitdiff_plain;h=2b44b8b015574645a3bea7219f2dba117e7a5bf6 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 Change-Id: Ic80fc32d62c2accab3b774d6587a27621c469a6e Reviewed-on: http://review.whamcloud.com/10854 Tested-by: Jenkins Reviewed-by: Ned Bass Tested-by: Maloo Reviewed-by: Andreas Dilger --- diff --git a/lustre/ofd/ofd_lvb.c b/lustre/ofd/ofd_lvb.c index 3105174..9da0300 100644 --- 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 - * Author: Alexey Zhuravlev + * 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 + * Author: Mikhail Pershin + * Author: Alexey Zhuravlev */ #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;