1.. _todo:
  2
  3=========
  4TODO list
  5=========
  6
  7This section contains a list of smaller janitorial tasks in the kernel DRM
  8graphics subsystem useful as newbie projects. Or for slow rainy days.
  9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 10Subsystem-wide refactorings
 11===========================
 12
 13Remove custom dumb_map_offset implementations
 14---------------------------------------------
 15
 16All GEM based drivers should be using drm_gem_create_mmap_offset() instead.
 17Audit each individual driver, make sure it'll work with the generic
 18implementation (there's lots of outdated locking leftovers in various
 19implementations), and then remove it.
 20
 21Contact: Daniel Vetter, respective driver maintainers
 22
 
 
 23Convert existing KMS drivers to atomic modesetting
 24--------------------------------------------------
 25
 263.19 has the atomic modeset interfaces and helpers, so drivers can now be
 27converted over. Modern compositors like Wayland or Surfaceflinger on Android
 28really want an atomic modeset interface, so this is all about the bright
 29future.
 30
 31There is a conversion guide for atomic and all you need is a GPU for a
 32non-converted driver (again virtual HW drivers for KVM are still all
 33suitable).
 34
 35As part of this drivers also need to convert to universal plane (which means
 36exposing primary & cursor as proper plane objects). But that's much easier to
 37do by directly using the new atomic helper driver callbacks.
 38
 
 
 
 
 39Contact: Daniel Vetter, respective driver maintainers
 40
 
 
 41Clean up the clipped coordination confusion around planes
 42---------------------------------------------------------
 43
 44We have a helper to get this right with drm_plane_helper_check_update(), but
 45it's not consistently used. This should be fixed, preferrably in the atomic
 46helpers (and drivers then moved over to clipped coordinates). Probably the
 47helper should also be moved from drm_plane_helper.c to the atomic helpers, to
 48avoid confusion - the other helpers in that file are all deprecated legacy
 49helpers.
 50
 51Contact: Ville Syrjälä, Daniel Vetter, driver maintainers
 52
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 53Convert early atomic drivers to async commit helpers
 54----------------------------------------------------
 55
 56For the first year the atomic modeset helpers didn't support asynchronous /
 57nonblocking commits, and every driver had to hand-roll them. This is fixed
 58now, but there's still a pile of existing drivers that easily could be
 59converted over to the new infrastructure.
 60
 61One issue with the helpers is that they require that drivers handle completion
 62events for atomic commits correctly. But fixing these bugs is good anyway.
 63
 
 
 
 
 64Contact: Daniel Vetter, respective driver maintainers
 65
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 66Fallout from atomic KMS
 67-----------------------
 68
 69``drm_atomic_helper.c`` provides a batch of functions which implement legacy
 70IOCTLs on top of the new atomic driver interface. Which is really nice for
 71gradual conversion of drivers, but unfortunately the semantic mismatches are
 72a bit too severe. So there's some follow-up work to adjust the function
 73interfaces to fix these issues:
 74
 75* atomic needs the lock acquire context. At the moment that's passed around
 76  implicitly with some horrible hacks, and it's also allocate with
 77  ``GFP_NOFAIL`` behind the scenes. All legacy paths need to start allocating
 78  the acquire context explicitly on stack and then also pass it down into
 79  drivers explicitly so that the legacy-on-atomic functions can use them.
 80
 81  Except for some driver code this is done. This task should be finished by
 82  adding WARN_ON(!drm_drv_uses_atomic_modeset) in drm_modeset_lock_all().
 83
 84* A bunch of the vtable hooks are now in the wrong place: DRM has a split
 85  between core vfunc tables (named ``drm_foo_funcs``), which are used to
 86  implement the userspace ABI. And then there's the optional hooks for the
 87  helper libraries (name ``drm_foo_helper_funcs``), which are purely for
 88  internal use. Some of these hooks should be move from ``_funcs`` to
 89  ``_helper_funcs`` since they are not part of the core ABI. There's a
 90  ``FIXME`` comment in the kerneldoc for each such case in ``drm_crtc.h``.
 91
 92Contact: Daniel Vetter
 93
 
 
 94Get rid of dev->struct_mutex from GEM drivers
 95---------------------------------------------
 96
 97``dev->struct_mutex`` is the Big DRM Lock from legacy days and infested
 98everything. Nowadays in modern drivers the only bit where it's mandatory is
 99serializing GEM buffer object destruction. Which unfortunately means drivers
100have to keep track of that lock and either call ``unreference`` or
101``unreference_locked`` depending upon context.
102
103Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8,
104and there's a ``gem_free_object_unlocked`` callback for any drivers which are
105entirely ``struct_mutex`` free.
106
107For drivers that need ``struct_mutex`` it should be replaced with a driver-
108private lock. The tricky part is the BO free functions, since those can't
109reliably take that lock any more. Instead state needs to be protected with
110suitable subordinate locks or some cleanup work pushed to a worker thread. For
111performance-critical drivers it might also be better to go with a more
112fine-grained per-buffer object and per-context lockings scheme. Currently only the
113``msm`` driver still use ``struct_mutex``.
114
115Contact: Daniel Vetter, respective driver maintainers
116
117Convert instances of dev_info/dev_err/dev_warn to their DRM_DEV_* equivalent
118----------------------------------------------------------------------------
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
119
120For drivers which could have multiple instances, it is necessary to
121differentiate between which is which in the logs. Since DRM_INFO/WARN/ERROR
122don't do this, drivers used dev_info/warn/err to make this differentiation. We
123now have DRM_DEV_* variants of the drm print macros, so we can start to convert
124those drivers back to using drm-formwatted specific log messages.
125
126Before you start this conversion please contact the relevant maintainers to make
127sure your work will be merged - not everyone agrees that the DRM dmesg macros
128are better.
129
130Contact: Sean Paul, Maintainer of the driver you plan to convert
131
 
 
132Convert drivers to use simple modeset suspend/resume
133----------------------------------------------------
134
135Most drivers (except i915 and nouveau) that use
136drm_atomic_helper_suspend/resume() can probably be converted to use
137drm_mode_config_helper_suspend/resume(). Also there's still open-coded version
138of the atomic suspend/resume code in older atomic modeset drivers.
139
140Contact: Maintainer of the driver you plan to convert
141
142Convert drivers to use drm_fb_helper_fbdev_setup/teardown()
143-----------------------------------------------------------
144
145Most drivers can use drm_fb_helper_fbdev_setup() except maybe:
 
146
147- amdgpu which has special logic to decide whether to call
148  drm_helper_disable_unused_functions()
 
 
 
