Skip to content

Commit

Permalink
docs: s390: unify and update s390dbf kdocs at debug.c
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@steffen-maier
steffen-maier authored and Vasily Gorbik committed Jul 5, 2019
1 parent f11977b commit 0328e51
Show file tree
Hide file tree
Showing 3 changed files with 102 additions and 116 deletions.
1 change: 1 addition & 0 deletions Documentation/s390/s390dbf.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
112 changes: 15 additions & 97 deletions arch/s390/include/asm/debug.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/**
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
*
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);

/*
Expand Down
105 changes: 86 additions & 19 deletions arch/s390/kernel/debug.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -681,10 +693,21 @@ debug_info_t *debug_register_mode(const char *name, int pages_per_area,
}
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)
Expand All @@ -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)
{
Expand Down Expand Up @@ -745,9 +772,14 @@ static int debug_set_size(debug_info_t *id, int nr_areas, int pages_per_area)
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)
{
Expand Down Expand Up @@ -873,13 +905,32 @@ 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)
debug_active = 0;
}
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;
Expand Down Expand Up @@ -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)
{
Expand Down Expand Up @@ -1077,8 +1136,16 @@ int debug_register_view(debug_info_t *id, struct debug_view *view)
}
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)
{
Expand Down

0 comments on commit 0328e51

Please sign in to comment.