1 /* $NetBSD: drm_print.h,v 1.3 2021/12/19 01:54:20 riastradh Exp $ */
2
3 /*
4 * Copyright (C) 2016 Red Hat
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a
7 * copy of this software and associated documentation files (the "Software"),
8 * to deal in the Software without restriction, including without limitation
9 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 * and/or sell copies of the Software, and to permit persons to whom the
11 * Software is furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 * OTHER DEALINGS IN THE SOFTWARE.
23 *
24 * Authors:
25 * Rob Clark <robdclark@gmail.com>
26 */
27
28 #ifndef DRM_PRINT_H_
29 #define DRM_PRINT_H_
30
31 #include <linux/compiler.h>
32 #include <linux/printk.h>
33 #include <linux/seq_file.h>
34 #include <linux/device.h>
35 #include <linux/debugfs.h>
36
37 #include <drm/drm.h>
38
39 /* Do *not* use outside of drm_print.[ch]! */
40 extern unsigned int __drm_debug;
41
42 /**
43 * DOC: print
44 *
45 * A simple wrapper for dev_printk(), seq_printf(), etc. Allows same
46 * debug code to be used for both debugfs and printk logging.
47 *
48 * For example::
49 *
50 * void log_some_info(struct drm_printer *p)
51 * {
52 * drm_printf(p, "foo=%d\n", foo);
53 * drm_printf(p, "bar=%d\n", bar);
54 * }
55 *
56 * #ifdef CONFIG_DEBUG_FS
57 * void debugfs_show(struct seq_file *f)
58 * {
59 * struct drm_printer p = drm_seq_file_printer(f);
60 * log_some_info(&p);
61 * }
62 * #endif
63 *
64 * void some_other_function(...)
65 * {
66 * struct drm_printer p = drm_info_printer(drm->dev);
67 * log_some_info(&p);
68 * }
69 */
70
71 /**
72 * struct drm_printer - drm output "stream"
73 *
74 * Do not use struct members directly. Use drm_printer_seq_file(),
75 * drm_printer_info(), etc to initialize. And drm_printf() for output.
76 */
77 struct drm_printer {
78 /* private: */
79 void (*printfn)(struct drm_printer *p, struct va_format *vaf);
80 void (*puts)(struct drm_printer *p, const char *str);
81 void *arg;
82 const char *prefix;
83 };
84
85 void __drm_printfn_coredump(struct drm_printer *p, struct va_format *vaf);
86 void __drm_puts_coredump(struct drm_printer *p, const char *str);
87 void __drm_printfn_seq_file(struct drm_printer *p, struct va_format *vaf);
88 void __drm_puts_seq_file(struct drm_printer *p, const char *str);
89 void __drm_printfn_info(struct drm_printer *p, struct va_format *vaf);
90 void __drm_printfn_debug(struct drm_printer *p, struct va_format *vaf);
91 void __drm_printfn_err(struct drm_printer *p, struct va_format *vaf);
92
93 __printf(2, 3)
94 void drm_printf(struct drm_printer *p, const char *f, ...);
95 void drm_puts(struct drm_printer *p, const char *str);
96 #ifndef __NetBSD__
97 void drm_print_regset32(struct drm_printer *p, struct debugfs_regset32 *regset);
98 #endif
99 void drm_print_bits(struct drm_printer *p, unsigned long value,
100 const char * const bits[], unsigned int nbits);
101
102 __printf(2, 0)
103 /**
104 * drm_vprintf - print to a &drm_printer stream
105 * @p: the &drm_printer
106 * @fmt: format string
107 * @va: the va_list
108 */
109 static inline void
drm_vprintf(struct drm_printer * p,const char * fmt,va_list * va)110 drm_vprintf(struct drm_printer *p, const char *fmt, va_list *va)
111 {
112 struct va_format vaf = { .fmt = fmt, .va = va };
113
114 p->printfn(p, &vaf);
115 }
116
117 /**
118 * drm_printf_indent - Print to a &drm_printer stream with indentation
119 * @printer: DRM printer
120 * @indent: Tab indentation level (max 5)
121 * @fmt: Format string
122 */
123 #define drm_printf_indent(printer, indent, fmt, ...) \
124 drm_printf((printer), "%.*s" fmt, (indent), "\t\t\t\t\tX", ##__VA_ARGS__)
125
126 /**
127 * struct drm_print_iterator - local struct used with drm_printer_coredump
128 * @data: Pointer to the devcoredump output buffer
129 * @start: The offset within the buffer to start writing
130 * @remain: The number of bytes to write for this iteration
131 */
132 struct drm_print_iterator {
133 void *data;
134 ssize_t start;
135 ssize_t remain;
136 /* private: */
137 ssize_t offset;
138 };
139
140 /**
141 * drm_coredump_printer - construct a &drm_printer that can output to a buffer
142 * from the read function for devcoredump
143 * @iter: A pointer to a struct drm_print_iterator for the read instance
144 *
145 * This wrapper extends drm_printf() to work with a dev_coredumpm() callback
146 * function. The passed in drm_print_iterator struct contains the buffer
147 * pointer, size and offset as passed in from devcoredump.
148 *
149 * For example::
150 *
151 * void coredump_read(char *buffer, loff_t offset, size_t count,
152 * void *data, size_t datalen)
153 * {
154 * struct drm_print_iterator iter;
155 * struct drm_printer p;
156 *
157 * iter.data = buffer;
158 * iter.start = offset;
159 * iter.remain = count;
160 *
161 * p = drm_coredump_printer(&iter);
162 *
163 * drm_printf(p, "foo=%d\n", foo);
164 * }
165 *
166 * void makecoredump(...)
167 * {
168 * ...
169 * dev_coredumpm(dev, THIS_MODULE, data, 0, GFP_KERNEL,
170 * coredump_read, ...)
171 * }
172 *
173 * RETURNS:
174 * The &drm_printer object
175 */
176 static inline struct drm_printer
drm_coredump_printer(struct drm_print_iterator * iter)177 drm_coredump_printer(struct drm_print_iterator *iter)
178 {
179 struct drm_printer p = {
180 .printfn = __drm_printfn_coredump,
181 .puts = __drm_puts_coredump,
182 .arg = iter,
183 };
184
185 /* Set the internal offset of the iterator to zero */
186 iter->offset = 0;
187
188 return p;
189 }
190
191 /**
192 * drm_seq_file_printer - construct a &drm_printer that outputs to &seq_file
193 * @f: the &struct seq_file to output to
194 *
195 * RETURNS:
196 * The &drm_printer object
197 */
drm_seq_file_printer(struct seq_file * f)198 static inline struct drm_printer drm_seq_file_printer(struct seq_file *f)
199 {
200 struct drm_printer p = {
201 .printfn = __drm_printfn_seq_file,
202 .puts = __drm_puts_seq_file,
203 .arg = f,
204 };
205 return p;
206 }
207
208 /**
209 * drm_info_printer - construct a &drm_printer that outputs to dev_printk()
210 * @dev: the &struct device pointer
211 *
212 * RETURNS:
213 * The &drm_printer object
214 */
drm_info_printer(struct device * dev)215 static inline struct drm_printer drm_info_printer(struct device *dev)
216 {
217 struct drm_printer p = {
218 .printfn = __drm_printfn_info,
219 .arg = dev,
220 };
221 return p;
222 }
223
224 /**
225 * drm_debug_printer - construct a &drm_printer that outputs to pr_debug()
226 * @prefix: debug output prefix
227 *
228 * RETURNS:
229 * The &drm_printer object
230 */
drm_debug_printer(const char * prefix)231 static inline struct drm_printer drm_debug_printer(const char *prefix)
232 {
233 struct drm_printer p = {
234 .printfn = __drm_printfn_debug,
235 .prefix = prefix
236 };
237 return p;
238 }
239
240 /**
241 * drm_err_printer - construct a &drm_printer that outputs to pr_err()
242 * @prefix: debug output prefix
243 *
244 * RETURNS:
245 * The &drm_printer object
246 */
drm_err_printer(const char * prefix)247 static inline struct drm_printer drm_err_printer(const char *prefix)
248 {
249 struct drm_printer p = {
250 .printfn = __drm_printfn_err,
251 .prefix = prefix
252 };
253 return p;
254 }
255
256 /**
257 * enum drm_debug_category - The DRM debug categories
258 *
259 * Each of the DRM debug logging macros use a specific category, and the logging
260 * is filtered by the drm.debug module parameter. This enum specifies the values
261 * for the interface.
262 *
263 * Each DRM_DEBUG_<CATEGORY> macro logs to DRM_UT_<CATEGORY> category, except
264 * DRM_DEBUG() logs to DRM_UT_CORE.
265 *
266 * Enabling verbose debug messages is done through the drm.debug parameter, each
267 * category being enabled by a bit:
268 *
269 * - drm.debug=0x1 will enable CORE messages
270 * - drm.debug=0x2 will enable DRIVER messages
271 * - drm.debug=0x3 will enable CORE and DRIVER messages
272 * - ...
273 * - drm.debug=0x1ff will enable all messages
274 *
275 * An interesting feature is that it's possible to enable verbose logging at
276 * run-time by echoing the debug value in its sysfs node::
277 *
278 * # echo 0xf > /sys/module/drm/parameters/debug
279 *
280 */
281 enum drm_debug_category {
282 /**
283 * @DRM_UT_CORE: Used in the generic drm code: drm_ioctl.c, drm_mm.c,
284 * drm_memory.c, ...
285 */
286 DRM_UT_CORE = 0x01,
287 /**
288 * @DRM_UT_DRIVER: Used in the vendor specific part of the driver: i915,
289 * radeon, ... macro.
290 */
291 DRM_UT_DRIVER = 0x02,
292 /**
293 * @DRM_UT_KMS: Used in the modesetting code.
294 */
295 DRM_UT_KMS = 0x04,
296 /**
297 * @DRM_UT_PRIME: Used in the prime code.
298 */
299 DRM_UT_PRIME = 0x08,
300 /**
301 * @DRM_UT_ATOMIC: Used in the atomic code.
302 */
303 DRM_UT_ATOMIC = 0x10,
304 /**
305 * @DRM_UT_VBL: Used for verbose debug message in the vblank code.
306 */
307 DRM_UT_VBL = 0x20,
308 /**
309 * @DRM_UT_STATE: Used for verbose atomic state debugging.
310 */
311 DRM_UT_STATE = 0x40,
312 /**
313 * @DRM_UT_LEASE: Used in the lease code.
314 */
315 DRM_UT_LEASE = 0x80,
316 /**
317 * @DRM_UT_DP: Used in the DP code.
318 */
319 DRM_UT_DP = 0x100,
320 };
321
drm_debug_enabled(enum drm_debug_category category)322 static inline bool drm_debug_enabled(enum drm_debug_category category)
323 {
324 return unlikely(__drm_debug & category);
325 }
326
327 /*
328 * struct device based logging
329 *
330 * Prefer drm_device based logging over device or prink based logging.
331 */
332
333 __printf(3, 4)
334 void drm_dev_printk(const struct device *dev, const char *level,
335 const char *format, ...);
336 __printf(3, 4)
337 void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
338 const char *format, ...);
339
340 /**
341 * Error output.
342 *
343 * @dev: device pointer
344 * @fmt: printf() like format string.
345 */
346 #define DRM_DEV_ERROR(dev, fmt, ...) \
347 drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__)
348
349 /**
350 * Rate limited error output. Like DRM_ERROR() but won't flood the log.
351 *
352 * @dev: device pointer
353 * @fmt: printf() like format string.
354 */
355 #define DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) \
356 ({ \
357 static DEFINE_RATELIMIT_STATE(_rs, \
358 DEFAULT_RATELIMIT_INTERVAL, \
359 DEFAULT_RATELIMIT_BURST); \
360 \
361 if (__ratelimit(&_rs)) \
362 DRM_DEV_ERROR(dev, fmt, ##__VA_ARGS__); \
363 })
364
365 #define DRM_DEV_INFO(dev, fmt, ...) \
366 drm_dev_printk(dev, KERN_INFO, fmt, ##__VA_ARGS__)
367
368 #define DRM_DEV_INFO_ONCE(dev, fmt, ...) \
369 ({ \
370 static bool __print_once __read_mostly; \
371 if (!__print_once) { \
372 __print_once = true; \
373 DRM_DEV_INFO(dev, fmt, ##__VA_ARGS__); \
374 } \
375 })
376
377 /**
378 * Debug output.
379 *
380 * @dev: device pointer
381 * @fmt: printf() like format string.
382 */
383 #define DRM_DEV_DEBUG(dev, fmt, ...) \
384 drm_dev_dbg(dev, DRM_UT_CORE, fmt, ##__VA_ARGS__)
385 #define DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) \
386 drm_dev_dbg(dev, DRM_UT_DRIVER, fmt, ##__VA_ARGS__)
387 #define DRM_DEV_DEBUG_KMS(dev, fmt, ...) \
388 drm_dev_dbg(dev, DRM_UT_KMS, fmt, ##__VA_ARGS__)
389 #define DRM_DEV_DEBUG_PRIME(dev, fmt, ...) \
390 drm_dev_dbg(dev, DRM_UT_PRIME, fmt, ##__VA_ARGS__)
391 #define DRM_DEV_DEBUG_ATOMIC(dev, fmt, ...) \
392 drm_dev_dbg(dev, DRM_UT_ATOMIC, fmt, ##__VA_ARGS__)
393 #define DRM_DEV_DEBUG_VBL(dev, fmt, ...) \
394 drm_dev_dbg(dev, DRM_UT_VBL, fmt, ##__VA_ARGS__)
395 #define DRM_DEV_DEBUG_DP(dev, fmt, ...) \
396 drm_dev_dbg(dev, DRM_UT_DP, fmt, ## __VA_ARGS__)
397
398 #define _DRM_DEV_DEFINE_DEBUG_RATELIMITED(dev, category, fmt, ...) \
399 ({ \
400 static DEFINE_RATELIMIT_STATE(_rs, \
401 DEFAULT_RATELIMIT_INTERVAL, \
402 DEFAULT_RATELIMIT_BURST); \
403 if (__ratelimit(&_rs)) \
404 drm_dev_dbg(dev, category, fmt, ##__VA_ARGS__); \
405 })
406
407 /**
408 * Rate limited debug output. Like DRM_DEBUG() but won't flood the log.
409 *
410 * @dev: device pointer
411 * @fmt: printf() like format string.
412 */
413 #define DRM_DEV_DEBUG_RATELIMITED(dev, fmt, ...) \
414 _DEV_DRM_DEFINE_DEBUG_RATELIMITED(dev, DRM_UT_CORE, \
415 fmt, ##__VA_ARGS__)
416 #define DRM_DEV_DEBUG_DRIVER_RATELIMITED(dev, fmt, ...) \
417 _DRM_DEV_DEFINE_DEBUG_RATELIMITED(dev, DRM_UT_DRIVER, \
418 fmt, ##__VA_ARGS__)
419 #define DRM_DEV_DEBUG_KMS_RATELIMITED(dev, fmt, ...) \
420 _DRM_DEV_DEFINE_DEBUG_RATELIMITED(dev, DRM_UT_KMS, \
421 fmt, ##__VA_ARGS__)
422 #define DRM_DEV_DEBUG_PRIME_RATELIMITED(dev, fmt, ...) \
423 _DRM_DEV_DEFINE_DEBUG_RATELIMITED(dev, DRM_UT_PRIME, \
424 fmt, ##__VA_ARGS__)
425
426 /*
427 * struct drm_device based logging
428 *
429 * Prefer drm_device based logging over device or prink based logging.
430 */
431
432 /* Helper for struct drm_device based logging. */
433 #define __drm_printk(drm, level, type, fmt, ...) \
434 dev_##level##type((drm)->dev, "[drm] " fmt, ##__VA_ARGS__)
435
436
437 #define drm_info(drm, fmt, ...) \
438 __drm_printk((drm), info,, fmt, ##__VA_ARGS__)
439
440 #define drm_notice(drm, fmt, ...) \
441 __drm_printk((drm), notice,, fmt, ##__VA_ARGS__)
442
443 #define drm_warn(drm, fmt, ...) \
444 __drm_printk((drm), warn,, fmt, ##__VA_ARGS__)
445
446 #define drm_err(drm, fmt, ...) \
447 __drm_printk((drm), err,, "*ERROR* " fmt, ##__VA_ARGS__)
448
449
450 #define drm_info_once(drm, fmt, ...) \
451 __drm_printk((drm), info, _once, fmt, ##__VA_ARGS__)
452
453 #define drm_notice_once(drm, fmt, ...) \
454 __drm_printk((drm), notice, _once, fmt, ##__VA_ARGS__)
455
456 #define drm_warn_once(drm, fmt, ...) \
457 __drm_printk((drm), warn, _once, fmt, ##__VA_ARGS__)
458
459 #define drm_err_once(drm, fmt, ...) \
460 __drm_printk((drm), err, _once, "*ERROR* " fmt, ##__VA_ARGS__)
461
462
463 #define drm_err_ratelimited(drm, fmt, ...) \
464 __drm_printk((drm), err, _ratelimited, "*ERROR* " fmt, ##__VA_ARGS__)
465
466
467 #define drm_dbg_core(drm, fmt, ...) \
468 drm_dev_dbg((drm)->dev, DRM_UT_CORE, fmt, ##__VA_ARGS__)
469 #define drm_dbg(drm, fmt, ...) \
470 drm_dev_dbg((drm)->dev, DRM_UT_DRIVER, fmt, ##__VA_ARGS__)
471 #define drm_dbg_kms(drm, fmt, ...) \
472 drm_dev_dbg((drm)->dev, DRM_UT_KMS, fmt, ##__VA_ARGS__)
473 #define drm_dbg_prime(drm, fmt, ...) \
474 drm_dev_dbg((drm)->dev, DRM_UT_PRIME, fmt, ##__VA_ARGS__)
475 #define drm_dbg_atomic(drm, fmt, ...) \
476 drm_dev_dbg((drm)->dev, DRM_UT_ATOMIC, fmt, ##__VA_ARGS__)
477 #define drm_dbg_vbl(drm, fmt, ...) \
478 drm_dev_dbg((drm)->dev, DRM_UT_VBL, fmt, ##__VA_ARGS__)
479 #define drm_dbg_state(drm, fmt, ...) \
480 drm_dev_dbg((drm)->dev, DRM_UT_STATE, fmt, ##__VA_ARGS__)
481 #define drm_dbg_lease(drm, fmt, ...) \
482 drm_dev_dbg((drm)->dev, DRM_UT_LEASE, fmt, ##__VA_ARGS__)
483 #define drm_dbg_dp(drm, fmt, ...) \
484 drm_dev_dbg((drm)->dev, DRM_UT_DP, fmt, ##__VA_ARGS__)
485
486
487 /*
488 * printk based logging
489 *
490 * Prefer drm_device based logging over device or prink based logging.
491 */
492
493 __printf(2, 3)
494 void __drm_dbg(enum drm_debug_category category, const char *format, ...);
495 __printf(1, 2)
496 void __drm_err(const char *format, ...);
497
498 /* Macros to make printk easier */
499
500 #define _DRM_PRINTK(once, level, fmt, ...) \
501 printk##once(KERN_##level "[" DRM_NAME "] " fmt, ##__VA_ARGS__)
502
503 #define DRM_INFO(fmt, ...) \
504 _DRM_PRINTK(, INFO, fmt, ##__VA_ARGS__)
505 #define DRM_NOTE(fmt, ...) \
506 _DRM_PRINTK(, NOTICE, fmt, ##__VA_ARGS__)
507 #define DRM_WARN(fmt, ...) \
508 _DRM_PRINTK(, WARNING, fmt, ##__VA_ARGS__)
509
510 #define DRM_INFO_ONCE(fmt, ...) \
511 _DRM_PRINTK(_once, INFO, fmt, ##__VA_ARGS__)
512 #define DRM_NOTE_ONCE(fmt, ...) \
513 _DRM_PRINTK(_once, NOTICE, fmt, ##__VA_ARGS__)
514 #define DRM_WARN_ONCE(fmt, ...) \
515 _DRM_PRINTK(_once, WARNING, fmt, ##__VA_ARGS__)
516
517 #define DRM_ERROR(fmt, ...) \
518 __drm_err(fmt, ##__VA_ARGS__)
519
520 #define DRM_ERROR_RATELIMITED(fmt, ...) \
521 DRM_DEV_ERROR_RATELIMITED(NULL, fmt, ##__VA_ARGS__)
522
523 #define DRM_DEBUG(fmt, ...) \
524 __drm_dbg(DRM_UT_CORE, fmt, ##__VA_ARGS__)
525
526 #define DRM_DEBUG_DRIVER(fmt, ...) \
527 __drm_dbg(DRM_UT_DRIVER, fmt, ##__VA_ARGS__)
528
529 #define DRM_DEBUG_KMS(fmt, ...) \
530 __drm_dbg(DRM_UT_KMS, fmt, ##__VA_ARGS__)
531
532 #define DRM_DEBUG_PRIME(fmt, ...) \
533 __drm_dbg(DRM_UT_PRIME, fmt, ##__VA_ARGS__)
534
535 #define DRM_DEBUG_ATOMIC(fmt, ...) \
536 __drm_dbg(DRM_UT_ATOMIC, fmt, ##__VA_ARGS__)
537
538 #define DRM_DEBUG_VBL(fmt, ...) \
539 __drm_dbg(DRM_UT_VBL, fmt, ##__VA_ARGS__)
540
541 #define DRM_DEBUG_LEASE(fmt, ...) \
542 __drm_dbg(DRM_UT_LEASE, fmt, ##__VA_ARGS__)
543
544 #define DRM_DEBUG_DP(fmt, ...) \
545 __drm_dbg(DRM_UT_DP, fmt, ## __VA_ARGS__)
546
547
548 #define DRM_DEBUG_RATELIMITED(fmt, ...) \
549 DRM_DEV_DEBUG_RATELIMITED(NULL, fmt, ##__VA_ARGS__)
550
551 #define DRM_DEBUG_DRIVER_RATELIMITED(fmt, ...) \
552 DRM_DEV_DEBUG_DRIVER_RATELIMITED(NULL, fmt, ##__VA_ARGS__)
553
554 #define DRM_DEBUG_KMS_RATELIMITED(fmt, ...) \
555 DRM_DEV_DEBUG_KMS_RATELIMITED(NULL, fmt, ##__VA_ARGS__)
556
557 #define DRM_DEBUG_PRIME_RATELIMITED(fmt, ...) \
558 DRM_DEV_DEBUG_PRIME_RATELIMITED(NULL, fmt, ##__VA_ARGS__)
559
560 #endif /* DRM_PRINT_H_ */
561