| Message ID | 20200102221519.31037-2-sam@ravnborg.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm: document logging functions | expand |
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@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 | 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 >
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. + * + */ + +/** + * enum drm_debug_category - The DRM debug categories */ enum drm_debug_category { /**
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@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 | 80 ++++++++++++++++++++++++++--- 2 files changed, 79 insertions(+), 7 deletions(-)