149
150- armada which isn't atomic and doesn't call
151  drm_helper_disable_unused_functions()
152
153- i915 which calls drm_fb_helper_initial_config() in a worker
154
155Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can
156probably use drm_fb_helper_fbdev_teardown().
157
158Contact: Maintainer of the driver you plan to convert
 
 
 
159
160Clean up mmap forwarding
161------------------------
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
162
163A lot of drivers forward gem mmap calls to dma-buf mmap for imported buffers.
164And also a lot of them forward dma-buf mmap to the gem mmap implementations.
165There's drm_gem_prime_mmap() for this now, but still needs to be rolled out.
166
167Contact: Daniel Vetter
168
 
 
169Generic fbdev defio support
170---------------------------
171
172The defio support code in the fbdev core has some very specific requirements,
173which means drivers need to have a special framebuffer for fbdev. Which prevents
174us from using the generic fbdev emulation code everywhere. The main issue is
175that it uses some fields in struct page itself, which breaks shmem gem objects
176(and other things).
177
178Possible solution would be to write our own defio mmap code in the drm fbdev
179emulation. It would need to fully wrap the existing mmap ops, forwarding
180everything after it has done the write-protect/mkwrite trickery:
181
182- In the drm_fbdev_fb_mmap helper, if we need defio, change the
183  default page prots to write-protected with something like this::
184
185      vma->vm_page_prot = pgprot_wrprotect(vma->vm_page_prot);
186
187- Set the mkwrite and fsync callbacks with similar implementions to the core
188  fbdev defio stuff. These should all work on plain ptes, they don't actually
189  require a struct page.  uff. These should all work on plain ptes, they don't
190  actually require a struct page.
191
192- Track the dirty pages in a separate structure (bitfield with one bit per page
193  should work) to avoid clobbering struct page.
194
195Might be good to also have some igt testcases for this.
196
197Contact: Daniel Vetter, Noralf Tronnes
198
199idr_init_base()
200---------------
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
201
202DRM core&drivers uses a lot of idr (integer lookup directories) for mapping
203userspace IDs to internal objects, and in most places ID=0 means NULL and hence
204is never used. Switching to idr_init_base() for these would make the idr more
205efficient.
206
207Contact: Daniel Vetter
208
209struct drm_gem_object_funcs
210---------------------------
211
212GEM objects can now have a function table instead of having the callbacks on the
213DRM driver struct. This is now the preferred way and drivers can be moved over.
214
215We also need a 2nd version of the CMA define that doesn't require the
216vmapping to be present (different hook for prime importing). Plus this needs to
217be rolled out to all drivers using their own implementations, too.
218
219Use DRM_MODESET_LOCK_ALL_* helpers instead of boilerplate
220---------------------------------------------------------
221
222For cases where drivers are attempting to grab the modeset locks with a local
223acquire context. Replace the boilerplate code surrounding
224drm_modeset_lock_all_ctx() with DRM_MODESET_LOCK_ALL_BEGIN() and
225DRM_MODESET_LOCK_ALL_END() instead.
226
227This should also be done for all places where drm_modest_lock_all() is still
228used.
229
230As a reference, take a look at the conversions already completed in drm core.
 
231
232Contact: Sean Paul, respective driver maintainers
 
 
233
234Rename CMA helpers to DMA helpers
235---------------------------------
236
237CMA (standing for contiguous memory allocator) is really a bit an accident of
238what these were used for first, a much better name would be DMA helpers. In the
239text these should even be called coherent DMA memory helpers (so maybe CDM, but
240no one knows what that means) since underneath they just use dma_alloc_coherent.
241
242Contact: Laurent Pinchart, Daniel Vetter
 
 
 
 
 
 
243
244Convert direct mode.vrefresh accesses to use drm_mode_vrefresh()
245----------------------------------------------------------------
 
 
 
246
247drm_display_mode.vrefresh isn't guaranteed to be populated. As such, using it
248is risky and has been known to cause div-by-zero bugs. Fortunately, drm core
249has helper which will use mode.vrefresh if it's !0 and will calculate it from
250the timings when it's 0.
251
252Use simple search/replace, or (more fun) cocci to replace instances of direct
253vrefresh access with a call to the helper. Check out
254https://lists.freedesktop.org/archives/dri-devel/2019-January/205186.html for
255inspiration.
256
257Once all instances of vrefresh have been converted, remove vrefresh from
258drm_display_mode to avoid future use.
259
260Contact: Sean Paul
 
261
262Remove drm_display_mode.hsync
263-----------------------------
 
 
264
265We have drm_mode_hsync() to calculate this from hsync_start/end, since drivers
266shouldn't/don't use this, remove this member to avoid any temptations to use it
267in the future. If there is any debug code using drm_display_mode.hsync, convert
268it to use drm_mode_hsync() instead.
269
270Contact: Sean Paul
 
 
271
272drm_fb_helper tasks
273-------------------
274
275- drm_fb_helper_restore_fbdev_mode_unlocked() should call restore_fbdev_mode()
276  not the _force variant so it can bail out if there is a master. But first
277  these igt tests need to be fixed: kms_fbcon_fbt@psr and
278  kms_fbcon_fbt@psr-suspend.
279
280- The max connector argument for drm_fb_helper_init() and
281  drm_fb_helper_fbdev_setup() isn't used anymore and can be removed.
282
283- The helper doesn't keep an array of connectors anymore so these can be
284  removed: drm_fb_helper_single_add_all_connectors(),
285  drm_fb_helper_add_one_connector() and drm_fb_helper_remove_one_connector().
286
287Core refactorings
288=================
 
