Re: [PATCH v1 1/8] drm/print: document logging functions

2019-12-23 Thread Sam Ravnborg 
Hi Jani.

> > + *
> > + * Each of the debug logging macros use a specific category, and the 
> > logging
> > + * is filtered by the drm.debug module parameter. The _debug_category 
> > enum
> > + * specifies the values for the interface.
> > + *
> > + * Each drm_dbg_ macro logs to a DRM_UT_ 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
___
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v1 1/8] drm/print: document logging functions

2019-12-23 Thread Jani Nikula 
On Sat, 21 Dec 2019, 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.
>
> Signed-off-by: Sam Ravnborg 
> Cc: Jani Nikula 
> Cc: Sean Paul 
> Cc: Daniel Vetter 
> ---
>  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_ macro logs to DRM_UT_ 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 _debug_category 
> enum
> + * specifies the values for the interface.
> + *
> + * Each drm_dbg_ macro logs to a DRM_UT_ 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 _device * is available use one of the following logging 
> functions.
> + * The same prototype is shared by all the logging functions
> + * that take a _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 _debug_category for a description of the categories.
> + *
> + * Logging when a  * is available, but no _device *
> + * 
> ~
> + * TODO
> + *
> + * Logging when no  * nor _device * is available
> + * 
> 
> + * TODO
> + *
> + * Obsoleted logging functions
> + * ~~~
> + * The DRM_*() logging functions are deprecated - do not use them in new 
> code.
> + */
> +
> +/**

[PATCH v1 1/8] drm/print: document logging functions

2019-12-21 Thread Sam Ravnborg 
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 
Cc: Jani Nikula 
Cc: Sean Paul 
Cc: Daniel Vetter 
---
 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_ macro logs to DRM_UT_ 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 _debug_category enum
+ * specifies the values for the interface.
+ *
+ * Each drm_dbg_ macro logs to a DRM_UT_ 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 _device * is available use one of the following logging 
functions.
+ * The same prototype is shared by all the logging functions
+ * that take a _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 _debug_category for a description of the categories.
+ *
+ * Logging when a  * is available, but no _device *
+ * 
~
+ * TODO
+ *
+ * Logging when no  * nor _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 {
/**
-- 
2.20.1

___
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel