~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/arch/s390/s390dbf.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/arch/s390/s390dbf.rst (Version linux-6.12-rc7) and /Documentation/arch/m68k/s390dbf.rst (Version linux-4.14.336)


  1 ==================                                
  2 S390 Debug Feature                                
  3 ==================                                
  4                                                   
  5 files:                                            
  6       - arch/s390/kernel/debug.c                  
  7       - arch/s390/include/asm/debug.h             
  8                                                   
  9 Description:                                      
 10 ------------                                      
 11 The goal of this feature is to provide a kerne    
 12 where log records can be stored efficiently in    
 13 (e.g. device drivers) can have one separate de    
 14 One purpose of this is to inspect the debug lo    
 15 in order to analyze the reason for the crash.     
 16                                                   
 17 If the system still runs but only a subcompone    
 18 it is possible to look at the debug logs on a     
 19 debugfs filesystem.                               
 20                                                   
 21 The debug feature may also very useful for ker    
 22                                                   
 23 Design:                                           
 24 -------                                           
 25 Kernel components (e.g. device drivers) can re    
 26 feature with the function call :c:func:`debug_    
 27 This function initializes a                       
 28 debug log for the caller. For each debug log e    
 29 where exactly one is active at one time.  Each    
 30 pages in memory. In the debug areas there are     
 31 which are written by event- and exception-call    
 32                                                   
 33 An event-call writes the specified debug entry    
 34 area and updates the log pointer for the activ    
 35 of the active debug area is reached, a wrap ar    
 36 and the next debug entry will be written at th    
 37 debug area.                                       
 38                                                   
 39 An exception-call writes the specified debug e    
 40 switches to the next debug area. This is done     
 41 that the records which describe the origin of     
 42 overwritten when a wrap around for the current    
 43                                                   
 44 The debug areas themselves are also ordered in    
 45 When an exception is thrown in the last debug     
 46 entries are then written again in the very fir    
 47                                                   
 48 There are four versions for the event- and exc    
 49 logging raw data, one for text, one for number    
 50 and one for sprintf-like formatted strings.       
 51                                                   
 52 Each debug entry contains the following data:     
 53                                                   
 54 - Timestamp                                       
 55 - Cpu-Number of calling task                      
 56 - Level of debug entry (0...6)                    
 57 - Return Address to caller                        
 58 - Flag, if entry is an exception or not           
 59                                                   
 60 The debug logs can be inspected in a live syst    
 61 the debugfs-filesystem. Under the toplevel dir    
 62 a directory for each registered component, whi    
 63 corresponding component. The debugfs normally     
 64 ``/sys/kernel/debug`` therefore the debug feat    
 65 ``/sys/kernel/debug/s390dbf``.                    
 66                                                   
 67 The content of the directories are files which    
 68 to the debug log. Each component can decide wh    
 69 used through registering them with the functio    
 70 Predefined views for hex/ascii and sprintf dat    
 71 It is also possible to define other views. The    
 72 a view can be inspected simply by reading the     
 73                                                   
 74 All debug logs have an actual debug level (ran    
 75 The default level is 3. Event and Exception fu    
 76 parameter. Only debug entries with a level tha    
 77 than the actual level are written to the log.     
 78 writing events, high priority log entries shou    
 79 value whereas low priority entries should have    
 80 The actual debug level can be changed with the    
 81 through writing a number string "x" to the ``l    
 82 provided for every debug log. Debugging can be    
 83 by using "-" on the ``level`` debugfs file.       
 84                                                   
 85 Example::                                         
 86                                                   
 87         > echo "-" > /sys/kernel/debug/s390dbf    
 88                                                   
 89 It is also possible to deactivate the debug fe    
 90 debug log. You can change the behavior using      
 91 ``/proc/sys/s390dbf``:                            
 92                                                   
 93 There are currently 2 possible triggers, which    
 94 globally. The first possibility is to use the     
 95 set to 1 the debug feature is running. If ``de    
 96 debug feature is turned off.                      
 97                                                   
 98 The second trigger which stops the debug featu    
 99 That prevents the debug feature from overwriti    
100 happened before the oops. After an oops you ca    
101 by piping 1 to ``/proc/sys/s390dbf/debug_activ    
102 suggested to use an oopsed kernel in a product    
103                                                   
104 If you want to disallow the deactivation of th    
105 the ``debug_stoppable`` sysctl. If you set ``d    
106 feature cannot be stopped. If the debug featur    
107 will stay deactivated.                            
108                                                   
109 Kernel Interfaces:                                
110 ------------------                                
111                                                   
112 .. kernel-doc:: arch/s390/kernel/debug.c          
113 .. kernel-doc:: arch/s390/include/asm/debug.h     
114                                                   
115 Predefined views:                                 
116 -----------------                                 
117                                                   
118 .. code-block:: c                                 
119                                                   
120   extern struct debug_view debug_hex_ascii_vie    
121                                                   
122   extern struct debug_view debug_sprintf_view;    
123                                                   
124 Examples                                          
125 --------                                          
126                                                   
127 .. code-block:: c                                 
128                                                   
129   /*                                              
130    * hex_ascii-view Example                       
131    */                                             
132                                                   
133   #include <linux/init.h>                         
134   #include <asm/debug.h>                          
135                                                   
136   static debug_info_t *debug_info;                
137                                                   
138   static int init(void)                           
139   {                                               
140       /* register 4 debug areas with one page     
141                                                   
142       debug_info = debug_register("test", 1, 4    
143       debug_register_view(debug_info, &debug_h    
144                                                   
145       debug_text_event(debug_info, 4 , "one ")    
146       debug_int_exception(debug_info, 4, 4711)    
147       debug_event(debug_info, 3, &debug_info,     
148                                                   
149       return 0;                                   
150   }                                               
151                                                   
152   static void cleanup(void)                       
153   {                                               
154       debug_unregister(debug_info);               
155   }                                               
156                                                   
157   module_init(init);                              
158   module_exit(cleanup);                           
159                                                   
160 .. code-block:: c                                 
161                                                   
162   /*                                              
163    * sprintf-view Example                         
164    */                                             
165                                                   
166   #include <linux/init.h>                         
167   #include <asm/debug.h>                          
168                                                   
169   static debug_info_t *debug_info;                
170                                                   
171   static int init(void)                           
172   {                                               
173       /* register 4 debug areas with one page     
174       /* format string pointer + 2 varargs (=     
175                                                   
176       debug_info = debug_register("test", 1, 4    
177       debug_register_view(debug_info, &debug_s    
178                                                   
179       debug_sprintf_event(debug_info, 2 , "fir    
180       debug_sprintf_exception(debug_info, 1, "    
181                                                   
182       return 0;                                   
183   }                                               
184                                                   
185   static void cleanup(void)                       
186   {                                               
187       debug_unregister(debug_info);               
188   }                                               
189                                                   
190   module_init(init);                              
191   module_exit(cleanup);                           
192                                                   
193 Debugfs Interface                                 
194 -----------------                                 
195 Views to the debug logs can be investigated th    
196 debugfs-files:                                    
197                                                   
198 Example::                                         
199                                                   
200   > ls /sys/kernel/debug/s390dbf/dasd             
201   flush  hex_ascii  level pages                   
202   > cat /sys/kernel/debug/s390dbf/dasd/hex_asc    
203   00 00974733272:680099 2 - 02 0006ad7e  07 ea    
204   00 00974733272:682210 2 - 02 0006ade6  46 52    
205   00 00974733272:682213 2 - 02 0006adf6  07 ea    
206   00 00974733272:682281 1 * 02 0006ab08  41 4c    
207   01 00974733272:682284 2 - 02 0006ab16  45 43    
208   01 00974733272:682287 2 - 02 0006ab28  00 00    
209   01 00974733272:682289 2 - 02 0006ab3e  00 00    
210   01 00974733272:682297 2 - 02 0006ad7e  07 ea    
211   01 00974733272:684384 2 - 00 0006ade6  46 52    
212   01 00974733272:684388 2 - 00 0006adf6  07 ea    
213                                                   
214 See section about predefined views for explana    
215                                                   
216 Changing the debug level                          
217 ------------------------                          
218                                                   
219 Example::                                         
220                                                   
221                                                   
222   > cat /sys/kernel/debug/s390dbf/dasd/level      
223   3                                               
224   > echo "5" > /sys/kernel/debug/s390dbf/dasd/    
225   > cat /sys/kernel/debug/s390dbf/dasd/level      
226   5                                               
227                                                   
228 Flushing debug areas                              
229 --------------------                              
230 Debug areas can be flushed with piping the num    
231 area (0...n) to the debugfs file "flush". When    
232 are flushed.                                      
233                                                   
234 Examples:                                         
235                                                   
236 1. Flush debug area 0::                           
237                                                   
238      > echo "0" > /sys/kernel/debug/s390dbf/da    
239                                                   
240 2. Flush all debug areas::                        
241                                                   
242      > echo "-" > /sys/kernel/debug/s390dbf/da    
243                                                   
244 Changing the size of debug areas                  
245 ------------------------------------              
246 It is possible the change the size of debug ar    
247 the number of pages to the debugfs file "pages    
248 also flush the debug areas.                       
249                                                   
250 Example:                                          
251                                                   
252 Define 4 pages for the debug areas of debug fe    
253                                                   
254   > echo "4" > /sys/kernel/debug/s390dbf/dasd/    
255                                                   
256 Stopping the debug feature                        
257 --------------------------                        
258 Example:                                          
259                                                   
260 1. Check if stopping is allowed::                 
261                                                   
262      > cat /proc/sys/s390dbf/debug_stoppable      
263                                                   
264 2. Stop debug feature::                           
265                                                   
266      > echo 0 > /proc/sys/s390dbf/debug_active    
267                                                   
268 crash Interface                                   
269 ----------------                                  
270 The ``crash`` tool since v5.1.0 has a built-in    
271 ``s390dbf`` to display all the debug logs or e    
272 With this tool it is possible                     
273 to investigate the debug logs on a live system    
274 a system crash.                                   
275                                                   
276 Investigating raw memory                          
277 ------------------------                          
278 One last possibility to investigate the debug     
279 system and after a system crash is to look at     
280 under VM or at the Service Element.               
281 It is possible to find the anchor of the debug    
282 the ``debug_area_first`` symbol in the System     
283 to follow the correct pointers of the data-str    
284 in debug.h and find the debug-areas in memory.    
285 Normally modules which use the debug feature w    
286 a global variable with the pointer to the debu    
287 this pointer it will also be possible to find     
288 memory.                                           
289                                                   
290 For this method it is recommended to use '16 *    
291 for the length of the data field in :c:func:`d    
292 order to see the debug entries well formatted.    
293                                                   
294                                                   
295 Predefined Views                                  
296 ----------------                                  
297                                                   
298 There are two predefined views: hex_ascii and     
299 The hex_ascii view shows the data field in hex    
300 (e.g. ``45 43 4b 44 | ECKD``).                    
301                                                   
302 The sprintf view formats the debug entries in     
303 function would do. The sprintf event/exception    
304 debug entry a pointer to the format string (si    
305 and for each vararg a long value. So e.g. for     
306 string plus two varargs one would need to allo    
307 byte data area in the debug_register() functio    
308                                                   
309 IMPORTANT:                                        
310   Using "%s" in sprintf event functions is dan    
311   use "%s" in the sprintf event functions, if     
312   is available as long as the debug feature ex    
313   that due to performance considerations only     
314   in  the debug feature. If you log a string t    
315   get an OOPS when inspecting the debug featur    
316   will access the already freed memory.           
317                                                   
318 NOTE:                                             
319   If using the sprintf view do NOT use other e    
320   than the sprintf-event and -exception functi    
321                                                   
322 The format of the hex_ascii and sprintf view i    
323                                                   
324 - Number of area                                  
325 - Timestamp (formatted as seconds and microsec    
326   Universal Time (UTC), January 1, 1970)          
327 - level of debug entry                            
328 - Exception flag (* = Exception)                  
329 - Cpu-Number of calling task                      
330 - Return Address to caller                        
331 - data field                                      
332                                                   
333 A typical line of the hex_ascii view will look    
334 is only for explanation and will not be displa    
335                                                   
336   area  time           level exception cpu cal    
337   --------------------------------------------    
338   00    00964419409:440690 1 -         00  880    
339                                                   
340                                                   
341 Defining views                                    
342 --------------                                    
343                                                   
344 Views are specified with the 'debug_view' stru    
345 callback functions which are used for reading     
346                                                   
347 .. code-block:: c                                 
348                                                   
349   struct debug_view {                             
350         char name[DEBUG_MAX_PROCF_LEN];           
351         debug_prolog_proc_t* prolog_proc;         
352         debug_header_proc_t* header_proc;         
353         debug_format_proc_t* format_proc;         
354         debug_input_proc_t*  input_proc;          
355         void*                private_data;        
356   };                                              
357                                                   
358 where:                                            
359                                                   
360 .. code-block:: c                                 
361                                                   
362   typedef int (debug_header_proc_t) (debug_inf    
363                                      struct de    
364                                      int area,    
365                                      debug_ent    
366                                      char* out    
367                                                   
368   typedef int (debug_format_proc_t) (debug_inf    
369                                      struct de    
370                                      const cha    
371   typedef int (debug_prolog_proc_t) (debug_inf    
372                                      struct de    
373                                      char* out    
374   typedef int (debug_input_proc_t) (debug_info    
375                                     struct deb    
376                                     struct fil    
377                                     size_t in_    
378                                                   
379                                                   
380 The "private_data" member can be used as point    
381 It is not used by the debug feature itself.       
382                                                   
383 The output when reading a debugfs file is stru    
384                                                   
385   "prolog_proc output"                            
386                                                   
387   "header_proc output 1"  "format_proc output     
388   "header_proc output 2"  "format_proc output     
389   "header_proc output 3"  "format_proc output     
390   ...                                             
391                                                   
392 When a view is read from the debugfs, the Debu    
393 'prolog_proc' once for writing the prolog.        
394 Then 'header_proc' and 'format_proc' are calle    
395 existing debug entry.                             
396                                                   
397 The input_proc can be used to implement functi    
398 the view (e.g. like with ``echo "0" > /sys/ker    
399                                                   
400 For header_proc there can be used the default     
401 :c:func:`debug_dflt_header_fn()` which is defi    
402 and which produces the same header output as t    
403 E.g::                                             
404                                                   
405   00 00964419409:440761 2 - 00 88023ec            
406                                                   
407 In order to see how to use the callback functi    
408 of the default views!                             
409                                                   
410 Example:                                          
411                                                   
412 .. code-block:: c                                 
413                                                   
414   #include <asm/debug.h>                          
415                                                   
416   #define UNKNOWNSTR "data: %08x"                 
417                                                   
418   const char* messages[] =                        
419   {"This error...........\n",                     
420    "That error...........\n",                     
421    "Problem..............\n",                     
422    "Something went wrong.\n",                     
423    "Everything ok........\n",                     
424    NULL                                           
425   };                                              
426                                                   
427   static int debug_test_format_fn(                
428      debug_info_t *id, struct debug_view *view    
429      char *out_buf, const char *in_buf            
430   )                                               
431   {                                               
432     int i, rc = 0;                                
433                                                   
434     if (id->buf_size >= 4) {                      
435        int msg_nr = *((int*)in_buf);              
436        if (msg_nr < sizeof(messages) / sizeof(    
437           rc += sprintf(out_buf, "%s", message    
438        else                                       
439           rc += sprintf(out_buf, UNKNOWNSTR, m    
440     }                                             
441     return rc;                                    
442   }                                               
443                                                   
444   struct debug_view debug_test_view = {           
445     "myview",                 /* name of view     
446     NULL,                     /* no prolog */     
447     &debug_dflt_header_fn,    /* default heade    
448     &debug_test_format_fn,    /* our own forma    
449     NULL,                     /* no input func    
450     NULL                      /* no private da    
451   };                                              
452                                                   
453 test:                                             
454 =====                                             
455                                                   
456 .. code-block:: c                                 
457                                                   
458   debug_info_t *debug_info;                       
459   int i;                                          
460   ...                                             
461   debug_info = debug_register("test", 0, 4, 4)    
462   debug_register_view(debug_info, &debug_test_    
463   for (i = 0; i < 10; i ++)                       
464     debug_int_event(debug_info, 1, i);            
465                                                   
466 ::                                                
467                                                   
468   > cat /sys/kernel/debug/s390dbf/test/myview     
469   00 00964419734:611402 1 - 00 88042ca   This     
470   00 00964419734:611405 1 - 00 88042ca   That     
471   00 00964419734:611408 1 - 00 88042ca   Probl    
472   00 00964419734:611411 1 - 00 88042ca   Somet    
473   00 00964419734:611414 1 - 00 88042ca   Every    
474   00 00964419734:611417 1 - 00 88042ca   data:    
475   00 00964419734:611419 1 - 00 88042ca   data:    
476   00 00964419734:611422 1 - 00 88042ca   data:    
477   00 00964419734:611425 1 - 00 88042ca   data:    
478   00 00964419734:611428 1 - 00 88042ca   data:    
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php