On Thu, Jan 02, 2020 at 11:15:18PM +0100, Sam Ravnborg wrote:
> This is the documentation I have missed when I looked for help
> how to do proper logging. Hopefully it can help others.
>
> v2:
> - Add parameters to the logging functions in the doc
> - Drop notes on other types of logging
>
> 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 | 80 ++++++++++++++++++++++++++---
> 2 files changed, 79 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..89e75eea65d2 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,52 @@ 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, ...)
> + *
> + * DRM/Drivers can use the following functions for logging.
> + *
> + * .. code-block:: none
> + *
> + * # Plain logging
> + * drm_dbg(drm, fmt, ...)
> + * drm_info(drm, fmt, ...)
> + * drm_notice(drm, fmt, ...)
> + * drm_warn(drm, fmt, ...)
> + * drm_err(drm, fmt, ...)
> + *
> + * # Log only once
> + * drm_info_once(drm, fmt, ...)
> + * drm_notice_once(drm, fmt, ...)
> + * drm_warn_once(drm, fmt, ...)
> + * drm_err_once(drm, fmt, ...)
> + *
> + * # Ratelimited - do not flood the logs
> + * drm_err_ratelimited(drm, fmt, ...)
> + *
> + * # Logging with a specific category
> + * drm_dbg_core(drm, fmt, ...)
> + * drm_dbg(drm, fmt, ...) # Uses the DRIVER category
> + * drm_dbg_kms(drm, fmt, ...)
> + * drm_dbg_prime(drm, fmt, ...)
> + * drm_dbg_atomic(drm, fmt, ...)
> + * drm_dbg_vbl(drm, fmt, ...)
> + * drm_dbg_state(drm, fmt, ...)
> + * drm_dbg_lease(drm, fmt, ...)
> + * drm_dbg_dp(drm, fmt, ...)
> + *
> + * See enum &drm_debug_category for a description of the categories.
> + *
> + */
I kinda can't decide between this and just copypasting fairly repetitive
kerneldoc over all the new functions. I think given the long-term idea is
to favour the above functions over all the screaming macros (because of
multi-gpu stuff), I'd go with full kerneldocs for these, plus comments or
a note in the overview doc that everything else is kinda deprecated.
Jani, thoughts?
-Daniel
> +
> +/**
> + * enum drm_debug_category - The DRM debug categories
> */
> enum drm_debug_category {
> /**
> --
> 2.20.1
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/dri-devel
