[PVFS2-CVS]
commit by rbross in pvfs2/src/kernel/linux-2.6: downcall.h file.c
pvfs2-kernel.h waitqueue.c
CVS commit program
cvs at parl.clemson.edu
Tue Jan 11 12:24:19 EST 2005
Update of /projects/cvsroot/pvfs2/src/kernel/linux-2.6
In directory parlweb:/tmp/cvs-serv32014/src/kernel/linux-2.6
Modified Files:
downcall.h file.c pvfs2-kernel.h waitqueue.c
Log Message:
More doxygen changes. Working on the kernel code now.
Index: downcall.h
===================================================================
RCS file: /projects/cvsroot/pvfs2/src/kernel/linux-2.6/downcall.h,v
diff -p -u -r1.22 -r1.23
--- downcall.h 3 Dec 2004 19:16:10 -0000 1.22
+++ downcall.h 11 Jan 2005 17:24:18 -0000 1.23
@@ -4,6 +4,11 @@
* See COPYING in top-level directory.
*/
+/** \file
+ * \ingroup pvfs2linux
+ *
+ * Definitions of downcalls used in Linux kernel module.
+ */
/* TODO: we might want to try to avoid this inclusion */
#include "pvfs2-sysint.h"
Index: file.c
===================================================================
RCS file: /projects/cvsroot/pvfs2/src/kernel/linux-2.6/file.c,v
diff -p -u -r1.88 -r1.89
--- file.c 3 Dec 2004 19:16:10 -0000 1.88
+++ file.c 11 Jan 2005 17:24:18 -0000 1.89
@@ -4,6 +4,12 @@
* See COPYING in top-level directory.
*/
+/** \file
+ * \ingroup pvfs2linux
+ *
+ * Linux VFS file operations.
+ */
+
#include "pvfs2-kernel.h"
#include "pvfs2-bufmap.h"
@@ -24,6 +30,8 @@ do {
} while(0)
+/** Called when a process requests to open a file.
+ */
int pvfs2_file_open(
struct inode *inode,
struct file *file)
@@ -74,6 +82,9 @@ int pvfs2_file_open(
return ret;
}
+/** Read data from a specified offset in a file (referenced by inode).
+ * Data may be placed either in a user or kernel buffer.
+ */
ssize_t pvfs2_inode_read(
struct inode *inode,
char __user *buf,
@@ -211,6 +222,8 @@ ssize_t pvfs2_inode_read(
return(total_count);
}
+/** Read data from a specified offset in a file into a user buffer.
+ */
ssize_t pvfs2_file_read(
struct file *file,
char __user *buf,
@@ -225,6 +238,9 @@ ssize_t pvfs2_file_read(
file->f_dentry->d_inode, buf, count, offset, 1, 0);
}
+/** Write data from a contiguous user buffer into a file at a specified
+ * offset.
+ */
static ssize_t pvfs2_file_write(
struct file *file,
const char __user *buf,
@@ -356,6 +372,8 @@ static ssize_t pvfs2_file_write(
return total_count;
}
+/** Perform a miscellaneous operation on a file.
+ */
int pvfs2_ioctl(
struct inode *inode,
struct file *file,
@@ -368,6 +386,8 @@ int pvfs2_ioctl(
return ret;
}
+/** Memory map a region of a file.
+ */
static int pvfs2_file_mmap(struct file *file, struct vm_area_struct *vma)
{
struct inode *inode = file->f_dentry->d_inode;
@@ -404,10 +424,11 @@ static int pvfs2_file_mmap(struct file *
#endif
}
-/*
- NOTE: gets called when all files are closed. not when
- each file is closed. (i.e. last reference to an opened file)
-*/
+/** Called to notify the module that there are no more references to
+ * this file (i.e. no processes have it open).
+ *
+ * \note Not called when each file is closed.
+ */
int pvfs2_file_release(
struct inode *inode,
struct file *file)
@@ -436,6 +457,8 @@ int pvfs2_file_release(
return 0;
}
+/** Push all data for a specific file onto permanent storage.
+ */
int pvfs2_fsync(
struct file *file,
struct dentry *dentry,
@@ -470,10 +493,11 @@ int pvfs2_fsync(
return ret;
}
-/*
- NOTE: if .llseek is overriden, we must acquire lock as described in
- Documentation/filesystems/Locking
-*/
+/** Change the file pointer position for an instance of an open file.
+ *
+ * \note If .llseek is overriden, we must acquire lock as described in
+ * Documentation/filesystems/Locking.
+ */
loff_t pvfs2_file_llseek(struct file *file, loff_t offset, int origin)
{
int ret = -EINVAL;
@@ -503,6 +527,7 @@ loff_t pvfs2_file_llseek(struct file *fi
return generic_file_llseek(file, offset, origin);
}
+/** PVFS2 implementation of VFS file operations */
struct file_operations pvfs2_file_operations =
{
#ifdef PVFS2_LINUX_KERNEL_2_4
Index: pvfs2-kernel.h
===================================================================
RCS file: /projects/cvsroot/pvfs2/src/kernel/linux-2.6/pvfs2-kernel.h,v
diff -p -u -r1.83 -r1.84
--- pvfs2-kernel.h 3 Dec 2004 19:16:10 -0000 1.83
+++ pvfs2-kernel.h 11 Jan 2005 17:24:19 -0000 1.84
@@ -4,6 +4,19 @@
* See COPYING in top-level directory.
*/
+/** \defgroup pvfs2linux PVFS2 Linux kernel support
+ *
+ * The PVFS2 Linux kernel support allows PVFS2 volumes to be mounted and
+ * accessed through the Linux VFS (i.e. using standard I/O system calls).
+ * This support is only needed on clients that wish to mount the file system.
+ *
+ * @{
+ */
+
+/** \file
+ * Declarations and macros for the PVFS2 Linux kernel support.
+ */
+
#ifndef __PVFS2KERNEL_H
#define __PVFS2KERNEL_H
@@ -199,7 +212,7 @@ typedef struct
struct list_head list;
} pvfs2_kernel_op_t;
-/* per inode private pvfs2 info */
+/** per inode private pvfs2 info */
typedef struct
{
PVFS_object_ref refn;
@@ -216,19 +229,18 @@ typedef struct
sector_t last_failed_block_index_read;
} pvfs2_inode_t;
-/*
- these are the available mount options that we accept:
-
- the intr option (if set) is inspired by the nfs intr option that
- interrupts the operation in progress if a signal is received, and
- ignores the signal otherwise (if not set).
-*/
+/** mount options. only accepted mount options are listed.
+ */
typedef struct
{
+ /** intr option (if set) is inspired by the nfs intr option that
+ * interrupts the operation in progress if a signal is received,
+ * and ignores the signal otherwise (if not set).
+ */
int intr;
} pvfs2_mount_options_t;
-/* per superblock private pvfs2 info */
+/** per superblock private pvfs2 info */
typedef struct
{
PVFS_handle root_handle;
@@ -242,10 +254,9 @@ typedef struct
struct list_head list;
} pvfs2_sb_info_t;
-/*
- a temporary structure used only for sb mount time that groups the
- mount time data provided along with a private superblock structure
- that is allocated before a 'kernel' superblock is allocated.
+/** a temporary structure used only for sb mount time that groups the
+ * mount time data provided along with a private superblock structure
+ * that is allocated before a 'kernel' superblock is allocated.
*/
typedef struct
{
@@ -549,10 +560,9 @@ do {
} \
} while(0)
-/*
- tries to service the operation and will retry on timeout
- failure up to num times (num MUST be a numeric lvalue).
-*/
+/** tries to service the operation and will retry on timeout
+ * failure up to num times (num MUST be a numeric lvalue).
+ */
#define service_operation_with_timeout_retry(op, method, num, intr)\
do { \
sigset_t orig_sigset; \
@@ -582,16 +592,15 @@ do {
} \
} while(0)
-/*
- tries to service the operation and will retry on timeout
- failure up to num times (num MUST be a numeric lvalue).
-
- this allows us to know if we've reached the error_exit code path
- from here or elsewhere
-
- NOTE: used in namei.c:lookup, file.c:pvfs2_inode_read, and
- file.c:pvfs2_file_write
-*/
+/** tries to service the operation and will retry on timeout
+ * failure up to num times (num MUST be a numeric lvalue).
+ *
+ * this allows us to know if we've reached the error_exit code path
+ * from here or elsewhere
+ *
+ * \note used in namei.c:lookup, file.c:pvfs2_inode_read, and
+ * file.c:pvfs2_file_write
+ */
#define service_error_exit_op_with_timeout_retry(op,meth,num,e,intr)\
do { \
sigset_t orig_sigset; \
@@ -622,27 +631,26 @@ do {
} \
} while(0)
-/*
- by design, our vfs i/o errors need to be handled in one of two ways,
- depending on where the error occured.
-
- if the error happens in the waitqueue code because we either timed
- out or a signal was raised while waiting, we need to cancel the
- userspace i/o operation and free the op manually. this is done to
- avoid having the device start writing application data to our shared
- bufmap pages without us expecting it.
-
- if a pvfs2 sysint level error occured and i/o has been completed,
- there is no need to cancel the operation, as the user has finished
- using the bufmap page and so there is no danger in this case. in
- this case, we wake up the device normally so that it may free the
- op, as normal.
-
- this macro handles both of these cases, depending on which error
- happened based on information known in context. the only reason
- this is a macro is because both read and write cases need the exact
- same handling code.
-*/
+/** handles two possible error cases, depending on context.
+ *
+ * by design, our vfs i/o errors need to be handled in one of two ways,
+ * depending on where the error occured.
+ *
+ * if the error happens in the waitqueue code because we either timed
+ * out or a signal was raised while waiting, we need to cancel the
+ * userspace i/o operation and free the op manually. this is done to
+ * avoid having the device start writing application data to our shared
+ * bufmap pages without us expecting it.
+ *
+ * if a pvfs2 sysint level error occured and i/o has been completed,
+ * there is no need to cancel the operation, as the user has finished
+ * using the bufmap page and so there is no danger in this case. in
+ * this case, we wake up the device normally so that it may free the
+ * op, as normal.
+ *
+ * \note the only reason this is a macro is because both read and write
+ * cases need the exact same handling code.
+ */
#define handle_io_error() \
do { \
if (error_exit) \
@@ -869,6 +877,8 @@ static inline ino_t parent_ino(struct de
#endif /* __PVFS2KERNEL_H */
+
+/* @} */
/*
* Local variables:
Index: waitqueue.c
===================================================================
RCS file: /projects/cvsroot/pvfs2/src/kernel/linux-2.6/waitqueue.c,v
diff -p -u -r1.14 -r1.15
--- waitqueue.c 25 Aug 2004 16:42:03 -0000 1.14
+++ waitqueue.c 11 Jan 2005 17:24:19 -0000 1.15
@@ -4,6 +4,12 @@
* See COPYING in top-level directory.
*/
+/** \file
+ * \ingroup pvfs2linux
+ *
+ * In-kernel waitqueue operations.
+ */
+
#include "pvfs2-kernel.h"
extern struct list_head pvfs2_request_list;
@@ -49,26 +55,23 @@ static inline void clean_up_interrupted_
spin_unlock(&op->lock);
}
-/*
- sleeps on waitqueue waiting for matching downcall for some amount of
- time and then wakes up.
-
- NOTE: when this call returns to the caller, the specified op will no
- longer be on any list or htable.
-
- return values and op status changes:
-
- PVFS2_WAIT_ERROR
- - an error occurred; op status unknown
- PVFS2_WAIT_SUCCESS
- - success; everything ok. the op state will be marked as serviced
- PVFS2_WAIT_TIMEOUT_REACHED
- - timeout reached (before downcall recv'd) the caller has the
- choice of either requeueing the op or failing the operation when
- this occurs. the op observes no state change.
- PVFS2_WAIT_SIGNAL_RECVD
- - sleep interrupted (signal recv'd) the op observes no state
- change.
+/** sleeps on waitqueue waiting for matching downcall for some amount of
+ * time and then wakes up.
+ *
+ * \post when this call returns to the caller, the specified op will no
+ * longer be on any list or htable.
+ *
+ * \return values and op status changes:
+ *
+ * \retval PVFS2_WAIT_ERROR an error occurred; op status unknown
+ * \retval PVFS2_WAIT_SUCCESS success; everything ok. the op state will
+ * be marked as serviced
+ * \retval PVFS2_WAIT_TIMEOUT_REACHED timeout reached (before downcall
+ * recv'd) the caller has the choice of either requeueing the op
+ * or failing the operation when this occurs. the op observes no
+ * state change.
+ * \retval PVFS2_WAIT_SIGNAL_RECVD sleep interrupted (signal recv'd) the
+ * op observes no state change.
*/
int wait_for_matching_downcall(pvfs2_kernel_op_t * op)
{
@@ -122,13 +125,13 @@ int wait_for_matching_downcall(pvfs2_ker
return ret;
}
-/*
- similar to the wait above, however used in the special case of I/O
- cancellations. we need a special wait function because if this is
- called we already know that a signal is pending in current and need
- to service the cancellation upcall anyway. the only way to exit
- this is to either timeout or have the cancellation be serviced
- properly.
+/** similar to wait_for_matching_downcall(), but used in the special case
+ * of I/O cancellations.
+ *
+ * \note we need a special wait function because if this is called we already
+ * know that a signal is pending in current and need to service the
+ * cancellation upcall anyway. the only way to exit this is to either
+ * timeout or have the cancellation be serviced properly.
*/
int wait_for_cancellation_downcall(pvfs2_kernel_op_t * op)
{
More information about the PVFS2-CVS
mailing list