Skip to contentSkip to conversation

drm: document logging functions

PATCH In review Sam Ravnborg 3 participants 10 messages Jan 2, 2020 – Jan 12, 2020

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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

#1 lore raw

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

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
index a73320576ca9..c2093611999c 100644
@@ -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
#2 lore raw

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 logging

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
index a73320576ca9..c2093611999c 100644
@@ -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
index 8f99d389792d..89e75eea65d2 100644
@@ -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
#3 lore raw

PATCH v2 2/2 drm/print: document DRM_ logging functions

In reply to 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.

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 +80 -4
index 89e75eea65d2..abe247199bf7 100644
@@ -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
#4 lore raw

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.

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
index 89e75eea65d2..abe247199bf7 100644

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
#5 lore raw

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.rst entry.

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
+ *
+ * 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, ...)

*/

/**

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.1
Signature · 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

#6 lore raw

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.rst entry.

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...

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
+ *
+ * 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, ...)

*/

/**

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.1
Signature · 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
#7 lore raw

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.rst entry.

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...

Quoted 8 lines

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?

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

#8 lore raw

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.rst entry.

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...

Quoted 8 lines

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?

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 use drm_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_ATOMIC

It 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

#9 lore raw

Re: [PATCH v2 2/2] drm/print: document DRM_ logging functions

In reply to Sam Ravnborg
Quoted 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.rst entry.

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...

Quoted 8 lines

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?

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 use drm_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