This is the documentation I have missed when I looked for help
how to do proper logging. Hopefully it can help others.
Signed-off-by: Sam Ravnborg <sam@xxxxxxxxxxxx>
Cc: Jani Nikula <jani.nikula@xxxxxxxxx>
Cc: Sean Paul <sean@xxxxxxxxxx>
Cc: Daniel Vetter <daniel@xxxxxxxx>
---
Documentation/gpu/drm-internals.rst | 6 ++
include/drm/drm_print.h | 91 ++++++++++++++++++++++++++---
2 files changed, 90 insertions(+), 7 deletions(-)
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index a73320576ca9..c2093611999c 100644
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -164,6 +164,12 @@ File Operations
Misc Utilities
==============
+Logging
+-------
+
+.. kernel-doc:: include/drm/drm_print.h
+ :doc: logging
+
Printer
-------
diff --git a/include/drm/drm_print.h b/include/drm/drm_print.h
index 8f99d389792d..e9e31ace0afa 100644
--- a/include/drm/drm_print.h
+++ b/include/drm/drm_print.h
@@ -250,22 +250,42 @@ static inline struct drm_printer drm_err_printer(const char *prefix)
}
/**
- * enum drm_debug_category - The DRM debug categories
+ * DOC: logging
+ *
+ * There is a set of functions/macros available used for logging
+ * in the DRM subsystem.
+ * Using the drm logging function enables that the logging is consistently
+ * prefixed with *[drm]* thus the logging is easy to recognize.
+ *
+ * Example of logging with *[drm]* prefix::
*
- * Each of the DRM debug logging macros use a specific category, and the logging
- * is filtered by the drm.debug module parameter. This enum specifies the values
- * for the interface.
+ * [drm] Supports vblank timestamp caching Rev 2 (21.10.2013).
+ * [drm] Driver supports precise vblank timestamp query.
*
- * Each DRM_DEBUG_<CATEGORY> macro logs to DRM_UT_<CATEGORY> category, except
- * DRM_DEBUG() logs to DRM_UT_CORE.
+ *
+ * Each of the debug logging macros use a specific category, and the logging
+ * is filtered by the drm.debug module parameter. The &drm_debug_category enum
+ * specifies the values for the interface.
+ *
+ * Each drm_dbg_<category> macro logs to a DRM_UT_<category> category,
+ * except drm_dbg() that logs to DRM_UT_DRIVER.
*
* Enabling verbose debug messages is done through the drm.debug parameter, each
* category being enabled by a bit:
*
* - drm.debug=0x1 will enable CORE messages
* - drm.debug=0x2 will enable DRIVER messages
+ * - drm.debug=0x4 will enable KMS messages
+ * - drm.debug=0x8 will enable PRIME messages
+ * - drm.debug=0x10 will enable ATOMIC messages
+ * - drm.debug=0x20 will enable VBL messages
+ * - drm.debug=0x40 will enable STATE messages
+ * - drm.debug=0x80 will enable LEASE messages
+ * - drm.debug=0x100 will enable DP messages
+ *
+ * To enable more than one category OR the values - examples:
+ *
* - drm.debug=0x3 will enable CORE and DRIVER messages
- * - ...
* - drm.debug=0x1ff will enable all messages
*
* An interesting feature is that it's possible to enable verbose logging at
@@ -273,6 +293,63 @@ static inline struct drm_printer drm_err_printer(const char *prefix)
*
* # echo 0xf > /sys/module/drm/parameters/debug
*
+ *
+ * When a &drm_device * is available use one of the following logging functions.
+ * The same prototype is shared by all the logging functions
+ * that take a &drm_device * as first argument:
+ *
+ * .. code-block:: c
+ *
+ * void drm_xxx(struct drm_device *, char * fmt, ...)
+ *
+ * Drivers can use the following functions for logging.
+ *
+ * .. code-block:: none
+ *
+ * # Plain logging
+ * drm_dbg()
+ * drm_info()
+ * drm_notice()
+ * drm_warn()
+ * drm_err()
+ *
+ * # Log only once
+ * drm_info_once()
+ * drm_notice_once()
+ * drm_warn_once()
+ * drm_err_once()
+ *
+ * # Ratelimited - do not flood the logs
+ * drm_err_ratelimited()
+ *
+ * # Logging with a specific category
+ * drm_dbg_core()
+ * drm_dbg() # Uses the DRIVER category
+ * drm_dbg_kms()
+ * drm_dbg_prime()
+ * drm_dbg_atomic()
+ * drm_dbg_vbl()
+ * drm_dbg_state()
+ * drm_dbg_lease()
+ * drm_dbg_dp()
+ *
+ * See enum &drm_debug_category for a description of the categories.
+ *
+ * Logging when a &device * is available, but no &drm_device *
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * TODO
+ *
+ * Logging when no &device * nor &drm_device * is available
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * TODO
+ *
+ * Obsoleted logging functions
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * The DRM_*() logging functions are deprecated - do not use them in new code.
+ */
+
+/**
+ * enum drm_debug_category - The DRM debug categories
*/
enum drm_debug_category {
/**
--
2.20.1
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel
