drm: document logging functions
Subsystems (3)
v2 cover drm: document logging functions
Add kernel-doc for the drm_ and DRM_ logging functions.
This is the documentation that I missed when I started to use the logging functions.
Version 1 of this patchset included drm_ variants of the existing logging functions - but they are left out for now.
The idea is that we should try to use drm_ logging in favour of the the variants that take a device *.
This patchset document the existing logging functions with no functional changes.
And the documentation is properly wired up in drm-internals.rst
Sam
Sam Ravnborg (2):
drm/print: document drm_ logging functions
drm/print: document DRM_ logging functions
Documentation/gpu/drm-internals.rst | 6 ++ include/drm/drm_print.h | 164 +++++++++++++++++++++++++++++++++--- 2 files changed, 159 insertions(+), 11 deletions(-)
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v2 1/2 drm/print: document drm_ logging functions
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
--- Documentation/gpu/drm-internals.rst | 6 +++ include/drm/drm_print.h | 80 ++++++++++++++++++++++++++--- 2 files changed, 79 insertions(+), 7 deletions(-)
Documentation/gpu/drm-internals.rst +6 -0
@@ -164,6 +164,12 @@ File Operations Misc Utilities ============== +Logging +------- + +.. kernel-doc:: include/drm/drm_print.h + :doc: logging + Printer -------
include/drm/drm_print.h +73 -7
101 lines not on this page · raw message
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 1/2] drm/print: document drm_ logging functions
Quoted 124 lines · Sam Ravnborg
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 loggingSigned-off-by Sam Ravnborg <[email protected]>Cc Jani Nikula <[email protected]>Cc Sean Paul <[email protected]>Cc Daniel Vetter <[email protected]>--- Documentation/gpu/drm-internals.rst | 6 +++ include/drm/drm_print.h | 80 ++++++++++++++++++++++++++--- 2 files changed, 79 insertions(+), 7 deletions(-)Documentation/gpu/drm-internals.rst +6
-0@@ -164,6 +164,12 @@ File Operations Misc Utilities ============== +Logging +------- + +.. kernel-doc:: include/drm/drm_print.h + :doc: logging + Printer -------include/drm/drm_print.h +60
-7@@ -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, ...)
include/drm/drm_print.h static inline struct drm_printer drm_err_printer(const char *prefix) · line 338
Quoted 10 lines
include/drm/drm_print.h +10
-0+* 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
Quoted 9 lines
include/drm/drm_print.h +3
-0+ +/** +* enum drm_debug_category - The DRM debug categories */ enum drm_debug_category {/** Signature · 1 line
2.20.1
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v2 2/2 drm/print: document DRM_ logging functions
In reply to Sam RavnborgDocument the remaining DRM_ logging functions. As the logging functions are now all properly listed drop the few specific kernel-doc markers so we keep the relevant parts in the documentation.
--- include/drm/drm_print.h | 84 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 4 deletions(-)
include/drm/drm_print.h +80 -4
@@ -335,6 +335,82 @@ static inline struct drm_printer drm_err_printer(const char *prefix)* * See enum &drm_debug_category for a description of the categories. * +* Logging when a &device * is available, but no &drm_device * +* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* +* DRM/Drivers can use the following functions for logging when there is a +* struct device * available. +* The logging functions share the same prototype: +* +* .. code-block:: c +* +* void DRM_xxx(struct device *, char * fmt, ...) +* +* .. code-block:: none +* +* # Plain logging +* DRM_DEV_INFO(dev, fmt, ...) +* DRM_DEV_ERROR(dev, fmt, ...) +* +* # Log only once +* DRM_DEV_INFO_ONCE(dev, fmt, ...) +* +* # Ratelimited - do not flood the logs +* DRM_DEV_DEBUG_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_DRIVER_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_KMS_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_PRIME_RATELIMITED(dev, fmt, ...) +* DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) +* +* # Logging with a specific category +* DRM_DEV_DEBUG(dev, fmt, ...) # Logged as CORE +* DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) +* DRM_DEV_DEBUG_KMS(dev, fmt, ...) +* DRM_DEV_DEBUG_PRIME(dev, fmt, ...) +* DRM_DEV_DEBUG_ATOMIC(dev, fmt, ...) +* DRM_DEV_DEBUG_VBL(dev, fmt, ...) +* DRM_DEV_DEBUG_DP(dev, fmt, ...) +* +* Logging when no &device * nor &drm_device * is available +* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* +* DRM/Drivers can use the following functions for logging when there is no +* extra info associated to the logging. +* The logging functions share the same prototype: +* +* .. code-block:: c +* +* void DRM_xxx(char * fmt, ...) +* +* .. code-block:: none +* +* # Plain logging +* DRM_INFO(fmt, ...) +* DRM_NOTE(fmt, ...) +* DRM_WARN(fmt, ...) +* DRM_ERROR(fmt, ...) +* +* # Log only once +* DRM_INFO_ONCE(fmt, ...) +* DRM_NOTE_ONCE(fmt, ...) +* DRM_WARN_ONCE(fmt, ...) +* +* # Ratelimited - do not flood the logs +* DRM_DEBUG_RATELIMITED(fmt, ...) +* DRM_DEBUG_DRIVER_RATELIMITED(fmt, ...) +* DRM_DEBUG_KMS_RATELIMITED(fmt, ...) +* DRM_DEBUG_PRIME_RATELIMITED(fmt, ...) +* DRM_ERROR_RATELIMITED(fmt, ...) +* +* # Logging with a specific category +* DRM_DEBUG(fmt, ...) # Logged as CORE +* DRM_DEBUG_DRIVER(fmt, ...) +* DRM_DEBUG_KMS(fmt, ...) +* DRM_DEBUG_PRIME(fmt, ...) +* DRM_DEBUG_ATOMIC(fmt, ...) +* DRM_DEBUG_VBL(fmt, ...) +* DRM_DEBUG_LEASE(fmt, ...) +* DRM_DEBUG_DP(fmt, ...) */ /**
@@ -399,7 +475,7 @@ __printf(3, 4)void drm_dev_dbg (const struct device *dev,enum drm_debug_category category,const char *format, ...); -/** +/* * Error output. * * @dev: device pointer
@@ -408,7 +484,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,#define DRM_DEV_ERROR (dev, fmt, ...) \ drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__) -/** +/* * Rate limited error output. Like DRM_ERROR() but won't flood the log. * * @dev: device pointer
@@ -436,7 +512,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, } \ }) -/** +/* * Debug output. * * @dev: device pointer
@@ -466,7 +542,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, drm_dev_dbg(dev, category, fmt, ##__VA_ARGS__); \ }) -/** +/* * Rate limited debug output. Like DRM_DEBUG() but won't flood the log. * * @dev: device pointer
Signature · 6 lines
2.20.1 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
Quoted 18 lines · Sam Ravnborg
Document the remaining
DRM_logging functions. As the logging functions are now all properly listed drop the few specific kernel-doc markers so we keep the relevant parts in the documentation.Signed-off-by Sam Ravnborg <[email protected]>Cc Jani Nikula <[email protected]>Cc Sean Paul <[email protected]>Cc Daniel Vetter <[email protected]>--- include/drm/drm_print.h | 84 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 4 deletions(-)include/drm/drm_print.h +0
-0
include/drm/drm_print.h static inline struct drm_printer drm_err_printer(const char *prefix) · line 343
Quoted 9 lines
include/drm/drm_print.h +6
-0@@ -335,6 +335,82 @@ static inline struct drm_printer drm_err_printer(const char *prefix)* * See enum &drm_debug_category for a description of the categories. * +* Logging when a &device * is available, but no &drm_device * +* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* +* DRM/Drivers can use the following functions for logging when there is a +* struct device * available. +* The logging functions share the same prototype:
I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding todo.rst entry.
-Daniel
Quoted 112 lines
include/drm/drm_print.h +74
-4+* +* .. code-block:: c +* +* void DRM_xxx(struct device *, char * fmt, ...) +* +* .. code-block:: none +* +* # Plain logging +* DRM_DEV_INFO(dev, fmt, ...) +* DRM_DEV_ERROR(dev, fmt, ...) +* +* # Log only once +* DRM_DEV_INFO_ONCE(dev, fmt, ...) +* +* # Ratelimited - do not flood the logs +* DRM_DEV_DEBUG_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_DRIVER_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_KMS_RATELIMITED(dev, fmt, ...) +* DRM_DEV_DEBUG_PRIME_RATELIMITED(dev, fmt, ...) +* DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) +* +* # Logging with a specific category +* DRM_DEV_DEBUG(dev, fmt, ...) # Logged as CORE +* DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) +* DRM_DEV_DEBUG_KMS(dev, fmt, ...) +* DRM_DEV_DEBUG_PRIME(dev, fmt, ...) +* DRM_DEV_DEBUG_ATOMIC(dev, fmt, ...) +* DRM_DEV_DEBUG_VBL(dev, fmt, ...) +* DRM_DEV_DEBUG_DP(dev, fmt, ...) +* +* Logging when no &device * nor &drm_device * is available +* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* +* DRM/Drivers can use the following functions for logging when there is no +* extra info associated to the logging. +* The logging functions share the same prototype: +* +* .. code-block:: c +* +* void DRM_xxx(char * fmt, ...) +* +* .. code-block:: none +* +* # Plain logging +* DRM_INFO(fmt, ...) +* DRM_NOTE(fmt, ...) +* DRM_WARN(fmt, ...) +* DRM_ERROR(fmt, ...) +* +* # Log only once +* DRM_INFO_ONCE(fmt, ...) +* DRM_NOTE_ONCE(fmt, ...) +* DRM_WARN_ONCE(fmt, ...) +* +* # Ratelimited - do not flood the logs +* DRM_DEBUG_RATELIMITED(fmt, ...) +* DRM_DEBUG_DRIVER_RATELIMITED(fmt, ...) +* DRM_DEBUG_KMS_RATELIMITED(fmt, ...) +* DRM_DEBUG_PRIME_RATELIMITED(fmt, ...) +* DRM_ERROR_RATELIMITED(fmt, ...) +* +* # Logging with a specific category +* DRM_DEBUG(fmt, ...) # Logged as CORE +* DRM_DEBUG_DRIVER(fmt, ...) +* DRM_DEBUG_KMS(fmt, ...) +* DRM_DEBUG_PRIME(fmt, ...) +* DRM_DEBUG_ATOMIC(fmt, ...) +* DRM_DEBUG_VBL(fmt, ...) +* DRM_DEBUG_LEASE(fmt, ...) +* DRM_DEBUG_DP(fmt, ...) */ /** @@ -399,7 +475,7 @@ __printf(3, 4)void drm_dev_dbg (const struct device *dev,enum drm_debug_category category,const char *format, ...); -/** +/* * Error output. * * @dev: device pointer @@ -408,7 +484,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,#define DRM_DEV_ERROR (dev, fmt, ...) \ drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__) -/** +/* * Rate limited error output. Like DRM_ERROR() but won't flood the log. * * @dev: device pointer @@ -436,7 +512,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, } \ }) -/** +/* * Debug output. * * @dev: device pointer @@ -466,7 +542,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, drm_dev_dbg(dev, category, fmt, ##__VA_ARGS__); \ }) -/** +/* * Rate limited debug output. Like DRM_DEBUG() but won't flood the log. * * @dev: device pointer Signature · 1 line
2.20.1
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
Hi Daniel.
Quoted 9 lines
Quoted 6 lines
+ * Logging when a &device * is available, but no
&drm_device*
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * DRM/Drivers can use the following functions for logging when there is a
+ * struct device * available.
+ * The logging functions share the same prototype:I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding
todo.rstentry.
We have many situations where no drm_device is available. At least when you a buried in drm_panel patches.
So it is either DRM_DEV_ERROR() or drv_err().
Which is why I have pushed for nicer drm_ variants of these...
The todo entry only covers the nice new macros that Jani added where we have a drm_device.
Sam
Quoted 106 lines
-Daniel
Quoted 104 lines
+ *
+ * .. code-block:: c
+ *
+ * voidDRM_xxx(struct device *, char * fmt, ...)
+ *
+ * .. code-block:: none
+ *+ * # Plain logging + * DRM_DEV_INFO(dev, fmt, ...) + * DRM_DEV_ERROR(dev, fmt, ...)+ *
+ * # Log only once
+ *DRM_DEV_INFO_ONCE(dev, fmt, ...)
+ *+ * # Ratelimited - do not flood the logs + * DRM_DEV_DEBUG_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_DRIVER_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_KMS_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_PRIME_RATELIMITED(dev, fmt, ...) + * DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) + * + * # Logging with a specific category + * DRM_DEV_DEBUG(dev, fmt, ...) # Logged as CORE + * DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) + * DRM_DEV_DEBUG_KMS(dev, fmt, ...) + * DRM_DEV_DEBUG_PRIME(dev, fmt, ...) + * DRM_DEV_DEBUG_ATOMIC(dev, fmt, ...) + * DRM_DEV_DEBUG_VBL(dev, fmt, ...) + * DRM_DEV_DEBUG_DP(dev, fmt, ...)+ *
+ * Logging when no &device * nor&drm_device* is available
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * DRM/Drivers can use the following functions for logging when there is no
+ * extra info associated to the logging.
+ * The logging functions share the same prototype:
+ *
+ * .. code-block:: c
+ *
+ * voidDRM_xxx(char * fmt, ...)
+ *
+ * .. code-block:: none
+ *+ * # Plain logging + * DRM_INFO(fmt, ...) + * DRM_NOTE(fmt, ...) + * DRM_WARN(fmt, ...) + * DRM_ERROR(fmt, ...) + * + * # Log only once + * DRM_INFO_ONCE(fmt, ...) + * DRM_NOTE_ONCE(fmt, ...) + * DRM_WARN_ONCE(fmt, ...) + * + * # Ratelimited - do not flood the logs + * DRM_DEBUG_RATELIMITED(fmt, ...) + * DRM_DEBUG_DRIVER_RATELIMITED(fmt, ...) + * DRM_DEBUG_KMS_RATELIMITED(fmt, ...) + * DRM_DEBUG_PRIME_RATELIMITED(fmt, ...) + * DRM_ERROR_RATELIMITED(fmt, ...) + * + * # Logging with a specific category + * DRM_DEBUG(fmt, ...) # Logged as CORE + * DRM_DEBUG_DRIVER(fmt, ...) + * DRM_DEBUG_KMS(fmt, ...) + * DRM_DEBUG_PRIME(fmt, ...) + * DRM_DEBUG_ATOMIC(fmt, ...) + * DRM_DEBUG_VBL(fmt, ...) + * DRM_DEBUG_LEASE(fmt, ...) + * DRM_DEBUG_DP(fmt, ...)*/
/**
include/drm/drm_print.h +3
-3@@ -399,7 +475,7 @@ __printf(3, 4)void drm_dev_dbg (const struct device *dev,enum drm_debug_category category,const char *format, ...); -/** +/* * Error output. * * @dev: device pointer @@ -408,7 +484,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,#define DRM_DEV_ERROR (dev, fmt, ...) \ drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__) -/** +/* * Rate limited error output. Like DRM_ERROR() but won't flood the log. * * @dev: device pointer @@ -436,7 +512,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, } \ }) -/** +/* * Debug output. * * @dev: device pointer @@ -466,7 +542,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, drm_dev_dbg(dev, category, fmt, ##__VA_ARGS__); \ })
Quoted 13 lines
Quoted 8 lines
include/drm/drm_print.h +1
-1-/** +/* * Rate limited debug output. Like DRM_DEBUG() but won't flood the log. * * @dev: device pointer Signature · 1 line
2.20.1Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
Quoted 9 lines · Sam Ravnborg
Hi Daniel.
Quoted 7 lines
Quoted 6 lines
+ * Logging when a &device * is available, but no
&drm_device*
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * DRM/Drivers can use the following functions for logging when there is a
+ * struct device * available.
+ * The logging functions share the same prototype:
Quoted 8 lines
Quoted 2 lines
I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding
todo.rstentry.We have many situations where no
drm_deviceis available. At least when you a buried indrm_panelpatches.So it is either
DRM_DEV_ERROR()ordrv_err().
Which is why I have pushed for nicerdrm_variants of these...
Huh, drm_panel indeed has no drm_device. And I guess we don't have a convenient excuse to add it ...
Quoted 2 lines
The todo entry only covers the nice new macros that Jani added where we have a
drm_device.
I wonder whether for those cases we shouldn't just directly use the various dev_* macros?
-Daniel
Quoted 124 lines
Sam
Quoted 119 lines
-Daniel
Quoted 112 lines
+ *
+ * .. code-block:: c
+ *
+ * voidDRM_xxx(struct device *, char * fmt, ...)
+ *
+ * .. code-block:: none
+ *+ * # Plain logging + * DRM_DEV_INFO(dev, fmt, ...) + * DRM_DEV_ERROR(dev, fmt, ...)+ *
+ * # Log only once
+ *DRM_DEV_INFO_ONCE(dev, fmt, ...)
+ *+ * # Ratelimited - do not flood the logs + * DRM_DEV_DEBUG_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_DRIVER_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_KMS_RATELIMITED(dev, fmt, ...) + * DRM_DEV_DEBUG_PRIME_RATELIMITED(dev, fmt, ...) + * DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...) + * + * # Logging with a specific category + * DRM_DEV_DEBUG(dev, fmt, ...) # Logged as CORE + * DRM_DEV_DEBUG_DRIVER(dev, fmt, ...) + * DRM_DEV_DEBUG_KMS(dev, fmt, ...) + * DRM_DEV_DEBUG_PRIME(dev, fmt, ...) + * DRM_DEV_DEBUG_ATOMIC(dev, fmt, ...) + * DRM_DEV_DEBUG_VBL(dev, fmt, ...) + * DRM_DEV_DEBUG_DP(dev, fmt, ...)+ *
+ * Logging when no &device * nor&drm_device* is available
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * DRM/Drivers can use the following functions for logging when there is no
+ * extra info associated to the logging.
+ * The logging functions share the same prototype:
+ *
+ * .. code-block:: c
+ *
+ * voidDRM_xxx(char * fmt, ...)
+ *
+ * .. code-block:: none
+ *+ * # Plain logging + * DRM_INFO(fmt, ...) + * DRM_NOTE(fmt, ...) + * DRM_WARN(fmt, ...) + * DRM_ERROR(fmt, ...) + * + * # Log only once + * DRM_INFO_ONCE(fmt, ...) + * DRM_NOTE_ONCE(fmt, ...) + * DRM_WARN_ONCE(fmt, ...) + * + * # Ratelimited - do not flood the logs + * DRM_DEBUG_RATELIMITED(fmt, ...) + * DRM_DEBUG_DRIVER_RATELIMITED(fmt, ...) + * DRM_DEBUG_KMS_RATELIMITED(fmt, ...) + * DRM_DEBUG_PRIME_RATELIMITED(fmt, ...) + * DRM_ERROR_RATELIMITED(fmt, ...) + * + * # Logging with a specific category + * DRM_DEBUG(fmt, ...) # Logged as CORE + * DRM_DEBUG_DRIVER(fmt, ...) + * DRM_DEBUG_KMS(fmt, ...) + * DRM_DEBUG_PRIME(fmt, ...) + * DRM_DEBUG_ATOMIC(fmt, ...) + * DRM_DEBUG_VBL(fmt, ...) + * DRM_DEBUG_LEASE(fmt, ...) + * DRM_DEBUG_DP(fmt, ...)*/
/**
include/drm/drm_print.h +4
-4@@ -399,7 +475,7 @@ __printf(3, 4)void drm_dev_dbg (const struct device *dev,enum drm_debug_category category,const char *format, ...); -/** +/* * Error output. * * @dev: device pointer @@ -408,7 +484,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,#define DRM_DEV_ERROR (dev, fmt, ...) \ drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__) -/** +/* * Rate limited error output. Like DRM_ERROR() but won't flood the log. * * @dev: device pointer @@ -436,7 +512,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, } \ }) -/** +/* * Debug output. * * @dev: device pointer @@ -466,7 +542,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category, drm_dev_dbg(dev, category, fmt, ##__VA_ARGS__); \ }) -/** +/* * Rate limited debug output. Like DRM_DEBUG() but won't flood the log. * * @dev: device pointer Signature · 1 line
2.20.1Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
Hi Daniel.
Quoted 10 lines
Quoted 9 lines
Quoted 3 lines
I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding
todo.rstentry.We have many situations where no
drm_deviceis available. At least when you a buried indrm_panelpatches.So it is either
DRM_DEV_ERROR()ordrv_err().
Which is why I have pushed for nicerdrm_variants of these...
Quoted 8 lines
Huh,
drm_panelindeed has nodrm_device. And I guess we don't have a convenient excuse to add it ...Quoted 2 lines
The todo entry only covers the nice new macros that Jani added where we have a
drm_device.I wonder whether for those cases we shouldn't just directly use the various dev_* macros?
We would miss the nice [drm] marker in the logging.
So [drm] will be added by the drivers and the core - but not the panels. That is the only drawback I see right now.
Which was enough justification for me to add the drm_dev_ variants. Feel free to convince me that this is not justification to add these variants.
In drm/panel/* there is no use of DRM_DEBUG* - and there is no reason to introduce the variants we can filer with drm.debug.
There is a single DRM_DEBUG() user, which does not count here.
We could introduce only:
drm_dev_(err|warn|info|debug) - and not the more specialized variants.
Then we avoid that people make shortcuts and use drm_dev_dbg_kms() when they are supposed to use drm_dbg_kms().
This was one of the very valid argumest against the patch that introduced all the drm_dev_* variants.
Sam
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
Quoted 33 lines · Sam Ravnborg
Hi Daniel.
Quoted 9 lines
Quoted 8 lines
Quoted 2 lines
I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding
todo.rstentry.We have many situations where no
drm_deviceis available. At least when you a buried indrm_panelpatches.So it is either
DRM_DEV_ERROR()ordrv_err().
Which is why I have pushed for nicerdrm_variants of these...Quoted 8 lines
Huh,
drm_panelindeed has nodrm_device. And I guess we don't have a convenient excuse to add it ...Quoted 2 lines
The todo entry only covers the nice new macros that Jani added where we have a
drm_device.I wonder whether for those cases we shouldn't just directly use the various dev_* macros?
We would miss the nice [drm] marker in the logging.
So [drm] will be added by the drivers and the core - but not the panels. That is the only drawback I see right now.Which was enough justification for me to add the
drm_dev_variants. Feel free to convince me that this is not justification to add these variants.In drm/panel/* there is no use of DRM_DEBUG* - and there is no reason to introduce the variants we can filer with drm.debug.
There is a single
DRM_DEBUG()user, which does not count here.
Quoted 8 lines
We could introduce only:
drm_dev_(err|warn|info|debug)- and not the more specialized variants.Then we avoid that people make shortcuts and use
drm_dev_dbg_kms()when they are supposed to usedrm_dbg_kms().
This was one of the very valid argumest against the patch that introduced all the drm_dev_* variants.
A few of these defines aren't used at all.
$ git grep -P -oh "DRM_DEV_DEBUG[A-Z_]*" | sort | uniq -c | sort -rn
98 DRM_DEV_DEBUG_KMS
38 DRM_DEV_DEBUG_DRIVER
26 DRM_DEV_DEBUG
2 DRM_DEV_DEBUG_RATELIMITED
2 DRM_DEV_DEBUG_PRIME_RATELIMITED
2 DRM_DEV_DEBUG_KMS_RATELIMITED
2 DRM_DEV_DEBUG_DRIVER_RATELIMITED
1 DRM_DEV_DEBUG_VBL
1 DRM_DEV_DEBUG_PRIME
1 DRM_DEV_DEBUG_DP
1 DRM_DEV_DEBUG_ATOMICIt might be sensible to consolidate these into just 2 calls and add an appropriate <type> argument.
DRM_DEV_DEBUG(dev, type, fmt, ...) DRM_DEV_DEBUG_RATELIMITED(dev, type, fmt, ...)
or
drm_dev_dbg(dev, type, fmt, ...) drm_dev_dbg_ratelimited(dev, type, fmt, ...)
A treewide sed is trivial.
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions
In reply to Sam RavnborgQuoted 20 lines · Sam Ravnborg
Hi Daniel.
Quoted 10 lines
Quoted 9 lines
Quoted 3 lines
I'd replace the entire block with a "This stuff is deprecated" warning. We have at least a corresponding
todo.rstentry.We have many situations where no
drm_deviceis available. At least when you a buried indrm_panelpatches.So it is either
DRM_DEV_ERROR()ordrv_err().
Which is why I have pushed for nicerdrm_variants of these...Quoted 8 lines
Huh,
drm_panelindeed has nodrm_device. And I guess we don't have a convenient excuse to add it ...Quoted 2 lines
The todo entry only covers the nice new macros that Jani added where we have a
drm_device.I wonder whether for those cases we shouldn't just directly use the various dev_* macros?
Quoted 7 lines
We would miss the nice [drm] marker in the logging.
So [drm] will be added by the drivers and the core - but not the panels. That is the only drawback I see right now.Which was enough justification for me to add the
drm_dev_variants. Feel free to convince me that this is not justification to add these variants.
tbh I don't mind, I just don't want to have a massive proliferation of drm debugging functions, all kinda alike but not the same. If we can settle on some color choice for this bikeshed and actually reduce the not-longer favoured version, I'm pretty much ok with anything.
Quoted 6 lines
In drm/panel/* there is no use of DRM_DEBUG* - and there is no reason to introduce the variants we can filer with drm.debug.
There is a single
DRM_DEBUG()user, which does not count here.
Quoted 8 lines
We could introduce only:
drm_dev_(err|warn|info|debug)- and not the more specialized variants.Then we avoid that people make shortcuts and use
drm_dev_dbg_kms()when they are supposed to usedrm_dbg_kms().
This was one of the very valid argumest against the patch that introduced all the drm_dev_* variants.
Hm, if you want something for panels, what about a drm_panel_* set of functions? Plus ofc patches to just roll them out everywhere (it should be a simple sed/cocci job, drm/panel/* isn't that big). Some churn, but yay! for consisteny at least.
If we have another set of generic drm debug/logging functions then I think consistency is going to take a big toll, and we're already bad with this. -Daniel
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel