[PATCH] Better document some regset helper functions

[PATCH] Better document some regset helper functions

[David Howells]

Better document some regset helper functions, namely user_regset_copyout() and
user_regset_copyin().

Signed-off-by: David Howells <dhowells@redhat.com>
---

 include/linux/regset.h |   77 +++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 69 insertions(+), 8 deletions(-)


diff --git a/include/linux/regset.h b/include/linux/regset.h
index 8abee65..ad67cb2 100644
--- a/include/linux/regset.h
+++ b/include/linux/regset.h
@@ -205,17 +205,48 @@ const struct user_regset_view *task_user_regset_view(struct task_struct *tsk);
 
 
 /*
- * These are helpers for writing regset get/set functions in arch code.
- * Because @start_pos and @end_pos are always compile-time constants,
- * these are inlined into very little code though they look large.
+ * The following functions are helpers for writing regset get/set functions in
+ * arch code.  Because @start_pos and @end_pos are always compile-time
+ * constants, these are inlined into very little code though they look large.
  *
- * Use one or more calls sequentially for each chunk of regset data stored
- * contiguously in memory.  Call with constants for @start_pos and @end_pos,
- * giving the range of byte positions in the regset that data corresponds
- * to; @end_pos can be -1 if this chunk is at the end of the regset layout.
- * Each call updates the arguments to point past its chunk.
+ * Use one or more calls sequentially for each subset of the regset data that
+ * is stored contiguously in memory.  Call with constants for @start_pos and
+ * @end_pos, giving the range of byte positions in the regset that @data
+ * corresponds to; @end_pos can be -1 if this subset is at the end of the
+ * regset layout.  Each call updates the arguments to point past its chunk.
  */
 
+/**
+ * user_regset_copyout - Retrieve data from a subset of a register set
+ * @pos:	The running position to retrieve from in the register set
+ * @count:	The running amount of data left to retrieve
+ * @kbuf:	The running kernel buffer pointer to write into (or NULL)
+ * @ubuf:	The running user buffer pointer to write into (if !*kbuf)
+ * @data:	Where the data for this subset of the register set is held
+ * @start_pos:	The offset at which this subset begins in the register set
+ * @end_pos:	The offset at which this subset ends in the register set
+ *
+ * This helper function can be called upon to retrieve the data from a subset
+ * of a register set and store it either into a kernel buffer or into a
+ * userspace buffer.
+ *
+ * The data subset being offered for retrieval by the caller is an array of
+ * @end_pos-@start_pos bytes at the @data pointer.
+ *
+ * The data subset requested for retrieval is an array of *@count bytes,
+ * beginning at *@pos bytes into the register set.
+ *
+ * If the requested subset overlaps the offered subset, then some data will be
+ * copied into the appropriate buffer, and the *@pos, *@count and the
+ * appropriate buffer pointer will be updated to reflect the amount remaining
+ * to be copied.  This allows subsequent calls to this function to cascade
+ * automatically.
+ *
+ * If the two subsets do not overlap, then no copy is made, and the running
+ * parameters are not altered.
+ *
+ * This function returns 0 if successful, and a -ve error code on error.
+ */
 static inline int user_regset_copyout(unsigned int *pos, unsigned int *count,
 				      void **kbuf,
 				      void __user **ubuf, const void *data,
@@ -241,6 +272,36 @@ static inline int user_regset_copyout(unsigned int *pos, unsigned int *count,
 	return 0;
 }
 
+/**
+ * user_regset_copyin - Store data into a subset of a register set
+ * @pos:	The running position to store to in the register set
+ * @count:	The running amount of data left to store
+ * @kbuf:	The running kernel buffer pointer to read from (or NULL)
+ * @ubuf:	The running user buffer pointer to read from (if !*kbuf)
+ * @data:	Where the data for this subset of the register set is help
+ * @start_pos:	The offset at which this subset begins in the register set
+ * @end_pos:	The offset at which this subset ends in the register set
+ *
+ * This helper function can be called upon to update the data in a subset of a
+ * register set from data either in a kernel buffer or in a userspace buffer.
+ *
+ * The data subset being offered for update by the caller is an array of
+ * @end_pos-@start_pos bytes at the @data pointer.
+ *
+ * The data subset requested to be updated is an array of *@count bytes,
+ * beginning at *@pos bytes into the register set.
+ *
+ * If the requested subset overlaps the offered subset, then some data will be
+ * copied from the appropriate buffer, and the *@pos, *@count and the
+ * appropriate buffer pointer will be updated to reflect the amount remaining
+ * to be copied.  This allows subsequent calls to this function to cascade
+ * automatically.
+ *
+ * If the two subsets do not overlap, then no copy is made, and the running
+ * parameters are not altered.
+ *
+ * This function returns 0 if successful, and a -ve error code on error.
+ */
 static inline int user_regset_copyin(unsigned int *pos, unsigned int *count,
 				     const void **kbuf,
 				     const void __user **ubuf, void *data,

Re: [PATCH] Better document some regset helper functions

[Roland McGrath]

I'm all for better comments and your text looks fine to me.

The reason I had not used kerneldoc comments for those helpers is that
these are the private helpers purely for the use of arch code implementing
user_regset accessor functions.  By contrast, the calls in linux/regset.h
that have kerneldoc comments are those that generic code (including future
modules, etc.) uses.  When generating DocBook or man pages, the regset.h
functions are grouped together and those that have kerneldoc today make
sense to have there, but IMHO these inline helpers for arch code do not.


Thanks,
Roland