xf86-video-armsoc
Open-source X.org graphics driver for ARM graphics

DRM driver selection
--------------------
While most operations use only the standard DRM modesetting interfaces, certain operations
unavoidably rely on specific driver behaviour (including dumb buffer allocation flags and cursor
plane z-ordering). As such, the armsoc driver should choose a particular DRM driver dynamically
according to the current environment.

The currently supported DRM drivers are:
- pl111
- exynos
- kirin
- meson
- rockchip
- sti
- sun4i

For other drivers, you will need to implement this support yourself. A template implementation is
provided in src/drmmode_template.
The interface is defined and documented in src/drmmode_driver.h, and you should refer to this while
modifying the template to set up your DRM driver's abstraction appropriately.

You can also copy src/drmmode_template into src/drmmode_<yourdrivername>,
modify the driver_name to match with the name used in the kernel drm driver.

Summary of bo reference counting
--------------------------------
The Screen takes a ref on the scanout bo in InitScreen and drops it in ScreenClose. When the scanout bo changes
(due to a flip or a modeset) the ref is moved from the old bo to the new one by set_scanout_bo.

Pixmaps take a ref on their bo(s) when created in ARMSOCCreatePixmap2 and drop it in ARMSOCDestroyPixmap.
If ARMSOCModifyPixmapHeader points a pixmap at anything other than the scanout bo then the ref to
the existing bo (if any) is dropped.
If ARMSOCModifyPixmapHeader points a pixmap at the scanout bo the ref is moved from the old bo to the new
If ARMSOCModifyPixmapHeader changes the size of the pixmap's bo the ref is dropped, a new bo created and a
ref taken on that.

resize_scanout_bo creates and takes a ref on the new bo and drops its ref when the new bo becomes the scanout bo and
the Screen has taken a ref.

The swap chain takes a ref on the src and dst bos when a swap is scheduled in ARMSOCDRI2ScheduleSwap and drops them
in ARMSOCDRI2SwapComplete after the src becomes pARMSOC->scanout and the screen takes a ref. 

The cursor takes a ref on its bo in drmmode_cursor_init and drops it in drmmode_cursor_fini

Known issues
------------
If HWCURSOR_API_PLANE is used with Xserver < 1.19.7, it is possible cursor
animations may trigger an infinite recursion with the timers that handle
the animation. When using Xserver 1.19, the following patches should be
applied, or alternatively a version newer than 1.19.6 should be used:

  - animcur: Fix transitions between animated cursors
  - animcur: Run the timer from the device, not the screen
  - animcur: Return the next interval directly from the timer callback
  - animcur: Use fixed-size screen private

When HWCURSOR_API_PLANE is used, cursor movement blocks pixmap blitting.
An obvious example is es2gears: when the cursor is continously moved around,
the gears appear to stop moving.