docs: s390: unify and update s390dbf kdocs at debug.c

For non-static-inlines, debug.c already had non-compliant function
header docs. So move the pure prototype kdocs of
("s390: include/asm/debug.h add kerneldoc markups")
from debug.h to debug.c and merge them with the old function docs.
Also, I had the impression that kdoc typically is at the implementation
in the compile unit rather than at the prototype in the header file.

While at it, update the short kdoc description to distinguish the
different functions. And a few more consistency cleanups.

Added a new kdoc for debug_set_critical() since debug.h comments it
as part of the API.

Signed-off-by: Steffen Maier <maier@linux.ibm.com>
Acked-by: Christian Borntraeger <borntraeger@de.ibm.com>
Message-Id: <1562149189-1417-3-git-send-email-maier@linux.ibm.com>
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>

3 files changed, 102 insertions, 116 deletions

diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst
index 01d66251643d..be42892b159e 100644
--- a/Documentation/s390/s390dbf.rst
+++ b/Documentation/s390/s390dbf.rst
@@ -107,6 +107,7 @@ will stay deactivated.
 Kernel Interfaces:
 ------------------
 
+.. kernel-doc:: arch/s390/kernel/debug.c
 .. kernel-doc:: arch/s390/include/asm/debug.h
 
 Predefined views:
diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index 02c36eedd780..310134015541 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -95,77 +95,19 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level,
 
 /* Debug Feature API: */
 
-/**
- * debug_register() - allocates memory for a debug log.
- *
- * @name:        Name of debug log (e.g. used for debugfs entry)
- * @pages:       Number of pages, which will be allocated per area
- * @nr_areas:    Number of debug areas
- * @buf_size:    Size of data area in each debug entry
- *
- * Return:
- * - Handler for generated debug area
- * - %NULL if register failed
- *
- * Must not be called within an interrupt handler.
- */
 debug_info_t *debug_register(const char *name, int pages, int nr_areas,
 			     int buf_size);
 
-/**
- * debug_register_mode() - allocates memory for a debug log.
- *
- * @name:	Name of debug log (e.g. used for debugfs entry)
- * @pages:	Number of pages, which will be allocated per area
- * @nr_areas:	Number of debug areas
- * @buf_size:	Size of data area in each debug entry
- * @mode:	File mode for debugfs files. E.g. S_IRWXUGO
- * @uid:	User ID for debugfs files. Currently only 0 is supported.
- * @gid:	Group ID for debugfs files. Currently only 0 is supported.
- *
- * Return:
- * - Handler for generated debug area
- * - %NULL if register failed
- *
- * Must not be called within an interrupt handler
- */
 debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
 				  int buf_size, umode_t mode, uid_t uid,
 				  gid_t gid);
 
-/**
- * debug_unregister() - frees memory for a debug log and removes all
- *			registered debug
- * views.
- *
- * @id:		handle for debug log
- *
- * Return:
- *    none
- *
- * Must not be called within an interrupt handler
- */
 void debug_unregister(debug_info_t *id);
 
-/**
- * debug_set_level() -  Sets new actual debug level if new_level is valid.
- *
- * @id:		handle for debug log
- * @new_level:	new debug level
- *
- * Return:
- *    none
- */
 void debug_set_level(debug_info_t *id, int new_level);
 
 void debug_set_critical(void);
 
-/**
- * debug_stop_all() - stops the debug feature if stopping is allowed.
- *
- * Return:
- * -   none
- */
 void debug_stop_all(void);
 
 /**
@@ -184,7 +126,7 @@ static inline bool debug_level_enabled(debug_info_t *id, int level)
 }
 
 /**
- * debug_event() - writes debug entry to active debug area
+ * debug_event() - writes binary debug entry to active debug area
  *		   (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -194,6 +136,7 @@ static inline bool debug_level_enabled(debug_info_t *id, int level)
  *
  * Return:
  * - Address of written debug entry
+ * - %NULL if error
  */
 static inline debug_entry_t *debug_event(debug_info_t *id, int level,
 					 void *data, int length)
