aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/s390/s390dbf.txt79
1 files changed, 46 insertions, 33 deletions
diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt
index 2d1cd939b4df..e24fdeada970 100644
--- a/Documentation/s390/s390dbf.txt
+++ b/Documentation/s390/s390dbf.txt
@@ -12,8 +12,8 @@ where log records can be stored efficiently in memory, where each component
12One purpose of this is to inspect the debug logs after a production system crash 12One purpose of this is to inspect the debug logs after a production system crash
13in order to analyze the reason for the crash. 13in order to analyze the reason for the crash.
14If the system still runs but only a subcomponent which uses dbf failes, 14If the system still runs but only a subcomponent which uses dbf failes,
15it is possible to look at the debug logs on a live system via the Linux proc 15it is possible to look at the debug logs on a live system via the Linux
16filesystem. 16debugfs filesystem.
17The debug feature may also very useful for kernel and driver development. 17The debug feature may also very useful for kernel and driver development.
18 18
19Design: 19Design:
@@ -52,16 +52,18 @@ Each debug entry contains the following data:
52- Flag, if entry is an exception or not 52- Flag, if entry is an exception or not
53 53
54The debug logs can be inspected in a live system through entries in 54The debug logs can be inspected in a live system through entries in
55the proc-filesystem. Under the path /proc/s390dbf there is 55the debugfs-filesystem. Under the toplevel directory "s390dbf" there is
56a directory for each registered component, which is named like the 56a directory for each registered component, which is named like the
57corresponding component. 57corresponding component. The debugfs normally should be mounted to
58/sys/kernel/debug therefore the debug feature can be accessed unter
59/sys/kernel/debug/s390dbf.
58 60
59The content of the directories are files which represent different views 61The content of the directories are files which represent different views
60to the debug log. Each component can decide which views should be 62to the debug log. Each component can decide which views should be
61used through registering them with the function debug_register_view(). 63used through registering them with the function debug_register_view().
62Predefined views for hex/ascii, sprintf and raw binary data are provided. 64Predefined views for hex/ascii, sprintf and raw binary data are provided.
63It is also possible to define other views. The content of 65It is also possible to define other views. The content of
64a view can be inspected simply by reading the corresponding proc file. 66a view can be inspected simply by reading the corresponding debugfs file.
65 67
66All debug logs have an an actual debug level (range from 0 to 6). 68All debug logs have an an actual debug level (range from 0 to 6).
67The default level is 3. Event and Exception functions have a 'level' 69The default level is 3. Event and Exception functions have a 'level'
@@ -69,14 +71,14 @@ parameter. Only debug entries with a level that is lower or equal
69than the actual level are written to the log. This means, when 71than the actual level are written to the log. This means, when
70writing events, high priority log entries should have a low level 72writing events, high priority log entries should have a low level
71value whereas low priority entries should have a high one. 73value whereas low priority entries should have a high one.
72The actual debug level can be changed with the help of the proc-filesystem 74The actual debug level can be changed with the help of the debugfs-filesystem
73through writing a number string "x" to the 'level' proc file which is 75through writing a number string "x" to the 'level' debugfs file which is
74provided for every debug log. Debugging can be switched off completely 76provided for every debug log. Debugging can be switched off completely
75by using "-" on the 'level' proc file. 77by using "-" on the 'level' debugfs file.
76 78
77Example: 79Example:
78 80
79> echo "-" > /proc/s390dbf/dasd/level 81> echo "-" > /sys/kernel/debug/s390dbf/dasd/level
80 82
81It is also possible to deactivate the debug feature globally for every 83It is also possible to deactivate the debug feature globally for every
82debug log. You can change the behavior using 2 sysctl parameters in 84debug log. You can change the behavior using 2 sysctl parameters in
@@ -99,11 +101,11 @@ Kernel Interfaces:
99------------------ 101------------------
100 102
101---------------------------------------------------------------------------- 103----------------------------------------------------------------------------
102debug_info_t *debug_register(char *name, int pages_index, int nr_areas, 104debug_info_t *debug_register(char *name, int pages, int nr_areas,
103 int buf_size); 105 int buf_size);
104 106
105Parameter: name: Name of debug log (e.g. used for proc entry) 107Parameter: name: Name of debug log (e.g. used for debugfs entry)
106 pages_index: 2^pages_index pages will be allocated per area 108 pages: number of pages, which will be allocated per area
107 nr_areas: number of debug areas 109 nr_areas: number of debug areas
108 buf_size: size of data area in each debug entry 110 buf_size: size of data area in each debug entry
109 111
@@ -134,7 +136,7 @@ Return Value: none
134Description: Sets new actual debug level if new_level is valid. 136Description: Sets new actual debug level if new_level is valid.
135 137
136--------------------------------------------------------------------------- 138---------------------------------------------------------------------------
137+void debug_stop_all(void); 139void debug_stop_all(void);
138 140
139Parameter: none 141Parameter: none
140 142
@@ -270,7 +272,7 @@ Parameter: id: handle for debug log
270Return Value: 0 : ok 272Return Value: 0 : ok
271 < 0: Error 273 < 0: Error
272 274
273Description: registers new debug view and creates proc dir entry 275Description: registers new debug view and creates debugfs dir entry
274 276
275--------------------------------------------------------------------------- 277---------------------------------------------------------------------------
276int debug_unregister_view (debug_info_t * id, struct debug_view *view); 278int debug_unregister_view (debug_info_t * id, struct debug_view *view);
@@ -281,7 +283,7 @@ Parameter: id: handle for debug log
281Return Value: 0 : ok 283Return Value: 0 : ok
282 < 0: Error 284 < 0: Error
283 285
284Description: unregisters debug view and removes proc dir entry 286Description: unregisters debug view and removes debugfs dir entry
285 287
286 288
287 289
@@ -308,7 +310,7 @@ static int init(void)
308{ 310{
309 /* register 4 debug areas with one page each and 4 byte data field */ 311 /* register 4 debug areas with one page each and 4 byte data field */
310 312
311 debug_info = debug_register ("test", 0, 4, 4 ); 313 debug_info = debug_register ("test", 1, 4, 4 );
312 debug_register_view(debug_info,&debug_hex_ascii_view); 314 debug_register_view(debug_info,&debug_hex_ascii_view);
313 debug_register_view(debug_info,&debug_raw_view); 315 debug_register_view(debug_info,&debug_raw_view);
314 316
@@ -343,7 +345,7 @@ static int init(void)
343 /* register 4 debug areas with one page each and data field for */ 345 /* register 4 debug areas with one page each and data field for */
344 /* format string pointer + 2 varargs (= 3 * sizeof(long)) */ 346 /* format string pointer + 2 varargs (= 3 * sizeof(long)) */
345 347
346 debug_info = debug_register ("test", 0, 4, sizeof(long) * 3); 348 debug_info = debug_register ("test", 1, 4, sizeof(long) * 3);
347 debug_register_view(debug_info,&debug_sprintf_view); 349 debug_register_view(debug_info,&debug_sprintf_view);
348 350
349 debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__); 351 debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__);
@@ -362,16 +364,16 @@ module_exit(cleanup);
362 364
363 365
364 366
365ProcFS Interface 367Debugfs Interface
366---------------- 368----------------
367Views to the debug logs can be investigated through reading the corresponding 369Views to the debug logs can be investigated through reading the corresponding
368proc-files: 370debugfs-files:
369 371
370Example: 372Example:
371 373
372> ls /proc/s390dbf/dasd 374> ls /sys/kernel/debug/s390dbf/dasd
373flush hex_ascii level raw 375flush hex_ascii level pages raw
374> cat /proc/s390dbf/dasd/hex_ascii | sort +1 376> cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort +1
37500 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | .... 37700 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
37600 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE 37800 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
37700 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | .... 37900 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | ....
@@ -391,25 +393,36 @@ Changing the debug level
391Example: 393Example:
392 394
393 395
394> cat /proc/s390dbf/dasd/level 396> cat /sys/kernel/debug/s390dbf/dasd/level
3953 3973
396> echo "5" > /proc/s390dbf/dasd/level 398> echo "5" > /sys/kernel/debug/s390dbf/dasd/level
397> cat /proc/s390dbf/dasd/level 399> cat /sys/kernel/debug/s390dbf/dasd/level
3985 4005
399 401
400Flushing debug areas 402Flushing debug areas
401-------------------- 403--------------------
402Debug areas can be flushed with piping the number of the desired 404Debug areas can be flushed with piping the number of the desired
403area (0...n) to the proc file "flush". When using "-" all debug areas 405area (0...n) to the debugfs file "flush". When using "-" all debug areas
404are flushed. 406are flushed.
405 407
406Examples: 408Examples:
407 409
4081. Flush debug area 0: 4101. Flush debug area 0:
409> echo "0" > /proc/s390dbf/dasd/flush 411> echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
410 412
4112. Flush all debug areas: 4132. Flush all debug areas:
412> echo "-" > /proc/s390dbf/dasd/flush 414> echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
415
416Changing the size of debug areas
417------------------------------------
418It is possible the change the size of debug areas through piping
419the number of pages to the debugfs file "pages". The resize request will
420also flush the debug areas.
421
422Example:
423
424Define 4 pages for the debug areas of debug feature "dasd":
425> echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
413 426
414Stooping the debug feature 427Stooping the debug feature
415-------------------------- 428--------------------------
@@ -491,7 +504,7 @@ Defining views
491-------------- 504--------------
492 505
493Views are specified with the 'debug_view' structure. There are defined 506Views are specified with the 'debug_view' structure. There are defined
494callback functions which are used for reading and writing the proc files: 507callback functions which are used for reading and writing the debugfs files:
495 508
496struct debug_view { 509struct debug_view {
497 char name[DEBUG_MAX_PROCF_LEN]; 510 char name[DEBUG_MAX_PROCF_LEN];
@@ -525,7 +538,7 @@ typedef int (debug_input_proc_t) (debug_info_t* id,
525The "private_data" member can be used as pointer to view specific data. 538The "private_data" member can be used as pointer to view specific data.
526It is not used by the debug feature itself. 539It is not used by the debug feature itself.
527 540
528The output when reading a debug-proc file is structured like this: 541The output when reading a debugfs file is structured like this:
529 542
530"prolog_proc output" 543"prolog_proc output"
531 544
@@ -534,13 +547,13 @@ The output when reading a debug-proc file is structured like this:
534"header_proc output 3" "format_proc output 3" 547"header_proc output 3" "format_proc output 3"
535... 548...
536 549
537When a view is read from the proc fs, the Debug Feature calls the 550When a view is read from the debugfs, the Debug Feature calls the
538'prolog_proc' once for writing the prolog. 551'prolog_proc' once for writing the prolog.
539Then 'header_proc' and 'format_proc' are called for each 552Then 'header_proc' and 'format_proc' are called for each
540existing debug entry. 553existing debug entry.
541 554
542The input_proc can be used to implement functionality when it is written to 555The input_proc can be used to implement functionality when it is written to
543the view (e.g. like with 'echo "0" > /proc/s390dbf/dasd/level). 556the view (e.g. like with 'echo "0" > /sys/kernel/debug/s390dbf/dasd/level).
544 557
545For header_proc there can be used the default function 558For header_proc there can be used the default function
546debug_dflt_header_fn() which is defined in in debug.h. 559debug_dflt_header_fn() which is defined in in debug.h.
@@ -602,7 +615,7 @@ debug_info = debug_register ("test", 0, 4, 4 ));
602debug_register_view(debug_info, &debug_test_view); 615debug_register_view(debug_info, &debug_test_view);
603for(i = 0; i < 10; i ++) debug_int_event(debug_info, 1, i); 616for(i = 0; i < 10; i ++) debug_int_event(debug_info, 1, i);
604 617
605> cat /proc/s390dbf/test/myview 618> cat /sys/kernel/debug/s390dbf/test/myview
60600 00964419734:611402 1 - 00 88042ca This error........... 61900 00964419734:611402 1 - 00 88042ca This error...........
60700 00964419734:611405 1 - 00 88042ca That error........... 62000 00964419734:611405 1 - 00 88042ca That error...........
60800 00964419734:611408 1 - 00 88042ca Problem.............. 62100 00964419734:611408 1 - 00 88042ca Problem..............