All collected together to provide a consistent story in one patch,
instead of the somewhat bumpy refactor-evolution leading to this.
Also some thoughts on what the next steps could be:
- Create a macro called devm_drm_dev_alloc() which essentially wraps
the kzalloc(); devm_drm_dev_init(); drmm_add_final_kfree() combo.
Needs to be a macro since we'll have to do some typeof trickery and
casting to make this fully generic for all drivers that embed struct
drm_device into their own thing.
- A lot of the simple drivers now have essentially just
drm_dev_unplug(); drm_atomic_helper_shutdown(); as their
$bus_driver->remove hook. We could create a devm_mode_config_reset
which sets drm_atomic_helper_shutdown as it's cleanup action, and a
devm_drm_dev_register with drm_dev_unplug as it's cleanup action,
and simple drivers wouldn't have a need for a ->remove function at
all, and we could delete them.
- For more complicated drivers we need drmm_ versions of a _lot_ more
things. All the userspace visible objects (crtc, plane, encoder,
crtc), anything else hanging of those (maybe a drmm_get_edid, at
least for panels and other built-in stuff).
Also some more thoughts on why we're not reusing devm_ with maybe a
fake struct device embedded into the drm_device (we can't use the
kdev, since that's in each drm_minor).
- Code review gets extremely tricky, since every time you see a devm_
you need to carefully check whether the fake device (with the
drm_device lifetim) or the real device (with the lifetim of the
underlying physical device and driver binding) are used. That's not
going to help at all, and we have enormous amounts of drivers who
use devm_ where they really shouldn't. Having different types makes
sure the compiler type checks this for us and ensures correctness.
- The set of functions are very much non-overlapping. E.g.
devm_ioremap makes total sense, drmm_ioremap has the wrong lifetime,
since hw resources need to be cleaned out at driver unbind and wont
outlive that like a drm_device. Similar, but other way round for
drmm_connector_init (which is the only correct version, devm_ for
drm_connector is just buggy). Simply not having the wrong version
again prevents bugs.
Finally I guess this opens a huge todo for all the drivers. I'm
semi-tempted to do a tree-wide s/devm_kzalloc/drmm_kzalloc/ since most
likely that'll fix an enormous amount of bugs and most likely not
cause any issues at all (aside from maybe holding onto memory slightly
too long).
v2:
- Doc improvements from Laurent.
- Also add kerneldoc for the new drmm_add_action_or_reset.
v3:
- Remove kerneldoc for drmm_remove_action.
Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Cc: Sam Ravnborg <sam@ravnborg.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: "Rafael J. Wysocki" <rafael@kernel.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
fixup docs
Link: https://patchwork.freedesktop.org/patch/msgid/20200323144950.3018436-52-daniel.vetter@ffwll.ch
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 <sam@ravnborg.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Dan Carpenter <dan.carpenter@oracle.com>
Cc: Sam Ravnborg <sam@ravnborg.org>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Neil Armstrong <narmstrong@baylibre.com
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: "Rafael J. Wysocki" <rafael@kernel.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20200324124540.3227396-1-daniel.vetter@ffwll.ch
Kernel sphinx has learned how to do that in
commit d74b0d31dd
Author: Jonathan Corbet <corbet@lwn.net>
Date: Thu Apr 25 07:55:07 2019 -0600
Docs: An initial automarkup extension for sphinx
Unfortunately it hasn't learned that yet for structures, so we're
stuck with the :c:type: noise for now still.
Reviewed-by: Thierry Reding <treding@nvidia.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20191204101933.861169-1-daniel.vetter@ffwll.ch
Now that component has docs it's worth spending a few words and
hyperlinks on recommended best practices in drm.
v2: Add another item that component shouldn't be preferred over
drm_bridge/panel and similar subsystems already providing specialized
support for specific components (Laurent). Also convert to bullet
list.
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Russell King - ARM Linux admin <linux@armlinux.org.uk>
Reviewed-by: Maxime Ripard <maxime.ripard@bootlin.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190212164615.13370-1-daniel.vetter@ffwll.ch
And move the documenation we alreay have into kerneldoc, plus a bit of
polish while at it.
v2:
- Ditch FIXME from commit message, I've resolved that already before
sending out the first version.
- Put the legacy DRIVER_ flags at the end (Sam).
Cc: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: Emil Velikov <emil.velikov@collabora.com>
Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190129104248.26607-2-daniel.vetter@ffwll.ch
Move drm_can_sleep() out of drmP.h to allow users
to get rid of the drmP.h include.
There was no header file that was a good match for this helper function.
So add this to drm_util with the relevant includes.
Add include of drm_util.h to all users.
v2:
- Update comments to use kernel-doc style (Daniel)
- Add FIXME to drm_can_sleep and add note that this
function should not be used in new code (Daniel)
v3:
- Fix kernel-doc syntax (Daniel)
- Plug drm_util.h into drm-internels.rst (Daniel)
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Sean Paul <sean@poorly.run>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: "Christian König" <christian.koenig@amd.com>
Cc: "David (ChunMing) Zhou" <David1.Zhou@amd.com>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Rob Clark <robdclark@gmail.com>
Cc: Tomi Valkeinen <tomi.valkeinen@ti.com>
Cc: Eric Anholt <eric@anholt.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20190112193251.20450-2-sam@ravnborg.org
I spotted a markup issue, plus adding the descriptions in drm_driver.
Plus a few more links while at it.
I'm still mildly unhappy with the split between fops and ioctls, but I
still think having the ioctls in the uapi chapter makes more sense. Oh
well ...
v2: Rebase.
v3: Move misplace hunk to the right patch.
Cc: Stefan Agner <stefan@agner.ch>
Acked-by: Thierry Reding <treding@nvidia.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092045.3950-1-daniel.vetter@ffwll.ch
Sync objects are new toplevel drm object, that contain a
pointer to a fence. This fence can be updated via command
submission ioctls via drivers.
There is also a generic wait obj API modelled on the vulkan
wait API (with code modelled on some amdgpu code).
These objects can be converted to an opaque fd that can be
passes between processes.
v2: rename reference/unreference to put/get (Chris)
fix leaked reference (David Zhou)
drop mutex in favour of cmpxchg (Chris)
v3: cleanups from danvet, rebase on drm_fops rename
check fd_flags is 0 in ioctls.
v4: export find/free, change replace fence to take a
syncobj. In order to support lookup first, replace
later semantics which seem in the end to be cleaner.
Reviewed-by: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Dave Airlie <airlied@redhat.com>
Pull a (much shorter) overview into drm_irq.c, and instead put the
callback documentation into in-line comments in drm_drv.h.
v2: Move the include stanzas back to the split-up patch (Stefan).
Cc: Stefan Agner <stefan@agner.ch>
Reviewed-by: Stefan Agner <stefan@agner.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092253.12833-1-daniel.vetter@ffwll.ch
drm_irq.c contains both the irq helper library (optional) and the
vblank support (optional, but part of the modeset uapi, and doesn't
require the use of the irq helpers at all.
Split this up for more clarity of the scope of the individual bits.
v2: Move misplaced hunks to this patch (Stefan).
Cc: Stefan Agner <stefan@agner.ch>
Reviewed-by: Stefan Agner <stefan@agner.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092146.12528-1-daniel.vetter@ffwll.ch
Also unify/merge with the existing stuff.
I was a bit torn where to put this, but in the end I decided to put
all the ioctl/sysfs/debugfs stuff into drm-uapi.rst. That means we
have a bit a split with the other uapi related stuff used internally,
like drm_file.[hc], but I think overall this makes more sense.
If it's too confusing we can always add more cross-links to make it
more discoverable. But the auto-sprinkling of links kernel-doc already
does seems sufficient.
Also for prettier docs and more cross-links, switch the internal
defines over to an enum, as usual.
v2: Update kerneldoc fro drm_compat_ioctl too (caught by 0day), plus a
bit more drive-by polish.
v3: Fix typo, spotted by xerpi on irc (Sergi).
v4: Add missing space in comment (Neil).
Cc: Sergi Granell <xerpi.g.12@gmail.com>
Reviewed-by: Neil Armstrong <narmstrong@baylibre.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170404095304.17599-4-daniel.vetter@ffwll.ch
First overview text (if there is any), then headers (since generally
you want to start out with the data structures), then all the other
stuff with functions.
Most of this is pre-shpinx, since with the old docbook only the
overview stuff was pulled in directly. Everything else was put in a
per-section index, so include order didn't really matter.
Acked-by: Eric Anholt <eric@anholt.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170302151638.1882-4-daniel.vetter@ffwll.ch
Well, mostly drm_file.h, and clean up all related things:
- I didnt' figure out the difference between preclose and postclose.
The existing explanation in drm-internals.rst didn't convince me,
since it's also really outdated - we clean up pending DRM events in
the core nowadays. I put a FIXME in for the future.
- Another FIXME is to have a macro for default fops.
- Lots of links all around, main areas are to tie the overview in
drm_file.c more into the callbacks in struct drm_device, and the
other is to link render/primary node code to the right sections in
drm-uapi.rst.
- Also moved the open/close stuff to drm_drv.h from drm-internals.rst,
seems like the better place for that information. Since that section
was rather outdated this amounted to full-on rewrite.
A big missing piece here is some overview graph, but I think better to
wait with that one until drm_device and drm_driver are also fully
documented.
v2: Nits from Sean.
Reviewed-by: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Liviu Dudau <Liviu.Dudau@arm.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170308141257.12119-12-daniel.vetter@ffwll.ch
Merge Laurent's drm_platform removal code. Only conflict is with the
drm_pci.h extraction, which allows me to fix up the misplayed
drm_platform_init fumble that 0day and Stephen Rothwell reported.
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Now that the last driver has been converted, the drm_platform midlayer
is unused. Remove it.
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch
Reviewed-by: Sean Paul <seanpaul@chromium.org>
kerneldoc expects the comment next to definitions, otherwise it can't
pick up exported vs. internal stuff.
This fixes a warning from the doc build done with:
$ make DOCBOOKS="" htmldocs
Fixes: d8187177b0 ("drm: add helper for printing to log or seq_file")
Cc: Rob Clark <robdclark@gmail.com>
Cc: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20161114115825.22050-8-daniel.vetter@ffwll.ch
It's super confusing that new drivers need to be marked with
DRIVER_MODESET when really it means DRIVER_MODERN. Much better to
invert the meaning and rename it to something that's suitably
off-putting.
Since there's over 100 places using DRIVER_MODESET we need to roll out
this change without a flag day.
v2: Update docs.
Reviewed-by: Frank Binns <frank.binns@imgtec.com>
Reviewed-by: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1470251470-30830-1-git-send-email-daniel.vetter@ffwll.ch
This is unfortunately not all the sphinx noise when building the gpu
documentations. But the remaining warnings have completely bogus line
and probably also file sources, and I just can't find them.
Probably some serious debuggging of the line annotations in the
sphinx/kernel-doc toolchain needed first.
Acked-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1468612088-9721-11-git-send-email-daniel.vetter@ffwll.ch
Pandoc really did a bad job of converting the big KMS properties table
to RST. Instead, put the properties into a separate plain text CSV file,
and include it in the RST file. The generated output isn't very pretty,
but at least the information is there, and it's stored in a format
that's easier to process and improve upon at a later time.
The CSV file was generated by copy-pasting the table from the HTML
generated by the DocBook toolchain into LibreOffice Calc, and then saved
as CSV, unmodified.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/17053ff08caf5cfac4f478437ef796f83a31d772.1466506505.git.jani.nikula@intel.com
While splitting the document up, the headings "shifted" from what pandoc
generated. Use the following order for headings for consistency:
==============
Document title
==============
First
=====
Second
------
Third
~~~~~
Leave the lower level headings as they are; I think those are less
important. Although RST doesn't mandate a specific order ("Rather than
imposing a fixed number and order of section title adornment styles, the
order enforced will be the order as encountered."), having the higher
levels the same overall makes it easier to follow the documents.
[I'm sort of kind of writing the recommendation for docs-next in the
mean time, but this order seems sensible, and is what I'm proposing.]
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/126f42734defac6cbb8496a481d58db7b38461dd.1466506505.git.jani.nikula@intel.com