@@ -204,7 +147,7 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_int_event() - writes debug entry to active debug area
+ * debug_int_event() - writes unsigned integer debug entry to active debug area
  *		       (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -226,12 +169,12 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_long_event() - writes debug entry to active debug area
+ * debug_long_event() - writes unsigned long debug entry to active debug area
  *		       (if level <= actual debug level)
  *
  * @id:		handle for debug log
  * @level:	debug level
- * @tag:	integer value for debug entry
+ * @tag:	long integer value for debug entry
  *
  * Return:
  * - Address of written debug entry
@@ -248,7 +191,7 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_text_event() - writes debug entry in ascii format to active
+ * debug_text_event() - writes string debug entry in ascii format to active
  *			debug area (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -306,9 +249,9 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
 })
 
 /**
- * debug_exception() - writes debug entry to active debug area
- *		       (if level <= actual debug level) and switches
- *		       to next debug area
+ * debug_exception() - writes binary debug entry to active debug area
+ *		       (if level <= actual debug level)
+ *		       and switches to next debug area
  *
  * @id:		handle for debug log
  * @level:	debug level
@@ -328,7 +271,7 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
 }
 
 /**
- * debug_int_exception() - writes debug entry to active debug area
+ * debug_int_exception() - writes unsigned int debug entry to active debug area
  *			   (if level <= actual debug level)
  *			   and switches to next debug area
  *
@@ -351,13 +294,13 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
 }
 
 /**
- * debug_long_exception() - writes debug entry to active debug area
+ * debug_long_exception() - writes long debug entry to active debug area
  *			   (if level <= actual debug level)
  *			   and switches to next debug area
  *
  * @id:		handle for debug log
  * @level:	debug level
- * @tag:	integer value for debug entry
+ * @tag:	long integer value for debug entry
  *
  * Return:
  * - Address of written debug entry
@@ -374,9 +317,9 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
 }
 
 /**
- * debug_text_exception() - writes debug entry in ascii format to active
+ * debug_text_exception() - writes string debug entry in ascii format to active
  *			    debug area (if level <= actual debug level)
- *			    and switches to next debug
+ *			    and switches to next debug area
  * area
  *
  * @id:	handle for debug log
@@ -407,7 +350,7 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
 /**
  * debug_sprintf_exception() - writes debug entry with format string and
  *			       varargs (longs) to active debug area
- *			       (if level $<=$ actual debug level)
+ *			       (if level <= actual debug level)
  *			       and switches to next debug area.
  *
  * @_id:	handle for debug log
@@ -435,33 +378,8 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
 	__ret;								\
 })
 
-/**
- * debug_register_view() - registers new debug view and creates debugfs
- *			   dir entry
- *
- * @id:	handle for debug log
- * @view:	pointer to debug view struct
- *
- * Return:
- * -   0  : ok
- * -   < 0: Error
- */
 int debug_register_view(debug_info_t *id, struct debug_view *view);
 
-/**
- * debug_unregister_view()
- *
- * @id:	handle for debug log
- * @view:	pointer to debug view struct
- *
- * Return:
- * -   0  : ok
- * -   < 0: Error
- *
- *
- * unregisters debug view and removes debugfs dir entry
- */
-
 int debug_unregister_view(debug_info_t *id, struct debug_view *view);
 
 /*
diff --git a/arch/s390/kernel/debug.c b/arch/s390/kernel/debug.c
index 0ebf08c3b35e..6d321f5f101d 100644
--- a/arch/s390/kernel/debug.c
+++ b/arch/s390/kernel/debug.c
@@ -647,11 +647,23 @@ static int debug_close(struct inode *inode, struct file *file)
 	return 0; /* success */
 }
 
-/*
- * debug_register_mode:
- * - Creates and initializes debug area for the caller
- *   The mode parameter allows to specify access rights for the s390dbf files
- * - Returns handle for debug area
+/**
+ * debug_register_mode() - creates and initializes debug area.
+ *
+ * @name:	Name of debug log (e.g. used for debugfs entry)
+ * @pages_per_area:	Number of pages, which will be allocated per area
+ * @nr_areas:	Number of debug areas
+ * @buf_size:	Size of data area in each debug entry
+ * @mode:	File mode for debugfs files. E.g. S_IRWXUGO
+ * @uid:	User ID for debugfs files. Currently only 0 is supported.
+ * @gid:	Group ID for debugfs files. Currently only 0 is supported.
+ *
+ * Return:
+ * - Handle for generated debug area
+ * - %NULL if register failed
+ *
+ * Allocates memory for a debug log.
+ * Must not be called within an interrupt handler.
  */
 debug_info_t *debug_register_mode(const char *name, int pages_per_area,
 				  int nr_areas, int buf_size, umode_t mode,
@@ -681,10 +693,21 @@ out:
 }
 EXPORT_SYMBOL(debug_register_mode);
 