289
290Clean up the DRM header mess
291----------------------------
292
293The DRM subsystem originally had only one huge global header, ``drmP.h``. This
294is now split up, but many source files still include it. The remaining part of
295the cleanup work here is to replace any ``#include <drm/drmP.h>`` by only the
296headers needed (and fixing up any missing pre-declarations in the headers).
297
298In the end no .c file should need to include ``drmP.h`` anymore.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
299
300Contact: Daniel Vetter
 
 
301
302Make panic handling work
303------------------------
304
305This is a really varied tasks with lots of little bits and pieces:
306
307* The panic path can't be tested currently, leading to constant breaking. The
308  main issue here is that panics can be triggered from hardirq contexts and
309  hence all panic related callback can run in hardirq context. It would be
310  awesome if we could test at least the fbdev helper code and driver code by
311  e.g. trigger calls through drm debugfs files. hardirq context could be
312  achieved by using an IPI to the local processor.
313
314* There's a massive confusion of different panic handlers. DRM fbdev emulation
315  helpers have one, but on top of that the fbcon code itself also has one. We
316  need to make sure that they stop fighting over each another.
 
 
 
 
317
318* ``drm_can_sleep()`` is a mess. It hides real bugs in normal operations and
319  isn't a full solution for panic paths. We need to make sure that it only
320  returns true if there's a panic going on for real, and fix up all the
321  fallout.
322
323* The panic handler must never sleep, which also means it can't ever
324  ``mutex_lock()``. Also it can't grab any other lock unconditionally, not
325  even spinlocks (because NMI and hardirq can panic too). We need to either
326  make sure to not call such paths, or trylock everything. Really tricky.
327
328* For the above locking troubles reasons it's pretty much impossible to
329  attempt a synchronous modeset from panic handlers. The only thing we could
330  try to achive is an atomic ``set_base`` of the primary plane, and hope that
331  it shows up. Everything else probably needs to be delayed to some worker or
332  something else which happens later on. Otherwise it just kills the box
333  harder, prevent the panic from going out on e.g. netconsole.
334
335* There's also proposal for a simplied DRM console instead of the full-blown
336  fbcon and DRM fbdev emulation. Any kind of panic handling tricks should
337  obviously work for both console, in case we ever get kmslog merged.
338
339Contact: Daniel Vetter
340
 
 
341Clean up the debugfs support
342----------------------------
343
344There's a bunch of issues with it:
345
346- The drm_info_list ->show() function doesn't even bother to cast to the drm
347  structure for you. This is lazy.
 
 
 
 
348
349- We probably want to have some support for debugfs files on crtc/connectors and
350  maybe other kms objects directly in core. There's even drm_print support in
351  the funcs for these objects to dump kms state, so it's all there. And then the
352  ->show() functions should obviously give you a pointer to the right object.
353
354- The drm_info_list stuff is centered on drm_minor instead of drm_device. For
355  anything we want to print drm_device (or maybe drm_file) is the right thing.
356
357- The drm_driver->debugfs_init hooks we have is just an artifact of the old
358  midlayered load sequence. DRM debugfs should work more like sysfs, where you
359  can create properties/files for an object anytime you want, and the core
360  takes care of publishing/unpuplishing all the files at register/unregister
361  time. Drivers shouldn't need to worry about these technicalities, and fixing
362  this (together with the drm_minor->drm_device move) would allow us to remove
363  debugfs_init.
364
365- Drop the return code and error checking from all debugfs functions. Greg KH is
366  working on this already.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
367
368Contact: Daniel Vetter
369
370KMS cleanups
371------------
 
 
372
373Some of these date from the very introduction of KMS in 2008 ...
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
374
375- Make ->funcs and ->helper_private vtables optional. There's a bunch of empty
376  function tables in drivers, but before we can remove them we need to make sure
377  that all the users in helpers and drivers do correctly check for a NULL
378  vtable.
379
380- Cleanup up the various ->destroy callbacks. A lot of them just wrapt the
381  drm_*_cleanup implementations and can be removed. Some tack a kfree() at the
382  end, for which we could add drm_*_cleanup_kfree(). And then there's the (for
383  historical reasons) misnamed drm_primary_helper_destroy() function.
384
385Better Testing
386==============
387
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
388Enable trinity for DRM
389----------------------
390
391And fix up the fallout. Should be really interesting ...
392
 
 
393Make KMS tests in i-g-t generic
394-------------------------------
395
396The i915 driver team maintains an extensive testsuite for the i915 DRM driver,
397including tons of testcases for corner-cases in the modesetting API. It would
398be awesome if those tests (at least the ones not relying on Intel-specific GEM
399features) could be made to run on any KMS driver.
400
401Basic work to run i-g-t tests on non-i915 is done, what's now missing is mass-
402converting things over. For modeset tests we also first need a bit of
403infrastructure to use dumb buffers for untiled buffers, to be able to run all
404the non-i915 specific modeset tests.
405
 
 
406Extend virtual test driver (VKMS)
407---------------------------------
408
409See the documentation of :ref:`VKMS <vkms>` for more details. This is an ideal
410internship task, since it only requires a virtual machine and can be sized to
411fit the available time.
412
413Contact: Daniel Vetter
414
415Backlight Refactoring
416---------------------
417
418Backlight drivers have a triple enable/disable state, which is a bit overkill.
419Plan to fix this:
420
4211. Roll out backlight_enable() and backlight_disable() helpers everywhere. This
422   has started already.
4232. In all, only look at one of the three status bits set by the above helpers.
4243. Remove the other two status bits.
425
426Contact: Daniel Vetter
427
 
 
428Driver Specific
429===============
430
431AMD DC Display Driver
432---------------------
433
434AMD DC is the display driver for AMD devices starting with Vega. There has been
435a bunch of progress cleaning it up but there's still plenty of work to be done.
436
437See drivers/gpu/drm/amd/display/TODO for tasks.
438
439Contact: Harry Wentland, Alex Deucher
440
441i915
442----
443
444- Our early/late pm callbacks could be removed in favour of using
445  device_link_add to model the dependency between i915 and snd_had. See
446  https://dri.freedesktop.org/docs/drm/driver-api/device_link.html
447
448Bootsplash
449==========
450
451There is support in place now for writing internal DRM clients making it
452possible to pick up the bootsplash work that was rejected because it was written
453for fbdev.
454
455- [v6,8/8] drm/client: Hack: Add bootsplash example
456  https://patchwork.freedesktop.org/patch/306579/
457
458- [RFC PATCH v2 00/13] Kernel based bootsplash
459  https://lkml.org/lkml/2017/12/13/764
460
461Contact: Sam Ravnborg
462
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
463Outside DRM
464===========

  1.. _todo:
  2
  3=========
  4TODO list
  5=========
  6
  7This section contains a list of smaller janitorial tasks in the kernel DRM
  8graphics subsystem useful as newbie projects. Or for slow rainy days.
  9
 10Difficulty
 11----------
 12
 13To make it easier task are categorized into different levels:
 14
 15Starter: Good tasks to get started with the DRM subsystem.
 16
 17Intermediate: Tasks which need some experience with working in the DRM
 18subsystem, or some specific GPU/display graphics knowledge. For debugging issue
 19it's good to have the relevant hardware (or a virtual driver set up) available
 20for testing.
 21
 22Advanced: Tricky tasks that need fairly good understanding of the DRM subsystem
 23and graphics topics. Generally need the relevant hardware for development and
 24testing.
 25
 26Expert: Only attempt these if you've successfully completed some tricky
 27refactorings already and are an expert in the specific area
 28
 29Subsystem-wide refactorings
 30===========================
 31
 32Remove custom dumb_map_offset implementations
 33---------------------------------------------
 34
 35All GEM based drivers should be using drm_gem_create_mmap_offset() instead.
 36Audit each individual driver, make sure it'll work with the generic
 37implementation (there's lots of outdated locking leftovers in various
 38implementations), and then remove it.
 39
 40Contact: Daniel Vetter, respective driver maintainers
 41
 42Level: Intermediate
 43
 44Convert existing KMS drivers to atomic modesetting
 45--------------------------------------------------
 46
 473.19 has the atomic modeset interfaces and helpers, so drivers can now be
 48converted over. Modern compositors like Wayland or Surfaceflinger on Android
 49really want an atomic modeset interface, so this is all about the bright
 50future.
 51
 52There is a conversion guide for atomic [1]_ and all you need is a GPU for a
 53non-converted driver.  The "Atomic mode setting design overview" series [2]_
 54[3]_ at LWN.net can also be helpful.
 55
 56As part of this drivers also need to convert to universal plane (which means
 57exposing primary & cursor as proper plane objects). But that's much easier to
 58do by directly using the new atomic helper driver callbacks.
 59
 60  .. [1] https://blog.ffwll.ch/2014/11/atomic-modeset-support-for-kms-drivers.html
 61  .. [2] https://lwn.net/Articles/653071/
 62  .. [3] https://lwn.net/Articles/653466/
 63
 64Contact: Daniel Vetter, respective driver maintainers
 65
 66Level: Advanced
 67
 68Clean up the clipped coordination confusion around planes
 69---------------------------------------------------------
 70
 71We have a helper to get this right with drm_plane_helper_check_update(), but
 72it's not consistently used. This should be fixed, preferably in the atomic
 73helpers (and drivers then moved over to clipped coordinates). Probably the
 74helper should also be moved from drm_plane_helper.c to the atomic helpers, to
 75avoid confusion - the other helpers in that file are all deprecated legacy
 76helpers.
 77
 78Contact: Ville Syrjälä, Daniel Vetter, driver maintainers
 79
 80Level: Advanced
 81
 82Improve plane atomic_check helpers
 83----------------------------------
 84
 85Aside from the clipped coordinates right above there's a few suboptimal things
 86with the current helpers:
 87
 88- drm_plane_helper_funcs->atomic_check gets called for enabled or disabled
 89  planes. At best this seems to confuse drivers, worst it means they blow up
 90  when the plane is disabled without the CRTC. The only special handling is
 91  resetting values in the plane state structures, which instead should be moved
 92  into the drm_plane_funcs->atomic_duplicate_state functions.
 93
 94- Once that's done, helpers could stop calling ->atomic_check for disabled
 95  planes.
 96
 97- Then we could go through all the drivers and remove the more-or-less confused
 98  checks for plane_state->fb and plane_state->crtc.
 99
