linux-toradex.git/include/drm/drm_print.h, branch v5.16-rc5

drm/print: Add deprecation notes to DRM_...() functions

2021-09-24T21:56:56+00:00

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 
Acked-by: Thomas Zimmermann 
Acked-by: Lyude Paul 
Link: https://patchwork.freedesktop.org/patch/msgid/20210921082757.RFC.1.Ibd82d98145615fa55f604947dc6a696cc82e8e43@changeid

drm/print: fixup spelling in a comment

2021-07-20T13:08:18+00:00

s/prink/printk/ - no functional changes

Signed-off-by: Jim Cromie 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20210714175138.319514-2-jim.cromie@gmail.com

drm/print: Handle potentially NULL drm_devices in drm_dbg_*

2021-04-27T22:43:44+00:00

While this shouldn't really be something that happens all that often, since
we're going to be using the drm_dbg_* log helpers in DRM helpers it's
technically possible that a driver could use an AUX adapter before it's
been associated with it's respective drm_device. While drivers should take
care to avoid this, there's likely going to be situations where it's
difficult to workaround. And since other logging helpers in the kernel tend
to be OK with NULL pointers (for instance, passing a NULL pointer to a "%s"
argument for a printk-like function in the kernel doesn't break anything),
we should do the same for ours.

Signed-off-by: Lyude Paul 
Link: https://patchwork.freedesktop.org/patch/msgid/20210423184309.207645-15-lyude@redhat.com
Reviewed-by: Dave Airlie

drm/print: Fixup DRM_DEBUG_KMS_RATELIMITED()

2021-04-08T21:46:02+00:00

Since we're about to move drm_dp_helper.c over to drm_dbg_*(), we'll want
to make sure that we can also add ratelimited versions of these macros in
order to retain some of the previous debugging output behavior we had.

However, as I was preparing to do this I noticed that the current
rate limited macros we have are kind of bogus. It looks like when I wrote
these, I didn't notice that we'd always be calling __ratelimit() even if
the debugging message we'd be printing would normally be filtered out due
to the relevant DRM debugging category being disabled.

So, let's fix this by making sure to check drm_debug_enabled() in our
ratelimited macros before calling __ratelimit(), and start using
drm_dev_printk() in order to print debugging messages since that will save
us from doing a redundant drm_debug_enabled() check. And while we're at it,
let's move the code for this into another macro that we can reuse for
defining new ratelimited DRM debug macros more easily.

v2:
* Make sure to use tabs where possible in __DRM_DEFINE_DBG_RATELIMITED()

Signed-off-by: Lyude Paul 
Cc: Robert Foss 
Reviewed-by: Robert Foss 
Link: https://patchwork.freedesktop.org/patch/msgid/20210326203807.105754-8-lyude@redhat.com

drm: drm_print.h: fix kernel-doc markups

2020-10-27T10:21:39+00:00

A kernel-doc markup should start with the identifier on its
first line.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/5b76c5625709aaaa3abee98faa620b9f3d27ff85.1603791716.git.mchehab+huawei@kernel.org

drm: add managed resources tied to drm_device

2020-03-26T13:49:13+00:00

We have lots of these. And the cleanup code tends to be of dubious
quality. The biggest wrong pattern is that developers use devm_, which
ties the release action to the underlying struct device, whereas
all the userspace visible stuff attached to a drm_device can long
outlive that one (e.g. after a hotunplug while userspace has open
files and mmap'ed buffers). Give people what they want, but with more
correctness.

Mostly copied from devres.c, with types adjusted to fit drm_device and
a few simplifications - I didn't (yet) copy over everything. Since
the types don't match code sharing looked like a hopeless endeavour.

For now it's only super simplified, no groups, you can't remove
actions (but kfree exists, we'll need that soon). Plus all specific to
drm_device ofc, including the logging. Which I didn't bother to make
compile-time optional, since none of the other drm logging is compile
time optional either.

One tricky bit here is the chicken&egg between allocating your
drm_device structure and initiliazing it with drm_dev_init. For
perfect onion unwinding we'd need to have the action to kfree the
allocation registered before drm_dev_init registers any of its own
release handlers. But drm_dev_init doesn't know where exactly the
drm_device is emebedded into the overall structure, and by the time it
returns it'll all be too late. And forcing drivers to be able clean up
everything except the one kzalloc is silly.

Work around this by having a very special final_kfree pointer. This
also avoids troubles with the list head possibly disappearing from
underneath us when we release all resources attached to the
drm_device.

v2: Do all the kerneldoc at the end, to avoid lots of fairly pointless
shuffling while getting everything into shape.

v3: Add static to add/del_dr (Neil)
Move typo fix to the right patch (Neil)

v4: Enforce contract for drmm_add_final_kfree:

Use ksize() to check that the drm_device is indeed contained somewhere
in the final kfree(). Because we need that or the entire managed
release logic blows up in a pile of use-after-frees. Motivated by a
discussion with Laurent.

v5: Review from Laurent:
- %zu instead of casting size_t
- header guards
- sorting of includes
- guarding of data assignment if we didn't allocate it for a NULL
  pointer
- delete spurious newline
- cast void* data parameter correctly in ->release call, no idea how
  this even worked before

v6: Review from Sam
- Add the kerneldoc for the managed sub-struct back in, even if it
  doesn't show up in the generated html somehow.
- Explain why __always_inline.
- Fix bisectability around the final kfree() in drm_dev_relase(). This
  is just interim code which will disappear again.
- Some whitespace polish.
- Add debug output when drmm_add_action or drmm_kmalloc fail.

v7: My bisectability fix wasn't up to par as noticed by smatch.

v8: Remove unecessary {} around if else

v9: Use kstrdup_const, which requires kfree_const and introducing a free_dr()
helper (Thomas).

v10: kfree_const goes boom on the plain "kmalloc" assignment, somehow
we need to wrap that in kstrdup_const() too!! Also renumber revision
log, I somehow reset it midway thruh.

Reviewed-by: Sam Ravnborg 
Cc: Thomas Zimmermann 
Cc: Dan Carpenter 
Cc: Sam Ravnborg 
Cc: Laurent Pinchart 
Cc: Neil Armstrong 
Cc: "Rafael J. Wysocki" 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20200324124540.3227396-1-daniel.vetter@ffwll.ch

drm/print: clean up RATELIMITED macros

2020-02-15T13:39:35+00:00

Drop a few indirections, making the code simpler.
This also drops a RATELIMITED variant that is not in use.

Signed-off-by: Sam Ravnborg 
Reviewed-by: Daniel Vetter 
Cc: Jani Nikula 
Link: https://patchwork.freedesktop.org/patch/msgid/20200214175919.GA14492@ravnborg.org

drm/print: Delete a few unused shouting macros

2020-02-14T16:26:02+00:00

We want to go over to the new lowercase ones, encourage that a bit
more.

v2: Remove the accidentally included hunk from some WIP branch this
was based on (Jani&Sam).

Cc: Jani Nikula 
Acked-by: Jani Nikula 
Reviewed-by: Sam Ravnborg 
Signed-off-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20200214090428.2929833-1-daniel.vetter@ffwll.ch

drm/print: introduce new struct drm_device based WARN* macros

2020-01-22T14:17:32+00:00

Add new struct drm_device based WARN* macros. These are modeled after
the core kernel device based WARN* macros. These would be preferred
over the regular WARN* macros, where possible.

These macros include device information in the backtrace, so we know
what device the warnings originate from.

Knowing the device specific information in the backtrace would be
helpful in development all around.

Signed-off-by: Pankaj Bharadiya 
Reviewed-by: Jani Nikula 
Reviewed-by: Sam Ravnborg 
Acked-by: Maxime Ripard 
Acked-by: Maarten Lankhorst 
Acked-by: Sean Paul 
Signed-off-by: Jani Nikula 
Link: https://patchwork.freedesktop.org/patch/msgid/20200115034455.17658-2-pankaj.laxminarayan.bharadiya@intel.com

drm/print: introduce new struct drm_device based logging macros

2019-12-17T14:43:20+00:00

Add new struct drm_device based logging macros modeled after the core
kernel device based logging macros. These would be preferred over the
drm printk and struct device based macros in drm code, where possible.

We have existing drm specific struct device based logging functions, but
they are too verbose to use for two main reasons:

 * The names are unnecessarily long, for example DRM_DEV_DEBUG_KMS().

 * The use of struct device over struct drm_device is too generic for
   most users, leading to an extra dereference.

For example:

	DRM_DEV_DEBUG_KMS(drm->dev, "Hello, world\n");

vs.

	drm_dbg_kms(drm, "Hello, world\n");

It's a matter of taste, but the SHOUTING UPPERCASE has been argued to be
less readable than lowercase.

Some names are changed from old DRM names to be based on the core kernel
logging functions. For example, NOTE -> notice, ERROR -> err, DEBUG ->
dbg.

Due to the conflation of DRM_DEBUG and DRM_DEBUG_DRIVER macro use
(DRM_DEBUG is used widely in drivers though it's supposed to be a core
debugging category), they are named as drm_dbg_core and drm_dbg,
respectively.

The drm_err and _once/_ratelimited variants no longer include the
function name in order to be able to use the core device based logging
macros. Arguably this is not a significant change; error messages should
not be so common to be only distinguishable by the function name.

Ratelimited debug logging macros are to be added later.

Cc: Sam Ravnborg 
Acked-by: Ville Syrjälä 
Reviewed-by: Rodrigo Vivi 
Acked-by: Sean Paul 
Acked-by: Sam Ravnborg 
Signed-off-by: Jani Nikula 
Link: https://patchwork.freedesktop.org/patch/msgid/20191210123050.8799-1-jani.nikula@intel.com