drm/print: Add deprecation notes to DRM_...() functions
authorDouglas Anderson <dianders@chromium.org>
Tue, 21 Sep 2021 15:28:01 +0000 (08:28 -0700)
committerDouglas Anderson <dianders@chromium.org>
Fri, 24 Sep 2021 21:56:56 +0000 (14:56 -0700)
commit306589856399e18894d20e717c217ede0a866d22
tree8bc8cfb9653014be2875a8ea671ea6e51c2a2c08
parent7d1be0a09fa62139f1a29ccbe6d46aa04616539b
drm/print: Add deprecation notes to DRM_...() functions

It's hard for someone (like me) who's not following closely to know
what the suggested best practices are for error printing in DRM
drivers. Add some hints to the header file.

In general, my understanding is that:
* When possible we should be using a `struct drm_device` for logging
  and recent patches have tried to make it more possible to access a
  relevant `struct drm_device` in more places.
* For most cases when we don't have a `struct drm_device`, we no
  longer bother with DRM-specific wrappers on the dev_...() functions
  or pr_...() functions and just encourage drivers to use the normal
  functions.
* For debug-level functions where we might want filtering based on a
  category we'll still have DRM-specific wrappers, but we'll only
  support passing a `struct drm_device`, not a `struct
  device`. Presumably most of the cases where we want the filtering
  are messages that happen while the system is in a normal running
  state (AKA not during probe time) and we should have a `struct
  drm_device` then. If we absolutely can't get a `struct drm_device`
  then these functions begrudgingly accept NULL for the `struct
  drm_device` and hopefully the awkwardness of having to manually pass
  NULL will keep people from doing this unless absolutely necessary.

Signed-off-by: Douglas Anderson <dianders@chromium.org>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Acked-by: Lyude Paul <lyude@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210921082757.RFC.1.Ibd82d98145615fa55f604947dc6a696cc82e8e43@changeid
include/drm/drm_print.h