projects/linux·blob master · refs

504 lines · 14.5 KiB

1/* SPDX-License-Identifier: GPL-2.0 */
2/*
3 * S/390 debug facility
4 *
5 * Copyright IBM Corp. 1999, 2020
6 */
7#ifndef _ASM_S390_DEBUG_H
8#define _ASM_S390_DEBUG_H
9
10#include <linux/string.h>
11#include <linux/spinlock.h>
12#include <linux/kernel.h>
13#include <linux/time.h>
14#include <linux/refcount.h>
15#include <linux/fs.h>
16#include <linux/init.h>
17
18#define DEBUG_MAX_LEVEL 6 /* debug levels range from 0 to 6 */
19#define DEBUG_OFF_LEVEL -1 /* level where debug is switched off */
20#define DEBUG_FLUSH_ALL -1 /* parameter to flush all areas */
21#define DEBUG_MAX_VIEWS 10 /* max number of views in proc fs */
22#define DEBUG_MAX_NAME_LEN 64 /* max length for a debugfs file name */
23#define DEBUG_DEFAULT_LEVEL 3 /* initial debug level */
24
25#define DEBUG_DIR_ROOT "s390dbf" /* name of debug root directory in proc fs */
26
27#define DEBUG_DATA(entry) (char *)(entry + 1) /* data is stored behind */
28 /* the entry information */
29
30#define __DEBUG_FEATURE_VERSION 3 /* version of debug feature */
31
32struct __debug_entry {
33 unsigned long clock : 60;
34 unsigned long exception : 1;
35 unsigned long level : 3;
36 void *caller;
37 unsigned short cpu;
38} __packed;
39
40typedef struct __debug_entry debug_entry_t;
41
42struct debug_view;
43
44typedef struct debug_info {
45 struct debug_info *next;
46 struct debug_info *prev;
47 refcount_t ref_count;
48 raw_spinlock_t lock;
49 int level;
50 int nr_areas;
51 int pages_per_area;
52 int buf_size;
53 int entry_size;
54 debug_entry_t ***areas;
55 int active_area;
56 int *active_pages;
57 int *active_entries;
58 struct dentry *debugfs_root_entry;
59 struct dentry *debugfs_entries[DEBUG_MAX_VIEWS];
60 struct debug_view *views[DEBUG_MAX_VIEWS];
61 char name[DEBUG_MAX_NAME_LEN];
62 umode_t mode;
63} debug_info_t;
64
65typedef int (debug_header_proc_t) (debug_info_t *id,
66 struct debug_view *view,
67 int area,
68 debug_entry_t *entry,
69 char *out_buf, size_t out_buf_size);
70
71typedef int (debug_format_proc_t) (debug_info_t *id,
72 struct debug_view *view, char *out_buf,
73 size_t out_buf_size,
74 const char *in_buf);
75typedef int (debug_prolog_proc_t) (debug_info_t *id,
76 struct debug_view *view,
77 char *out_buf, size_t out_buf_size);
78typedef int (debug_input_proc_t) (debug_info_t *id,
79 struct debug_view *view,
80 struct file *file,
81 const char __user *user_buf,
82 size_t in_buf_size, loff_t *offset);
83
84int debug_dflt_header_fn(debug_info_t *id, struct debug_view *view,
85 int area, debug_entry_t *entry,
86 char *out_buf, size_t out_buf_size);
87
88#define DEBUG_SPRINTF_MAX_ARGS 10
89int debug_sprintf_format_fn(debug_info_t *id, struct debug_view *view,
90 char *out_buf, size_t out_buf_size,
91 const char *inbuf);
92struct debug_view {
93 char name[DEBUG_MAX_NAME_LEN];
94 debug_prolog_proc_t *prolog_proc;
95 debug_header_proc_t *header_proc;
96 debug_format_proc_t *format_proc;
97 debug_input_proc_t *input_proc;
98 void *private_data;
99};
100
101extern struct debug_view debug_hex_ascii_view;
102extern struct debug_view debug_sprintf_view;
103
104/* do NOT use the _common functions */
105
106debug_entry_t *debug_event_common(debug_info_t *id, int level,
107 const void *data, int length);
108
109debug_entry_t *debug_exception_common(debug_info_t *id, int level,
110 const void *data, int length);
111
112/* Debug Feature API: */
113
114debug_info_t *debug_register(const char *name, int pages, int nr_areas,
115 int buf_size);
116
117debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
118 int buf_size, umode_t mode, uid_t uid,
119 gid_t gid);
120
121ssize_t debug_dump(debug_info_t *id, struct debug_view *view,
122 char *buf, size_t buf_size, bool reverse);
123
124void debug_unregister(debug_info_t *id);
125
126void debug_set_level(debug_info_t *id, int new_level);
127
128void debug_set_critical(void);
129
130void debug_stop_all(void);
131
132/**
133 * debug_level_enabled() - Returns true if debug events for the specified
134 * level would be logged. Otherwise returns false.
135 *
136 * @id: handle for debug log
137 * @level: debug level
138 *
139 * Return:
140 * - %true if level is less or equal to the current debug level.
141 */
142static inline bool debug_level_enabled(debug_info_t *id, int level)
143{
144 return level <= id->level;
145}
146
147/**
148 * debug_event() - writes binary debug entry to active debug area
149 * (if level <= actual debug level)
150 *
151 * @id: handle for debug log
152 * @level: debug level
153 * @data: pointer to data for debug entry
154 * @length: length of data in bytes
155 *
156 * Return:
157 * - Address of written debug entry
158 * - %NULL if error
159 */
160static inline debug_entry_t *debug_event(debug_info_t *id, int level,
161 void *data, int length)
162{
163 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
164 return NULL;
165 return debug_event_common(id, level, data, length);
166}
167
168/**
169 * debug_int_event() - writes unsigned integer debug entry to active debug area
170 * (if level <= actual debug level)
171 *
172 * @id: handle for debug log
173 * @level: debug level
174 * @tag: integer value for debug entry
175 *
176 * Return:
177 * - Address of written debug entry
178 * - %NULL if error
179 */
180static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
181 unsigned int tag)
182{
183 unsigned int t = tag;
184
185 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
186 return NULL;
187 return debug_event_common(id, level, &t, sizeof(unsigned int));
188}
189
190/**
191 * debug_long_event() - writes unsigned long debug entry to active debug area
192 * (if level <= actual debug level)
193 *
194 * @id: handle for debug log
195 * @level: debug level
196 * @tag: long integer value for debug entry
197 *
198 * Return:
199 * - Address of written debug entry
200 * - %NULL if error
201 */
202static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
203 unsigned long tag)
204{
205 unsigned long t = tag;
206
207 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
208 return NULL;
209 return debug_event_common(id, level, &t, sizeof(unsigned long));
210}
211
212/**
213 * debug_text_event() - writes string debug entry in ascii format to active
214 * debug area (if level <= actual debug level)
215 *
216 * @id: handle for debug log
217 * @level: debug level
218 * @txt: string for debug entry
219 *
220 * Return:
221 * - Address of written debug entry
222 * - %NULL if error
223 */
224static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
225 const char *txt)
226{
227 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
228 return NULL;
229 return debug_event_common(id, level, txt, strlen(txt));
230}
231
232/*
233 * IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
234 * stored in the s390dbf. See Documentation/arch/s390/s390dbf.rst for more details!
235 */
236extern debug_entry_t *
237__debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
238 __attribute__ ((format(printf, 3, 4)));
239
240/**
241 * debug_sprintf_event() - writes debug entry with format string
242 * and varargs (longs) to active debug area
243 * (if level $<=$ actual debug level).
244 *
245 * @_id: handle for debug log
246 * @_level: debug level
247 * @_fmt: format string for debug entry
248 * @...: varargs used as in sprintf()
249 *
250 * Return:
251 * - Address of written debug entry
252 * - %NULL if error
253 *
254 * floats and long long datatypes cannot be used as varargs.
255 */
256#define debug_sprintf_event(_id, _level, _fmt, ...) \
257({ \
258 debug_entry_t *__ret; \
259 debug_info_t *__id = _id; \
260 int __level = _level; \
261 \
262 if ((!__id) || (__level > __id->level)) \
263 __ret = NULL; \
264 else \
265 __ret = __debug_sprintf_event(__id, __level, \
266 _fmt, ## __VA_ARGS__); \
267 __ret; \
268})
269
270/**
271 * debug_exception() - writes binary debug entry to active debug area
272 * (if level <= actual debug level)
273 * and switches to next debug area
274 *
275 * @id: handle for debug log
276 * @level: debug level
277 * @data: pointer to data for debug entry
278 * @length: length of data in bytes
279 *
280 * Return:
281 * - Address of written debug entry
282 * - %NULL if error
283 */
284static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
285 void *data, int length)
286{
287 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
288 return NULL;
289 return debug_exception_common(id, level, data, length);
290}
291
292/**
293 * debug_int_exception() - writes unsigned int debug entry to active debug area
294 * (if level <= actual debug level)
295 * and switches to next debug area
296 *
297 * @id: handle for debug log
298 * @level: debug level
299 * @tag: integer value for debug entry
300 *
301 * Return:
302 * - Address of written debug entry
303 * - %NULL if error
304 */
305static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
306 unsigned int tag)
307{
308 unsigned int t = tag;
309
310 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
311 return NULL;
312 return debug_exception_common(id, level, &t, sizeof(unsigned int));
313}
314
315/**
316 * debug_long_exception() - writes long debug entry to active debug area
317 * (if level <= actual debug level)
318 * and switches to next debug area
319 *
320 * @id: handle for debug log
321 * @level: debug level
322 * @tag: long integer value for debug entry
323 *
324 * Return:
325 * - Address of written debug entry
326 * - %NULL if error
327 */
328static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
329 unsigned long tag)
330{
331 unsigned long t = tag;
332
333 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
334 return NULL;
335 return debug_exception_common(id, level, &t, sizeof(unsigned long));
336}
337
338/**
339 * debug_text_exception() - writes string debug entry in ascii format to active
340 * debug area (if level <= actual debug level)
341 * and switches to next debug area
342 * area
343 *
344 * @id: handle for debug log
345 * @level: debug level
346 * @txt: string for debug entry
347 *
348 * Return:
349 * - Address of written debug entry
350 * - %NULL if error
351 */
352static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
353 const char *txt)
354{
355 if ((!id) || (level > id->level) || (id->pages_per_area == 0))
356 return NULL;
357 return debug_exception_common(id, level, txt, strlen(txt));
358}
359
360/*
361 * IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
362 * stored in the s390dbf. See Documentation/arch/s390/s390dbf.rst for more details!
363 */
364extern debug_entry_t *
365__debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
366 __attribute__ ((format(printf, 3, 4)));
367
368
369/**
370 * debug_sprintf_exception() - writes debug entry with format string and
371 * varargs (longs) to active debug area
372 * (if level <= actual debug level)
373 * and switches to next debug area.
374 *
375 * @_id: handle for debug log
376 * @_level: debug level
377 * @_fmt: format string for debug entry
378 * @...: varargs used as in sprintf()
379 *
380 * Return:
381 * - Address of written debug entry
382 * - %NULL if error
383 *
384 * floats and long long datatypes cannot be used as varargs.
385 */
386#define debug_sprintf_exception(_id, _level, _fmt, ...) \
387({ \
388 debug_entry_t *__ret; \
389 debug_info_t *__id = _id; \
390 int __level = _level; \
391 \
392 if ((!__id) || (__level > __id->level)) \
393 __ret = NULL; \
394 else \
395 __ret = __debug_sprintf_exception(__id, __level, \
396 _fmt, ## __VA_ARGS__);\
397 __ret; \
398})
399
400int debug_register_view(debug_info_t *id, struct debug_view *view);
401
402int debug_unregister_view(debug_info_t *id, struct debug_view *view);
403
404#ifndef MODULE
405
406/*
407 * Note: Initial page and area numbers must be fixed to allow static
408 * initialization. This enables very early tracing. Changes to these values
409 * must be reflected in __DEFINE_STATIC_AREA.
410 */
411#define EARLY_PAGES 8
412#define EARLY_AREAS 1
413
414#define VNAME(var, suffix) __##var##_##suffix
415
416/*
417 * Define static areas for early trace data. During boot debug_register_static()
418 * will replace these with dynamically allocated areas to allow custom page and
419 * area sizes, and dynamic resizing.
420 */
421#define __DEFINE_STATIC_AREA(var) \
422static char VNAME(var, data)[EARLY_PAGES][PAGE_SIZE] __initdata; \
423static debug_entry_t *VNAME(var, pages)[EARLY_PAGES] __initdata = { \
424 (debug_entry_t *)VNAME(var, data)[0], \
425 (debug_entry_t *)VNAME(var, data)[1], \
426 (debug_entry_t *)VNAME(var, data)[2], \
427 (debug_entry_t *)VNAME(var, data)[3], \
428 (debug_entry_t *)VNAME(var, data)[4], \
429 (debug_entry_t *)VNAME(var, data)[5], \
430 (debug_entry_t *)VNAME(var, data)[6], \
431 (debug_entry_t *)VNAME(var, data)[7], \
432}; \
433static debug_entry_t **VNAME(var, areas)[EARLY_AREAS] __initdata = { \
434 (debug_entry_t **)VNAME(var, pages), \
435}; \
436static int VNAME(var, active_pages)[EARLY_AREAS] __initdata; \
437static int VNAME(var, active_entries)[EARLY_AREAS] __initdata
438
439#define __DEBUG_INFO_INIT(var, _name, _buf_size) { \
440 .next = NULL, \
441 .prev = NULL, \
442 .ref_count = REFCOUNT_INIT(1), \
443 .lock = __RAW_SPIN_LOCK_UNLOCKED(var.lock), \
444 .level = DEBUG_DEFAULT_LEVEL, \
445 .nr_areas = EARLY_AREAS, \
446 .pages_per_area = EARLY_PAGES, \
447 .buf_size = (_buf_size), \
448 .entry_size = sizeof(debug_entry_t) + (_buf_size), \
449 .areas = VNAME(var, areas), \
450 .active_area = 0, \
451 .active_pages = VNAME(var, active_pages), \
452 .active_entries = VNAME(var, active_entries), \
453 .debugfs_root_entry = NULL, \
454 .debugfs_entries = { NULL }, \
455 .views = { NULL }, \
456 .name = (_name), \
457 .mode = 0600, \
458}
459
460#define __REGISTER_STATIC_DEBUG_INFO(var, name, pages, areas, view) \
461static int __init VNAME(var, reg)(void) \
462{ \
463 int rc; \
464 \
465 rc = debug_register_static(&var, (pages), (areas)); \
466 if (rc) \
467 return rc; \
468 debug_register_view(&var, (view)); \
469 return 0; \
470} \
471arch_initcall(VNAME(var, reg))
472
473/**
474 * DEFINE_STATIC_DEBUG_INFO - Define static debug_info_t
475 *
476 * @var: Name of debug_info_t variable
477 * @name: Name of debug log (e.g. used for debugfs entry)
478 * @pages: Number of pages per area
479 * @nr_areas: Number of debug areas
480 * @buf_size: Size of data area in each debug entry
481 * @view: Pointer to debug view struct
482 *
483 * Define a static debug_info_t for early tracing. The associated debugfs log
484 * is automatically registered with the specified debug view.
485 *
486 * Important: Users of this macro must not call any of the
487 * debug_register/_unregister() functions for this debug_info_t!
488 *
489 * Note: Tracing will start with a fixed number of initial pages and areas.
490 * The debug area will be changed to use the specified numbers during
491 * arch_initcall.
492 */
493#define DEFINE_STATIC_DEBUG_INFO(var, name, pages, nr_areas, buf_size, view) \
494__DEFINE_STATIC_AREA(var); \
495static debug_info_t __refdata var = \
496 __DEBUG_INFO_INIT(var, (name), (buf_size)); \
497static debug_info_t __used __section(".s390dbf_info") *VNAME(var, info) = &var; \
498__REGISTER_STATIC_DEBUG_INFO(var, name, pages, nr_areas, view)
499
500int debug_register_static(debug_info_t *id, int pages_per_area, int nr_areas);
501
502#endif /* MODULE */
503
504#endif /* _ASM_S390_DEBUG_H */