diff options
| -rw-r--r-- | Documentation/s390/s390dbf.rst | 1 | ||||
| -rw-r--r-- | arch/s390/include/asm/debug.h | 112 | ||||
| -rw-r--r-- | arch/s390/kernel/debug.c | 105 |
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) { |