On Sat, 21 Dec 2019, Sam Ravnborg <sam@xxxxxxxxxxxx> 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@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
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 {
> /**
--
Jani Nikula, Intel Open Source Graphics Center
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel
