On Sat, 21 Dec 2019, Sam Ravnborg sam@ravnborg.org wrote:
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@ravnborg.org Cc: Jani Nikula jani.nikula@intel.com Cc: Sean Paul sean@poorly.run Cc: Daniel Vetter daniel@ffwll.ch
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
Maybe document this stuff in enum drm_debug_category where they're defined instead?
BR, Jani.
- 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 { /**