Back to home page

OSCL-LXR
 
 

     

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  *   S/390 debug facility
0004  *
0005  *    Copyright IBM Corp. 1999, 2020
0006  */
0007 #ifndef DEBUG_H
0008 #define DEBUG_H
0009 
0010 #include <linux/string.h>
0011 #include <linux/spinlock.h>
0012 #include <linux/kernel.h>
0013 #include <linux/time.h>
0014 #include <linux/refcount.h>
0015 #include <linux/fs.h>
0016 #include <linux/init.h>
0017 
0018 #define DEBUG_MAX_LEVEL        6  /* debug levels range from 0 to 6 */
0019 #define DEBUG_OFF_LEVEL        -1 /* level where debug is switched off */
0020 #define DEBUG_FLUSH_ALL        -1 /* parameter to flush all areas */
0021 #define DEBUG_MAX_VIEWS        10 /* max number of views in proc fs */
0022 #define DEBUG_MAX_NAME_LEN     64 /* max length for a debugfs file name */
0023 #define DEBUG_DEFAULT_LEVEL    3  /* initial debug level */
0024 
0025 #define DEBUG_DIR_ROOT "s390dbf" /* name of debug root directory in proc fs */
0026 
0027 #define DEBUG_DATA(entry) (char *)(entry + 1) /* data is stored behind */
0028                           /* the entry information */
0029 
0030 #define __DEBUG_FEATURE_VERSION    3  /* version of debug feature */
0031 
0032 struct __debug_entry {
0033     unsigned long clock : 60;
0034     unsigned long exception :  1;
0035     unsigned long level :  3;
0036     void *caller;
0037     unsigned short cpu;
0038 } __packed;
0039 
0040 typedef struct __debug_entry debug_entry_t;
0041 
0042 struct debug_view;
0043 
0044 typedef struct debug_info {
0045     struct debug_info *next;
0046     struct debug_info *prev;
0047     refcount_t ref_count;
0048     spinlock_t lock;
0049     int level;
0050     int nr_areas;
0051     int pages_per_area;
0052     int buf_size;
0053     int entry_size;
0054     debug_entry_t ***areas;
0055     int active_area;
0056     int *active_pages;
0057     int *active_entries;
0058     struct dentry *debugfs_root_entry;
0059     struct dentry *debugfs_entries[DEBUG_MAX_VIEWS];
0060     struct debug_view *views[DEBUG_MAX_VIEWS];
0061     char name[DEBUG_MAX_NAME_LEN];
0062     umode_t mode;
0063 } debug_info_t;
0064 
0065 typedef int (debug_header_proc_t) (debug_info_t *id,
0066                    struct debug_view *view,
0067                    int area,
0068                    debug_entry_t *entry,
0069                    char *out_buf);
0070 
0071 typedef int (debug_format_proc_t) (debug_info_t *id,
0072                    struct debug_view *view, char *out_buf,
0073                    const char *in_buf);
0074 typedef int (debug_prolog_proc_t) (debug_info_t *id,
0075                    struct debug_view *view,
0076                    char *out_buf);
0077 typedef int (debug_input_proc_t) (debug_info_t *id,
0078                   struct debug_view *view,
0079                   struct file *file,
0080                   const char __user *user_buf,
0081                   size_t in_buf_size, loff_t *offset);
0082 
0083 int debug_dflt_header_fn(debug_info_t *id, struct debug_view *view,
0084              int area, debug_entry_t *entry, char *out_buf);
0085 
0086 struct debug_view {
0087     char name[DEBUG_MAX_NAME_LEN];
0088     debug_prolog_proc_t *prolog_proc;
0089     debug_header_proc_t *header_proc;
0090     debug_format_proc_t *format_proc;
0091     debug_input_proc_t  *input_proc;
0092     void            *private_data;
0093 };
0094 
0095 extern struct debug_view debug_hex_ascii_view;
0096 extern struct debug_view debug_sprintf_view;
0097 
0098 /* do NOT use the _common functions */
0099 
0100 debug_entry_t *debug_event_common(debug_info_t *id, int level,
0101                   const void *data, int length);
0102 
0103 debug_entry_t *debug_exception_common(debug_info_t *id, int level,
0104                       const void *data, int length);
0105 
0106 /* Debug Feature API: */
0107 
0108 debug_info_t *debug_register(const char *name, int pages, int nr_areas,
0109                  int buf_size);
0110 
0111 debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
0112                   int buf_size, umode_t mode, uid_t uid,
0113                   gid_t gid);
0114 
0115 void debug_unregister(debug_info_t *id);
0116 
0117 void debug_set_level(debug_info_t *id, int new_level);
0118 
0119 void debug_set_critical(void);
0120 
0121 void debug_stop_all(void);
0122 
0123 /**
0124  * debug_level_enabled() - Returns true if debug events for the specified
0125  *             level would be logged. Otherwise returns false.
0126  *
0127  * @id:     handle for debug log
0128  * @level:  debug level
0129  *
0130  * Return:
0131  * - %true if level is less or equal to the current debug level.
0132  */
0133 static inline bool debug_level_enabled(debug_info_t *id, int level)
0134 {
0135     return level <= id->level;
0136 }
0137 
0138 /**
0139  * debug_event() - writes binary debug entry to active debug area
0140  *         (if level <= actual debug level)
0141  *
0142  * @id:     handle for debug log
0143  * @level:  debug level
0144  * @data:   pointer to data for debug entry
0145  * @length: length of data in bytes
0146  *
0147  * Return:
0148  * - Address of written debug entry
0149  * - %NULL if error
0150  */
0151 static inline debug_entry_t *debug_event(debug_info_t *id, int level,
0152                      void *data, int length)
0153 {
0154     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0155         return NULL;
0156     return debug_event_common(id, level, data, length);
0157 }
0158 
0159 /**
0160  * debug_int_event() - writes unsigned integer debug entry to active debug area
0161  *             (if level <= actual debug level)
0162  *
0163  * @id:     handle for debug log
0164  * @level:  debug level
0165  * @tag:    integer value for debug entry
0166  *
0167  * Return:
0168  * - Address of written debug entry
0169  * - %NULL if error
0170  */
0171 static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
0172                          unsigned int tag)
0173 {
0174     unsigned int t = tag;
0175 
0176     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0177         return NULL;
0178     return debug_event_common(id, level, &t, sizeof(unsigned int));
0179 }
0180 
0181 /**
0182  * debug_long_event() - writes unsigned long debug entry to active debug area
0183  *             (if level <= actual debug level)
0184  *
0185  * @id:     handle for debug log
0186  * @level:  debug level
0187  * @tag:    long integer value for debug entry
0188  *
0189  * Return:
0190  * - Address of written debug entry
0191  * - %NULL if error
0192  */
0193 static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
0194                           unsigned long tag)
0195 {
0196     unsigned long t = tag;
0197 
0198     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0199         return NULL;
0200     return debug_event_common(id, level, &t, sizeof(unsigned long));
0201 }
0202 
0203 /**
0204  * debug_text_event() - writes string debug entry in ascii format to active
0205  *          debug area (if level <= actual debug level)
0206  *
0207  * @id:     handle for debug log
0208  * @level:  debug level
0209  * @txt:    string for debug entry
0210  *
0211  * Return:
0212  * - Address of written debug entry
0213  * - %NULL if error
0214  */
0215 static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
0216                           const char *txt)
0217 {
0218     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0219         return NULL;
0220     return debug_event_common(id, level, txt, strlen(txt));
0221 }
0222 
0223 /*
0224  * IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
0225  * stored in the s390dbf. See Documentation/s390/s390dbf.rst for more details!
0226  */
0227 extern debug_entry_t *
0228 __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
0229     __attribute__ ((format(printf, 3, 4)));
0230 
0231 /**
0232  * debug_sprintf_event() - writes debug entry with format string
0233  *             and varargs (longs) to active debug area
0234  *             (if level $<=$ actual debug level).
0235  *
0236  * @_id:    handle for debug log
0237  * @_level: debug level
0238  * @_fmt:   format string for debug entry
0239  * @...:    varargs used as in sprintf()
0240  *
0241  * Return:
0242  * - Address of written debug entry
0243  * - %NULL if error
0244  *
0245  * floats and long long datatypes cannot be used as varargs.
0246  */
0247 #define debug_sprintf_event(_id, _level, _fmt, ...)         \
0248 ({                                  \
0249     debug_entry_t *__ret;                       \
0250     debug_info_t *__id = _id;                   \
0251     int __level = _level;                       \
0252                                     \
0253     if ((!__id) || (__level > __id->level))             \
0254         __ret = NULL;                       \
0255     else                                \
0256         __ret = __debug_sprintf_event(__id, __level,        \
0257                           _fmt, ## __VA_ARGS__);    \
0258     __ret;                              \
0259 })
0260 
0261 /**
0262  * debug_exception() - writes binary debug entry to active debug area
0263  *             (if level <= actual debug level)
0264  *             and switches to next debug area
0265  *
0266  * @id:     handle for debug log
0267  * @level:  debug level
0268  * @data:   pointer to data for debug entry
0269  * @length: length of data in bytes
0270  *
0271  * Return:
0272  * - Address of written debug entry
0273  * - %NULL if error
0274  */
0275 static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
0276                          void *data, int length)
0277 {
0278     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0279         return NULL;
0280     return debug_exception_common(id, level, data, length);
0281 }
0282 
0283 /**
0284  * debug_int_exception() - writes unsigned int debug entry to active debug area
0285  *             (if level <= actual debug level)
0286  *             and switches to next debug area
0287  *
0288  * @id:     handle for debug log
0289  * @level:  debug level
0290  * @tag:    integer value for debug entry
0291  *
0292  * Return:
0293  * - Address of written debug entry
0294  * - %NULL if error
0295  */
0296 static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
0297                          unsigned int tag)
0298 {
0299     unsigned int t = tag;
0300 
0301     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0302         return NULL;
0303     return debug_exception_common(id, level, &t, sizeof(unsigned int));
0304 }
0305 
0306 /**
0307  * debug_long_exception() - writes long debug entry to active debug area
0308  *             (if level <= actual debug level)
0309  *             and switches to next debug area
0310  *
0311  * @id:     handle for debug log
0312  * @level:  debug level
0313  * @tag:    long integer value for debug entry
0314  *
0315  * Return:
0316  * - Address of written debug entry
0317  * - %NULL if error
0318  */
0319 static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
0320                            unsigned long tag)
0321 {
0322     unsigned long t = tag;
0323 
0324     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0325         return NULL;
0326     return debug_exception_common(id, level, &t, sizeof(unsigned long));
0327 }
0328 
0329 /**
0330  * debug_text_exception() - writes string debug entry in ascii format to active
0331  *              debug area (if level <= actual debug level)
0332  *              and switches to next debug area
0333  * area
0334  *
0335  * @id: handle for debug log
0336  * @level:  debug level
0337  * @txt:    string for debug entry
0338  *
0339  * Return:
0340  * - Address of written debug entry
0341  * - %NULL if error
0342  */
0343 static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
0344                           const char *txt)
0345 {
0346     if ((!id) || (level > id->level) || (id->pages_per_area == 0))
0347         return NULL;
0348     return debug_exception_common(id, level, txt, strlen(txt));
0349 }
0350 
0351 /*
0352  * IMPORTANT: Use "%s" in sprintf format strings with care! Only pointers are
0353  * stored in the s390dbf. See Documentation/s390/s390dbf.rst for more details!
0354  */
0355 extern debug_entry_t *
0356 __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
0357     __attribute__ ((format(printf, 3, 4)));
0358 
0359 
0360 /**
0361  * debug_sprintf_exception() - writes debug entry with format string and
0362  *                 varargs (longs) to active debug area
0363  *                 (if level <= actual debug level)
0364  *                 and switches to next debug area.
0365  *
0366  * @_id:    handle for debug log
0367  * @_level: debug level
0368  * @_fmt:   format string for debug entry
0369  * @...:    varargs used as in sprintf()
0370  *
0371  * Return:
0372  * - Address of written debug entry
0373  * - %NULL if error
0374  *
0375  * floats and long long datatypes cannot be used as varargs.
0376  */
0377 #define debug_sprintf_exception(_id, _level, _fmt, ...)         \
0378 ({                                  \
0379     debug_entry_t *__ret;                       \
0380     debug_info_t *__id = _id;                   \
0381     int __level = _level;                       \
0382                                     \
0383     if ((!__id) || (__level > __id->level))             \
0384         __ret = NULL;                       \
0385     else                                \
0386         __ret = __debug_sprintf_exception(__id, __level,    \
0387                           _fmt, ## __VA_ARGS__);\
0388     __ret;                              \
0389 })
0390 
0391 int debug_register_view(debug_info_t *id, struct debug_view *view);
0392 
0393 int debug_unregister_view(debug_info_t *id, struct debug_view *view);
0394 
0395 #ifndef MODULE
0396 
0397 /*
0398  * Note: Initial page and area numbers must be fixed to allow static
0399  * initialization. This enables very early tracing. Changes to these values
0400  * must be reflected in __DEFINE_STATIC_AREA.
0401  */
0402 #define EARLY_PAGES     8
0403 #define EARLY_AREAS     1
0404 
0405 #define VNAME(var, suffix)  __##var##_##suffix
0406 
0407 /*
0408  * Define static areas for early trace data. During boot debug_register_static()
0409  * will replace these with dynamically allocated areas to allow custom page and
0410  * area sizes, and dynamic resizing.
0411  */
0412 #define __DEFINE_STATIC_AREA(var)                   \
0413 static char VNAME(var, data)[EARLY_PAGES][PAGE_SIZE] __initdata;    \
0414 static debug_entry_t *VNAME(var, pages)[EARLY_PAGES] __initdata = { \
0415     (debug_entry_t *)VNAME(var, data)[0],               \
0416     (debug_entry_t *)VNAME(var, data)[1],               \
0417     (debug_entry_t *)VNAME(var, data)[2],               \
0418     (debug_entry_t *)VNAME(var, data)[3],               \
0419     (debug_entry_t *)VNAME(var, data)[4],               \
0420     (debug_entry_t *)VNAME(var, data)[5],               \
0421     (debug_entry_t *)VNAME(var, data)[6],               \
0422     (debug_entry_t *)VNAME(var, data)[7],               \
0423 };                                  \
0424 static debug_entry_t **VNAME(var, areas)[EARLY_AREAS] __initdata = {    \
0425     (debug_entry_t **)VNAME(var, pages),                \
0426 };                                  \
0427 static int VNAME(var, active_pages)[EARLY_AREAS] __initdata;        \
0428 static int VNAME(var, active_entries)[EARLY_AREAS] __initdata
0429 
0430 #define __DEBUG_INFO_INIT(var, _name, _buf_size) {          \
0431     .next = NULL,                           \
0432     .prev = NULL,                           \
0433     .ref_count = REFCOUNT_INIT(1),                  \
0434     .lock = __SPIN_LOCK_UNLOCKED(var.lock),             \
0435     .level = DEBUG_DEFAULT_LEVEL,                   \
0436     .nr_areas = EARLY_AREAS,                    \
0437     .pages_per_area = EARLY_PAGES,                  \
0438     .buf_size = (_buf_size),                    \
0439     .entry_size = sizeof(debug_entry_t) + (_buf_size),      \
0440     .areas = VNAME(var, areas),                 \
0441     .active_area = 0,                       \
0442     .active_pages = VNAME(var, active_pages),           \
0443     .active_entries = VNAME(var, active_entries),           \
0444     .debugfs_root_entry = NULL,                 \
0445     .debugfs_entries = { NULL },                    \
0446     .views = { NULL },                      \
0447     .name = (_name),                        \
0448     .mode = 0600,                           \
0449 }
0450 
0451 #define __REGISTER_STATIC_DEBUG_INFO(var, name, pages, areas, view) \
0452 static int __init VNAME(var, reg)(void)                 \
0453 {                                   \
0454     debug_register_static(&var, (pages), (areas));          \
0455     debug_register_view(&var, (view));              \
0456     return 0;                           \
0457 }                                   \
0458 arch_initcall(VNAME(var, reg))
0459 
0460 /**
0461  * DEFINE_STATIC_DEBUG_INFO - Define static debug_info_t
0462  *
0463  * @var: Name of debug_info_t variable
0464  * @name: Name of debug log (e.g. used for debugfs entry)
0465  * @pages: Number of pages per area
0466  * @nr_areas: Number of debug areas
0467  * @buf_size: Size of data area in each debug entry
0468  * @view: Pointer to debug view struct
0469  *
0470  * Define a static debug_info_t for early tracing. The associated debugfs log
0471  * is automatically registered with the specified debug view.
0472  *
0473  * Important: Users of this macro must not call any of the
0474  * debug_register/_unregister() functions for this debug_info_t!
0475  *
0476  * Note: Tracing will start with a fixed number of initial pages and areas.
0477  * The debug area will be changed to use the specified numbers during
0478  * arch_initcall.
0479  */
0480 #define DEFINE_STATIC_DEBUG_INFO(var, name, pages, nr_areas, buf_size, view) \
0481 __DEFINE_STATIC_AREA(var);                      \
0482 static debug_info_t __refdata var =                 \
0483     __DEBUG_INFO_INIT(var, (name), (buf_size));         \
0484 __REGISTER_STATIC_DEBUG_INFO(var, name, pages, nr_areas, view)
0485 
0486 void debug_register_static(debug_info_t *id, int pages_per_area, int nr_areas);
0487 
0488 #endif /* MODULE */
0489 
0490 #endif /* DEBUG_H */
[ Source navigation ] [ Diff markup ] [ Identifier search ] [ general search ]

This page was automatically generated by the 2.1.0 LXR engine.

The LXR team
Valid CSS 2.1! Valid HTML 4.01!