-/*
- * debug_register:
- * - creates and initializes debug area for the caller
- * - returns handle for debug area
+/**
+ * debug_register() - creates and initializes debug area with default file mode.
+ *
+ * @name:	Name of debug log (e.g. used for debugfs entry)
+ * @pages_per_area:	Number of pages, which will be allocated per area
+ * @nr_areas:	Number of debug areas
+ * @buf_size:	Size of data area in each debug entry
+ *
+ * Return:
+ * - Handle for generated debug area
+ * - %NULL if register failed
+ *
+ * Allocates memory for a debug log.
+ * The debugfs file mode access permissions are read and write for user.
+ * Must not be called within an interrupt handler.
  */
 debug_info_t *debug_register(const char *name, int pages_per_area,
 			     int nr_areas, int buf_size)
@@ -694,9 +717,13 @@ debug_info_t *debug_register(const char *name, int pages_per_area,
 }
 EXPORT_SYMBOL(debug_register);
 
-/*
- * debug_unregister:
- * - give back debug area
+/**
+ * debug_unregister() - give back debug area.
+ *
+ * @id:		handle for debug log
+ *
+ * Return:
+ *    none
  */
 void debug_unregister(debug_info_t *id)
 {
@@ -745,9 +772,14 @@ out:
 	return rc;
 }
 
-/*
- * debug_set_level:
- * - set actual debug level
+/**
+ * debug_set_level() - Sets new actual debug level if new_level is valid.
+ *
+ * @id:		handle for debug log
+ * @new_level:	new debug level
+ *
+ * Return:
+ *    none
  */
 void debug_set_level(debug_info_t *id, int new_level)
 {
@@ -873,6 +905,14 @@ static struct ctl_table s390dbf_dir_table[] = {
 
 static struct ctl_table_header *s390dbf_sysctl_header;
 
+/**
+ * debug_stop_all() - stops the debug feature if stopping is allowed.
+ *
+ * Return:
+ * -   none
+ *
+ * Currently used in case of a kernel oops.
+ */
 void debug_stop_all(void)
 {
 	if (debug_stoppable)
@@ -880,6 +920,17 @@ void debug_stop_all(void)
 }
 EXPORT_SYMBOL(debug_stop_all);
 
+/**
+ * debug_set_critical() - event/exception functions try lock instead of spin.
+ *
+ * Return:
+ * -   none
+ *
+ * Currently used in case of stopping all CPUs but the current one.
+ * Once in this state, functions to write a debug entry for an
+ * event or exception no longer spin on the debug area lock,
+ * but only try to get it and fail if they do not get the lock.
+ */
 void debug_set_critical(void)
 {
 	debug_critical = 1;
@@ -1036,8 +1087,16 @@ debug_entry_t *__debug_sprintf_exception(debug_info_t *id, int level, char *stri
 }
 EXPORT_SYMBOL(__debug_sprintf_exception);
 
-/*
- * debug_register_view:
+/**
+ * debug_register_view() - registers new debug view and creates debugfs
+ *			   dir entry
+ *
+ * @id:		handle for debug log
+ * @view:	pointer to debug view struct
+ *
+ * Return:
+ * -   0  : ok
+ * -   < 0: Error
  */
 int debug_register_view(debug_info_t *id, struct debug_view *view)
 {
@@ -1077,8 +1136,16 @@ out:
 }
 EXPORT_SYMBOL(debug_register_view);
 
-/*
- * debug_unregister_view:
+/**
+ * debug_unregister_view() - unregisters debug view and removes debugfs
+ *			     dir entry
+ *
+ * @id:		handle for debug log
+ * @view:	pointer to debug view struct
+ *
+ * Return:
+ * -   0  : ok
+ * -   < 0: Error
  */
 int debug_unregister_view(debug_info_t *id, struct debug_view *view)
 {