100Contact: Daniel Vetter
101
102Level: Advanced
103
104Convert early atomic drivers to async commit helpers
105----------------------------------------------------
106
107For the first year the atomic modeset helpers didn't support asynchronous /
108nonblocking commits, and every driver had to hand-roll them. This is fixed
109now, but there's still a pile of existing drivers that easily could be
110converted over to the new infrastructure.
111
112One issue with the helpers is that they require that drivers handle completion
113events for atomic commits correctly. But fixing these bugs is good anyway.
114
115Somewhat related is the legacy_cursor_update hack, which should be replaced with
116the new atomic_async_check/commit functionality in the helpers in drivers that
117still look at that flag.
118
119Contact: Daniel Vetter, respective driver maintainers
120
121Level: Advanced
122
123Rename drm_atomic_state
124-----------------------
125
126The KMS framework uses two slightly different definitions for the ``state``
127concept. For a given object (plane, CRTC, encoder, etc., so
128``drm_$OBJECT_state``), the state is the entire state of that object. However,
129at the device level, ``drm_atomic_state`` refers to a state update for a
130limited number of objects.
131
132The state isn't the entire device state, but only the full state of some
133objects in that device. This is confusing to newcomers, and
134``drm_atomic_state`` should be renamed to something clearer like
135``drm_atomic_commit``.
136
137In addition to renaming the structure itself, it would also imply renaming some
138related functions (``drm_atomic_state_alloc``, ``drm_atomic_state_get``,
139``drm_atomic_state_put``, ``drm_atomic_state_init``,
140``__drm_atomic_state_free``, etc.).
141
142Contact: Maxime Ripard <mripard@kernel.org>
143
144Level: Advanced
145
146Fallout from atomic KMS
147-----------------------
148
149``drm_atomic_helper.c`` provides a batch of functions which implement legacy
150IOCTLs on top of the new atomic driver interface. Which is really nice for
151gradual conversion of drivers, but unfortunately the semantic mismatches are
152a bit too severe. So there's some follow-up work to adjust the function
153interfaces to fix these issues:
154
155* atomic needs the lock acquire context. At the moment that's passed around
156  implicitly with some horrible hacks, and it's also allocate with
157  ``GFP_NOFAIL`` behind the scenes. All legacy paths need to start allocating
158  the acquire context explicitly on stack and then also pass it down into
159  drivers explicitly so that the legacy-on-atomic functions can use them.
160
161  Except for some driver code this is done. This task should be finished by
162  adding WARN_ON(!drm_drv_uses_atomic_modeset) in drm_modeset_lock_all().
163
164* A bunch of the vtable hooks are now in the wrong place: DRM has a split
165  between core vfunc tables (named ``drm_foo_funcs``), which are used to
166  implement the userspace ABI. And then there's the optional hooks for the
167  helper libraries (name ``drm_foo_helper_funcs``), which are purely for
168  internal use. Some of these hooks should be move from ``_funcs`` to
169  ``_helper_funcs`` since they are not part of the core ABI. There's a
170  ``FIXME`` comment in the kerneldoc for each such case in ``drm_crtc.h``.
171
172Contact: Daniel Vetter
173
174Level: Intermediate
175
176Get rid of dev->struct_mutex from GEM drivers
177---------------------------------------------
178
179``dev->struct_mutex`` is the Big DRM Lock from legacy days and infested
180everything. Nowadays in modern drivers the only bit where it's mandatory is
181serializing GEM buffer object destruction. Which unfortunately means drivers
182have to keep track of that lock and either call ``unreference`` or
183``unreference_locked`` depending upon context.
184
185Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8,
186and there's a GEM object ``free`` callback for any drivers which are
187entirely ``struct_mutex`` free.
188
189For drivers that need ``struct_mutex`` it should be replaced with a driver-
190private lock. The tricky part is the BO free functions, since those can't
191reliably take that lock any more. Instead state needs to be protected with
192suitable subordinate locks or some cleanup work pushed to a worker thread. For
193performance-critical drivers it might also be better to go with a more
194fine-grained per-buffer object and per-context lockings scheme. Currently only
195the ``msm`` and `i915` drivers use ``struct_mutex``.
196
197Contact: Daniel Vetter, respective driver maintainers
198
199Level: Advanced
200
201Move Buffer Object Locking to dma_resv_lock()
202---------------------------------------------
203
204Many drivers have their own per-object locking scheme, usually using
205mutex_lock(). This causes all kinds of trouble for buffer sharing, since
206depending which driver is the exporter and importer, the locking hierarchy is
207reversed.
208
209To solve this we need one standard per-object locking mechanism, which is
210dma_resv_lock(). This lock needs to be called as the outermost lock, with all
211other driver specific per-object locks removed. The problem is that rolling out
212the actual change to the locking contract is a flag day, due to struct dma_buf
213buffer sharing.
214
215Level: Expert
216
217Convert logging to drm_* functions with drm_device parameter
218------------------------------------------------------------
219
220For drivers which could have multiple instances, it is necessary to
221differentiate between which is which in the logs. Since DRM_INFO/WARN/ERROR
222don't do this, drivers used dev_info/warn/err to make this differentiation. We
223now have drm_* variants of the drm print functions, so we can start to convert
224those drivers back to using drm-formatted specific log messages.
225
226Before you start this conversion please contact the relevant maintainers to make
227sure your work will be merged - not everyone agrees that the DRM dmesg macros
228are better.
229
230Contact: Sean Paul, Maintainer of the driver you plan to convert
231
232Level: Starter
233
234Convert drivers to use simple modeset suspend/resume
235----------------------------------------------------
236
237Most drivers (except i915 and nouveau) that use
238drm_atomic_helper_suspend/resume() can probably be converted to use
239drm_mode_config_helper_suspend/resume(). Also there's still open-coded version
240of the atomic suspend/resume code in older atomic modeset drivers.
241
242Contact: Maintainer of the driver you plan to convert
243
244Level: Intermediate
 
