arch/s390/s390dbf.rst

6       - arch/s390/kernel/debug.c
7       - arch/s390/include/asm/debug.h
11 The goal of this feature is to provide a kernel debug logging API
13 (e.g. device drivers) can have one separate debug log.
14 One purpose of this is to inspect the debug logs after a production system crash
18 it is possible to look at the debug logs on a live system via the Linux
21 The debug feature may also very useful for kernel and driver development.
25 Kernel components (e.g. device drivers) can register themselves at the debug
28 debug log for the caller. For each debug log exists a number of debug areas
29 where exactly one is active at one time.  Each debug area consists of contiguous
30 pages in memory. In the debug areas there are stored debug entries (log records)
33 An event-call writes the specified debug entry to the active debug
35 of the active debug area is reached, a wrap around is done (ring buffer)
36 and the next debug entry will be written at the beginning of the active
37 debug area.
39 An exception-call writes the specified debug entry to the log and
40 switches to the next debug area. This is done in order to be sure
44 The debug areas themselves are also ordered in form of a ring buffer.
45 When an exception is thrown in the last debug area, the following debug
52 Each debug entry contains the following data:
56 - Level of debug entry (0...6)
60 The debug logs can be inspected in a live system through entries in
64 ``/sys/kernel/debug`` therefore the debug feature can be accessed under
65 ``/sys/kernel/debug/s390dbf``.
68 to the debug log. Each component can decide which views should be
74 All debug logs have an actual debug level (range from 0 to 6).
76 parameter. Only debug entries with a level that is lower or equal
80 The actual debug level can be changed with the help of the debugfs-filesystem
82 provided for every debug log. Debugging can be switched off completely
87 	> echo "-" > /sys/kernel/debug/s390dbf/dasd/level
89 It is also possible to deactivate the debug feature globally for every
90 debug log. You can change the behavior using  2 sysctl parameters in
93 There are currently 2 possible triggers, which stop the debug feature
95 set to 1 the debug feature is running. If ``debug_active`` is set to 0 the
96 debug feature is turned off.
98 The second trigger which stops the debug feature is a kernel oops.
99 That prevents the debug feature from overwriting debug information that
100 happened before the oops. After an oops you can reactivate the debug feature
104 If you want to disallow the deactivation of the debug feature, you can use
105 the ``debug_stoppable`` sysctl. If you set ``debug_stoppable`` to 0 the debug
106 feature cannot be stopped. If the debug feature is already stopped, it
112 .. kernel-doc:: arch/s390/kernel/debug.c
113 .. kernel-doc:: arch/s390/include/asm/debug.h
134   #include <asm/debug.h>
140       /* register 4 debug areas with one page each and 4 byte data field */
167   #include <asm/debug.h>
173       /* register 4 debug areas with one page each and data field for */
180       debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info);
195 Views to the debug logs can be investigated through reading the corresponding
200   > ls /sys/kernel/debug/s390dbf/dasd
202   > cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
216 Changing the debug level
222   > cat /sys/kernel/debug/s390dbf/dasd/level
224   > echo "5" > /sys/kernel/debug/s390dbf/dasd/level
225   > cat /sys/kernel/debug/s390dbf/dasd/level
228 Flushing debug areas
231 area (0...n) to the debugfs file "flush". When using "-" all debug areas
236 1. Flush debug area 0::
238      > echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
240 2. Flush all debug areas::
242      > echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
244 Changing the size of debug areas
246 It is possible the change the size of debug areas through piping
248 also flush the debug areas.
252 Define 4 pages for the debug areas of debug feature "dasd"::
254   > echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
256 Stopping the debug feature
264 2. Stop debug feature::
271 ``s390dbf`` to display all the debug logs or export them to the file system.
273 to investigate the debug logs on a live system and with a memory dump after
278 One last possibility to investigate the debug logs at a live
281 It is possible to find the anchor of the debug-logs through
284 in debug.h and find the debug-areas in memory.
285 Normally modules which use the debug feature will also have
286 a global variable with the pointer to the debug-logs. Following
287 this pointer it will also be possible to find the debug logs in
292 order to see the debug entries well formatted.
302 The sprintf view formats the debug entries in the same way as the sprintf
304 debug entry a pointer to the format string (size = sizeof(long))
305 and for each vararg a long value. So e.g. for a debug entry with a format
312   is available as long as the debug feature exists. The reason behind this is
314   in  the debug feature. If you log a string that is freed afterwards, you will
315   get an OOPS when inspecting the debug feature, because then the debug feature
327 - level of debug entry
381 It is not used by the debug feature itself.
395 existing debug entry.
398 the view (e.g. like with ``echo "0" > /sys/kernel/debug/s390dbf/dasd/level``).
401 :c:func:`debug_dflt_header_fn()` which is defined in debug.h.
414   #include <asm/debug.h>
468   > cat /sys/kernel/debug/s390dbf/test/myview