| Message ID | 20191221095553.13332-2-sam@ravnborg.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm: add more new-style logging functions | expand |
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 { > /**
Hi Jani. > > + * > > + * 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? For the logging user it is much more convinient to have the logging filtering explained in one place. The enum already tell part of the story but then the reader needs to hunt for the information. Sam
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 { /**
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(-)