245
246Convert drivers to use drm_fbdev_generic_setup()
247------------------------------------------------
248
249Most drivers can use drm_fbdev_generic_setup(). Driver have to implement
250atomic modesetting and GEM vmap support. Historically, generic fbdev emulation
251expected the framebuffer in system memory or system-like memory. By employing
252struct iosys_map, drivers with frambuffers in I/O memory can be supported
253as well.
254
255Contact: Maintainer of the driver you plan to convert
 
256
257Level: Intermediate
258
259Reimplement functions in drm_fbdev_fb_ops without fbdev
260-------------------------------------------------------
261
262A number of callback functions in drm_fbdev_fb_ops could benefit from
263being rewritten without dependencies on the fbdev module. Some of the
264helpers could further benefit from using struct iosys_map instead of
265raw pointers.
266
267Contact: Thomas Zimmermann <tzimmermann@suse.de>, Daniel Vetter
268
269Level: Advanced
270
271Benchmark and optimize blitting and format-conversion function
272--------------------------------------------------------------
273
274Drawing to display memory quickly is crucial for many applications'
275performance.
276
277On at least x86-64, sys_imageblit() is significantly slower than
278cfb_imageblit(), even though both use the same blitting algorithm and
279the latter is written for I/O memory. It turns out that cfb_imageblit()
280uses movl instructions, while sys_imageblit apparently does not. This
281seems to be a problem with gcc's optimizer. DRM's format-conversion
282helpers might be subject to similar issues.
283
284Benchmark and optimize fbdev's sys_() helpers and DRM's format-conversion
285helpers. In cases that can be further optimized, maybe implement a different
286algorithm. For micro-optimizations, use movl/movq instructions explicitly.
287That might possibly require architecture-specific helpers (e.g., storel()
288storeq()).
289
290Contact: Thomas Zimmermann <tzimmermann@suse.de>
291
292Level: Intermediate
293
294drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup
295-----------------------------------------------------------------
296
297A lot more drivers could be switched over to the drm_gem_framebuffer helpers.
298Various hold-ups:
299
300- Need to switch over to the generic dirty tracking code using
301  drm_atomic_helper_dirtyfb first (e.g. qxl).
302
303- Need to switch to drm_fbdev_generic_setup(), otherwise a lot of the custom fb
304  setup code can't be deleted.
305
306- Need to switch to drm_gem_fb_create(), as now drm_gem_fb_create() checks for
307  valid formats for atomic drivers.
308
309- Many drivers subclass drm_framebuffer, we'd need a embedding compatible
310  version of the varios drm_gem_fb_create functions. Maybe called
311  drm_gem_fb_create/_with_dirty/_with_funcs as needed.
312
313Contact: Daniel Vetter
314
315Level: Intermediate
316
317Generic fbdev defio support
318---------------------------
319
320The defio support code in the fbdev core has some very specific requirements,
321which means drivers need to have a special framebuffer for fbdev. The main
322issue is that it uses some fields in struct page itself, which breaks shmem
323gem objects (and other things). To support defio, affected drivers require
324the use of a shadow buffer, which may add CPU and memory overhead.
325
326Possible solution would be to write our own defio mmap code in the drm fbdev
327emulation. It would need to fully wrap the existing mmap ops, forwarding
328everything after it has done the write-protect/mkwrite trickery:
329
330- In the drm_fbdev_fb_mmap helper, if we need defio, change the
331  default page prots to write-protected with something like this::
332
333      vma->vm_page_prot = pgprot_wrprotect(vma->vm_page_prot);
334
335- Set the mkwrite and fsync callbacks with similar implementions to the core
336  fbdev defio stuff. These should all work on plain ptes, they don't actually
337  require a struct page.  uff. These should all work on plain ptes, they don't
338  actually require a struct page.
339
340- Track the dirty pages in a separate structure (bitfield with one bit per page
341  should work) to avoid clobbering struct page.
342
343Might be good to also have some igt testcases for this.
344
345Contact: Daniel Vetter, Noralf Tronnes
346
347Level: Advanced
348
349connector register/unregister fixes
350-----------------------------------
351
352- For most connectors it's a no-op to call drm_connector_register/unregister
353  directly from driver code, drm_dev_register/unregister take care of this
354  already. We can remove all of them.
355
356- For dp drivers it's a bit more a mess, since we need the connector to be
357  registered when calling drm_dp_aux_register. Fix this by instead calling
358  drm_dp_aux_init, and moving the actual registering into a late_register
359  callback as recommended in the kerneldoc.
360
361Level: Intermediate
362
363Remove load/unload callbacks
364----------------------------
365
366The load/unload callbacks in struct &drm_driver are very much midlayers, plus
367for historical reasons they get the ordering wrong (and we can't fix that)
368between setting up the &drm_driver structure and calling drm_dev_register().
369
370- Rework drivers to no longer use the load/unload callbacks, directly coding the
371  load/unload sequence into the driver's probe function.
372
373- Once all drivers are converted, remove the load/unload callbacks.
374
375Contact: Daniel Vetter
376
377Level: Intermediate
 
378
379Replace drm_detect_hdmi_monitor() with drm_display_info.is_hdmi
380---------------------------------------------------------------
381
382Once EDID is parsed, the monitor HDMI support information is available through
383drm_display_info.is_hdmi. Many drivers still call drm_detect_hdmi_monitor() to
384retrieve the same information, which is less efficient.
385
386Audit each individual driver calling drm_detect_hdmi_monitor() and switch to
387drm_display_info.is_hdmi if applicable.
388
389Contact: Laurent Pinchart, respective driver maintainers
 
 
 
390
391Level: Intermediate
 
392
393Consolidate custom driver modeset properties
394--------------------------------------------
395
396Before atomic modeset took place, many drivers where creating their own
397properties. Among other things, atomic brought the requirement that custom,
398driver specific properties should not be used.
399
400For this task, we aim to introduce core helpers or reuse the existing ones
401if available:
402
403A quick, unconfirmed, examples list.
 
 
 
404
405Introduce core helpers:
406- audio (amdgpu, intel, gma500, radeon)
407- brightness, contrast, etc (armada, nouveau) - overlay only (?)
408- broadcast rgb (gma500, intel)
409- colorkey (armada, nouveau, rcar) - overlay only (?)
410- dither (amdgpu, nouveau, radeon) - varies across drivers
411- underscan family (amdgpu, radeon, nouveau)
412
413Already in core:
414- colorspace (sti)
415- tv format names, enhancements (gma500, intel)
416- tv overscan, margins, etc. (gma500, intel)
417- zorder (omapdrm) - same as zpos (?)
418
 
 
 
 
419
420Contact: Emil Velikov, respective driver maintainers
 
 
 
421
422Level: Intermediate
 
423
424Use struct iosys_map throughout codebase
425----------------------------------------
426
427Pointers to shared device memory are stored in struct iosys_map. Each
428instance knows whether it refers to system or I/O memory. Most of the DRM-wide
429interface have been converted to use struct iosys_map, but implementations
430often still use raw pointers.
431
432The task is to use struct iosys_map where it makes sense.
 
 
 
433
434* Memory managers should use struct iosys_map for dma-buf-imported buffers.
435* TTM might benefit from using struct iosys_map internally.
436* Framebuffer copying and blitting helpers should operate on struct iosys_map.
437
438Contact: Thomas Zimmermann <tzimmermann@suse.de>, Christian König, Daniel Vetter
 
439
440Level: Intermediate
 
 
 
441
442Review all drivers for setting struct drm_mode_config.{max_width,max_height} correctly
443--------------------------------------------------------------------------------------
444
445The values in struct drm_mode_config.{max_width,max_height} describe the
446maximum supported framebuffer size. It's the virtual screen size, but many
447drivers treat it like limitations of the physical resolution.
448
449The maximum width depends on the hardware's maximum scanline pitch. The
450maximum height depends on the amount of addressable video memory. Review all
451drivers to initialize the fields to the correct values.
452
453Contact: Thomas Zimmermann <tzimmermann@suse.de>
 
454
455Level: Intermediate
 
 
 
456
457Request memory regions in all drivers
458-------------------------------------
459
460Go through all drivers and add code to request the memory regions that the
461driver uses. This requires adding calls to request_mem_region(),
462pci_request_region() or similar functions. Use helpers for managed cleanup
463where possible.
464
465Drivers are pretty bad at doing this and there used to be conflicts among
466DRM and fbdev drivers. Still, it's the correct thing to do.
467
468Contact: Thomas Zimmermann <tzimmermann@suse.de>
469
470Level: Starter
471
472Remove driver dependencies on FB_DEVICE
473---------------------------------------
474
475A number of fbdev drivers provide attributes via sysfs and therefore depend
476on CONFIG_FB_DEVICE to be selected. Review each driver and attempt to make
477any dependencies on CONFIG_FB_DEVICE optional. At the minimum, the respective
478code in the driver could be conditionalized via ifdef CONFIG_FB_DEVICE. Not
479all drivers might be able to drop CONFIG_FB_DEVICE.
480
481Contact: Thomas Zimmermann <tzimmermann@suse.de>
482
483Level: Starter
484
485Clean up checks for already prepared/enabled in panels
486------------------------------------------------------
487
488In a whole pile of panel drivers, we have code to make the
489prepare/unprepare/enable/disable callbacks behave as no-ops if they've already
490been called. To get some idea of the duplicated code, try::
491
492  git grep 'if.*>prepared' -- drivers/gpu/drm/panel
493  git grep 'if.*>enabled' -- drivers/gpu/drm/panel
494
495In the patch ("drm/panel: Check for already prepared/enabled in drm_panel")
496we've moved this check to the core. Now we can most definitely remove the
497check from the individual panels and save a pile of code.
498
499In adition to removing the check from the individual panels, it is believed
500that even the core shouldn't need this check and that should be considered
501an error if other code ever relies on this check. The check in the core
502currently prints a warning whenever something is relying on this check with
503dev_warn(). After a little while, we likely want to promote this to a
504WARN(1) to help encourage folks not to rely on this behavior.
505
506Contact: Douglas Anderson <dianders@chromium.org>
507
508Level: Starter/Intermediate
509
510
511Core refactorings
512=================
513
514Make panic handling work
515------------------------
516
517This is a really varied tasks with lots of little bits and pieces:
518
519* The panic path can't be tested currently, leading to constant breaking. The
520  main issue here is that panics can be triggered from hardirq contexts and
521  hence all panic related callback can run in hardirq context. It would be
522  awesome if we could test at least the fbdev helper code and driver code by
523  e.g. trigger calls through drm debugfs files. hardirq context could be
524  achieved by using an IPI to the local processor.
525
526* There's a massive confusion of different panic handlers. DRM fbdev emulation
527  helpers had their own (long removed), but on top of that the fbcon code itself
528  also has one. We need to make sure that they stop fighting over each other.
529  This is worked around by checking ``oops_in_progress`` at various entry points
530  into the DRM fbdev emulation helpers. A much cleaner approach here would be to
531  switch fbcon to the `threaded printk support
532  <https://lwn.net/Articles/800946/>`_.
533
534* ``drm_can_sleep()`` is a mess. It hides real bugs in normal operations and
535  isn't a full solution for panic paths. We need to make sure that it only
536  returns true if there's a panic going on for real, and fix up all the
537  fallout.
538
539* The panic handler must never sleep, which also means it can't ever
540  ``mutex_lock()``. Also it can't grab any other lock unconditionally, not
541  even spinlocks (because NMI and hardirq can panic too). We need to either
542  make sure to not call such paths, or trylock everything. Really tricky.
543
544* A clean solution would be an entirely separate panic output support in KMS,
545  bypassing the current fbcon support. See `[PATCH v2 0/3] drm: Add panic handling
546  <https://lore.kernel.org/dri-devel/20190311174218.51899-1-noralf@tronnes.org/>`_.
547
548* Encoding the actual oops and preceding dmesg in a QR might help with the
549  dread "important stuff scrolled away" problem. See `[RFC][PATCH] Oops messages
550  transfer using QR codes
551  <https://lore.kernel.org/lkml/1446217392-11981-1-git-send-email-alexandru.murtaza@intel.com/>`_
552  for some example code that could be reused.
 
553
554Contact: Daniel Vetter
555
556Level: Advanced
557
558Clean up the debugfs support
559----------------------------
560
561There's a bunch of issues with it:
562
563- Convert drivers to support the drm_debugfs_add_files() function instead of
564  the drm_debugfs_create_files() function.
565
566- Improve late-register debugfs by rolling out the same debugfs pre-register
567  infrastructure for connector and crtc too. That way, the drivers won't need to
568  split their setup code into init and register anymore.
569
570- We probably want to have some support for debugfs files on crtc/connectors and
571  maybe other kms objects directly in core. There's even drm_print support in
572  the funcs for these objects to dump kms state, so it's all there. And then the
573  ->show() functions should obviously give you a pointer to the right object.
574
 
 
 
575- The drm_driver->debugfs_init hooks we have is just an artifact of the old
576  midlayered load sequence. DRM debugfs should work more like sysfs, where you
577  can create properties/files for an object anytime you want, and the core
578  takes care of publishing/unpuplishing all the files at register/unregister
579  time. Drivers shouldn't need to worry about these technicalities, and fixing
580  this (together with the drm_minor->drm_device move) would allow us to remove
581  debugfs_init.
582
583Contact: Daniel Vetter
584
585Level: Intermediate
586
587Object lifetime fixes
588---------------------
589
590There's two related issues here
591
592- Cleanup up the various ->destroy callbacks, which often are all the same
593  simple code.
594
595- Lots of drivers erroneously allocate DRM modeset objects using devm_kzalloc,
596  which results in use-after free issues on driver unload. This can be serious
597  trouble even for drivers for hardware integrated on the SoC due to
598  EPROBE_DEFERRED backoff.
599
600Both these problems can be solved by switching over to drmm_kzalloc(), and the
601various convenience wrappers provided, e.g. drmm_crtc_alloc_with_planes(),
602drmm_universal_plane_alloc(), ... and so on.
603
604Contact: Daniel Vetter
605
606Level: Intermediate
607
608Remove automatic page mapping from dma-buf importing
609----------------------------------------------------
610
611When importing dma-bufs, the dma-buf and PRIME frameworks automatically map
612imported pages into the importer's DMA area. drm_gem_prime_fd_to_handle() and
613drm_gem_prime_handle_to_fd() require that importers call dma_buf_attach()
614even if they never do actual device DMA, but only CPU access through
615dma_buf_vmap(). This is a problem for USB devices, which do not support DMA
616operations.
617
618To fix the issue, automatic page mappings should be removed from the
619buffer-sharing code. Fixing this is a bit more involved, since the import/export
620cache is also tied to &drm_gem_object.import_attach. Meanwhile we paper over
621this problem for USB devices by fishing out the USB host controller device, as
622long as that supports DMA. Otherwise importing can still needlessly fail.
623
624Contact: Thomas Zimmermann <tzimmermann@suse.de>, Daniel Vetter
625
626Level: Advanced
627
 
 
 
 
 
 
 
 
 
628
629Better Testing
630==============
631
632Add unit tests using the Kernel Unit Testing (KUnit) framework
633--------------------------------------------------------------
634
635The `KUnit <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_
636provides a common framework for unit tests within the Linux kernel. Having a
637test suite would allow to identify regressions earlier.
638
639A good candidate for the first unit tests are the format-conversion helpers in
640``drm_format_helper.c``.
641
642Contact: Javier Martinez Canillas <javierm@redhat.com>
643
644Level: Intermediate
645
646Clean up and document former selftests suites
647---------------------------------------------
648
649Some KUnit test suites (drm_buddy, drm_cmdline_parser, drm_damage_helper,
650drm_format, drm_framebuffer, drm_dp_mst_helper, drm_mm, drm_plane_helper and
651drm_rect) are former selftests suites that have been converted over when KUnit
652was first introduced.
653
654These suites were fairly undocumented, and with different goals than what unit
655tests can be. Trying to identify what each test in these suites actually test
656for, whether that makes sense for a unit test, and either remove it if it
657doesn't or document it if it does would be of great help.
658
659Contact: Maxime Ripard <mripard@kernel.org>
660
661Level: Intermediate
662
663Enable trinity for DRM
664----------------------
665
666And fix up the fallout. Should be really interesting ...
667
668Level: Advanced
669
670Make KMS tests in i-g-t generic
671-------------------------------
672
673The i915 driver team maintains an extensive testsuite for the i915 DRM driver,
674including tons of testcases for corner-cases in the modesetting API. It would
675be awesome if those tests (at least the ones not relying on Intel-specific GEM
676features) could be made to run on any KMS driver.
677
678Basic work to run i-g-t tests on non-i915 is done, what's now missing is mass-
679converting things over. For modeset tests we also first need a bit of
680infrastructure to use dumb buffers for untiled buffers, to be able to run all
681the non-i915 specific modeset tests.
682
683Level: Advanced
684
685Extend virtual test driver (VKMS)
686---------------------------------
687
688See the documentation of :ref:`VKMS <vkms>` for more details. This is an ideal
689internship task, since it only requires a virtual machine and can be sized to
690fit the available time.
691
692Level: See details
693
694Backlight Refactoring
695---------------------
696
697Backlight drivers have a triple enable/disable state, which is a bit overkill.
698Plan to fix this:
699
7001. Roll out backlight_enable() and backlight_disable() helpers everywhere. This
701   has started already.
7022. In all, only look at one of the three status bits set by the above helpers.
7033. Remove the other two status bits.
704
705Contact: Daniel Vetter
706
707Level: Intermediate
708
709Driver Specific
710===============
711
712AMD DC Display Driver
713---------------------
714
715AMD DC is the display driver for AMD devices starting with Vega. There has been
716a bunch of progress cleaning it up but there's still plenty of work to be done.
717
718See drivers/gpu/drm/amd/display/TODO for tasks.
719
720Contact: Harry Wentland, Alex Deucher
721
 
 
 
 
 
 
 
722Bootsplash
723==========
724
725There is support in place now for writing internal DRM clients making it
726possible to pick up the bootsplash work that was rejected because it was written
727for fbdev.
728
729- [v6,8/8] drm/client: Hack: Add bootsplash example
730  https://patchwork.freedesktop.org/patch/306579/
731
732- [RFC PATCH v2 00/13] Kernel based bootsplash
733  https://lore.kernel.org/r/20171213194755.3409-1-mstaudt@suse.de
734
735Contact: Sam Ravnborg
736
737Level: Advanced
738
739Brightness handling on devices with multiple internal panels
740============================================================
741
742On x86/ACPI devices there can be multiple backlight firmware interfaces:
743(ACPI) video, vendor specific and others. As well as direct/native (PWM)
744register programming by the KMS driver.
745
746To deal with this backlight drivers used on x86/ACPI call
747acpi_video_get_backlight_type() which has heuristics (+quirks) to select
748which backlight interface to use; and backlight drivers which do not match
749the returned type will not register themselves, so that only one backlight
750device gets registered (in a single GPU setup, see below).
751
752At the moment this more or less assumes that there will only
753be 1 (internal) panel on a system.
754
755On systems with 2 panels this may be a problem, depending on
756what interface acpi_video_get_backlight_type() selects:
757
7581. native: in this case the KMS driver is expected to know which backlight
759   device belongs to which output so everything should just work.
7602. video: this does support controlling multiple backlights, but some work
761   will need to be done to get the output <-> backlight device mapping
762
763The above assumes both panels will require the same backlight interface type.
764Things will break on systems with multiple panels where the 2 panels need
765a different type of control. E.g. one panel needs ACPI video backlight control,
766where as the other is using native backlight control. Currently in this case
767only one of the 2 required backlight devices will get registered, based on
768the acpi_video_get_backlight_type() return value.
769
770If this (theoretical) case ever shows up, then supporting this will need some
771work. A possible solution here would be to pass a device and connector-name
772to acpi_video_get_backlight_type() so that it can deal with this.
773
774Note in a way we already have a case where userspace sees 2 panels,
775in dual GPU laptop setups with a mux. On those systems we may see
776either 2 native backlight devices; or 2 native backlight devices.
777
778Userspace already has code to deal with this by detecting if the related
779panel is active (iow which way the mux between the GPU and the panels
780points) and then uses that backlight device. Userspace here very much
781assumes a single panel though. It picks only 1 of the 2 backlight devices
782and then only uses that one.
783
784Note that all userspace code (that I know off) is currently hardcoded
785to assume a single panel.
786
787Before the recent changes to not register multiple (e.g. video + native)
788/sys/class/backlight devices for a single panel (on a single GPU laptop),
789userspace would see multiple backlight devices all controlling the same
790backlight.
791
792To deal with this userspace had to always picks one preferred device under
793/sys/class/backlight and will ignore the others. So to support brightness
794control on multiple panels userspace will need to be updated too.
795
796There are plans to allow brightness control through the KMS API by adding
797a "display brightness" property to drm_connector objects for panels. This
798solves a number of issues with the /sys/class/backlight API, including not
799being able to map a sysfs backlight device to a specific connector. Any
800userspace changes to add support for brightness control on devices with
801multiple panels really should build on top of this new KMS property.
802
803Contact: Hans de Goede
804
805Level: Advanced
806
807Buffer age or other damage accumulation algorithm for buffer damage
808===================================================================
809
810Drivers that do per-buffer uploads, need a buffer damage handling (rather than
811frame damage like drivers that do per-plane or per-CRTC uploads), but there is
812no support to get the buffer age or any other damage accumulation algorithm.
813
814For this reason, the damage helpers just fallback to a full plane update if the
815framebuffer attached to a plane has changed since the last page-flip. Drivers
816set &drm_plane_state.ignore_damage_clips to true as indication to
817drm_atomic_helper_damage_iter_init() and drm_atomic_helper_damage_iter_next()
818helpers that the damage clips should be ignored.
819
820This should be improved to get damage tracking properly working on drivers that
821do per-buffer uploads.
822
823More information about damage tracking and references to learning materials can
824be found in :ref:`damage_tracking_properties`.
825
826Contact: Javier Martinez Canillas <javierm@redhat.com>
827
828Level: Advanced
829
830Outside DRM
831===========
832
833Convert fbdev drivers to DRM
834----------------------------
835
836There are plenty of fbdev drivers for older hardware. Some hardware has
837become obsolete, but some still provides good(-enough) framebuffers. The
838drivers that are still useful should be converted to DRM and afterwards
839removed from fbdev.
840
841Very simple fbdev drivers can best be converted by starting with a new
842DRM driver. Simple KMS helpers and SHMEM should be able to handle any
843existing hardware. The new driver's call-back functions are filled from
844existing fbdev code.
845
846More complex fbdev drivers can be refactored step-by-step into a DRM
847driver with the help of the DRM fbconv helpers [4]_. These helpers provide
848the transition layer between the DRM core infrastructure and the fbdev
849driver interface. Create a new DRM driver on top of the fbconv helpers,
850copy over the fbdev driver, and hook it up to the DRM code. Examples for
851several fbdev drivers are available in Thomas Zimmermann's fbconv tree
852[4]_, as well as a tutorial of this process [5]_. The result is a primitive
853DRM driver that can run X11 and Weston.
854
855 .. [4] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv
856 .. [5] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c
857
858Contact: Thomas Zimmermann <tzimmermann@suse.de>
859
860Level: Advanced