Features Download
From: Greg Hackmann <ghackmann <at> google.com>
Subject: [RFC 0/4] Atomic Display Framework
Newsgroups: gmane.comp.video.dri.devel
Date: Thursday 29th August 2013 01:51:17 UTC (over 4 years ago)

ADF is an experimental display framework that I designed after
experimenting with a KMS-based hardware composer for Android.  ADF started
as an proof-of-concept implemented from scratch, so right now it's a
separate framework rather than a patchstack on top of KMS.  If there's
community interest, moving forward I'd like to merge its functionality into
KMS rather than keep it as a separate thing.

I'm going to talk about ADF at the Android and Graphics session at Linux
Plumbers.  The documentation's not done but I wanted to post these patches
to people a heads-up about ADF.  If there's interest I can write up some
more formal documentation ahead of Plumbers.

I designed ADF to deal with some serious issues I had working with KMS:

1.  The API is geared toward updating one object at a time.  Android's
graphics stack needs the entire screen updated atomically to avoid tearing,
and on some SoCs to avoid wedging the display hardware.  Rob Clark's atomic
modeset patchset worked, but copy/update/commit design meant the driver had
to keep a lot more internal state.

2.  Some SoCs don't map well to KMS's CRTC + planes + encoders + connector
model.  At the time I was dealing with hardware where the blending engines
didn't have their own framebuffer (they could only scan out constant colors
or mix the output of other blocks), and you needed to gang several mixers
together to drive high-res displays.

3.  KMS doesn't support custom pixel formats, which a lot of newer SoCs use
internally to cut down on bandwidth between hardware blocks. 

4.  KMS doesn't have a way to exchange sync fences.  As a hack I managed to
pass sync fences into the kernel as properties of the atomic pageflip, but
there was no good way to get them back out of the kernel without a side

ADF represents display devices as collections of overlay engines and
interfaces.  Overlay engines (struct adf_overlay_engine) scan out images
and interfaces (struct adf_interface) display those images.  Overlay
engines and interfaces can be connected in any n-to-n configuration that
the hardware supports.

Clients issue atomic updates to the screen by passing in a list of buffers
(struct adf_buffer) consisting of dma-buf handles, sync fences, and basic
metadata like format and size.  If this involves composing multiple
buffers, clients include a block of custom data describing the actual
composition (scaling, z-order, blending, etc.) in a driver-specific format.

Drivers provide hooks to validate these custom data blocks and commit the
new configuration to hardware.  ADF handles importing the dma-bufs and
fences, waiting on incoming sync fences before committing, advancing the
display's sync timeline, and releasing dma-bufs once they're removed from
the screen.

ADF represents pixel formats using DRM-style fourccs, and automatically
sanity-checks buffer sizes when using one of the formats listed in
drm_fourcc.h.  Drivers can support custom fourccs if they provide hooks to
validate buffers that use them.

ADF also provides driver hooks for modesetting, managing and reporting
hardware events like vsync, and changing DPMS state.  These are documented
in struct adf_{obj,overlay_engine,interface,device}_ops, and are similar to
the equivalent DRM ops.

Greg Hackmann (3):
  video: add atomic display framework
  video: adf: add display core helper
  video: adf: add memblock helper

Laurent Pinchart (1):
  video: Add generic display entity core

 drivers/video/Kconfig                |    2 +
 drivers/video/Makefile               |    2 +
 drivers/video/adf/Kconfig            |   15 +
 drivers/video/adf/Makefile           |   14 +
 drivers/video/adf/adf.c              | 1013
 drivers/video/adf/adf.h              |   49 ++
 drivers/video/adf/adf_client.c       |  853 ++++++++++++++++++++++++++++
 drivers/video/adf/adf_display.c      |  123 +++++
 drivers/video/adf/adf_fops.c         |  982
 drivers/video/adf/adf_fops.h         |   37 ++
 drivers/video/adf/adf_fops32.c       |  217 ++++++++
 drivers/video/adf/adf_fops32.h       |   78 +++
 drivers/video/adf/adf_memblock.c     |  150 +++++
 drivers/video/adf/adf_sysfs.c        |  291 ++++++++++
 drivers/video/adf/adf_sysfs.h        |   33 ++
 drivers/video/adf/adf_trace.h        |   93 ++++
 drivers/video/display/Kconfig        |    4 +
 drivers/video/display/Makefile       |    1 +
 drivers/video/display/display-core.c |  362 ++++++++++++
 include/video/adf.h                  |  743 +++++++++++++++++++++++++
 include/video/adf_client.h           |   61 ++
 include/video/adf_display.h          |   31 ++
 include/video/adf_format.h           |  282 ++++++++++
 include/video/adf_memblock.h         |   20 +
 include/video/display.h              |  150 +++++
 25 files changed, 5606 insertions(+)
 create mode 100644 drivers/video/adf/Kconfig
 create mode 100644 drivers/video/adf/Makefile
 create mode 100644 drivers/video/adf/adf.c
 create mode 100644 drivers/video/adf/adf.h
 create mode 100644 drivers/video/adf/adf_client.c
 create mode 100644 drivers/video/adf/adf_display.c
 create mode 100644 drivers/video/adf/adf_fops.c
 create mode 100644 drivers/video/adf/adf_fops.h
 create mode 100644 drivers/video/adf/adf_fops32.c
 create mode 100644 drivers/video/adf/adf_fops32.h
 create mode 100644 drivers/video/adf/adf_memblock.c
 create mode 100644 drivers/video/adf/adf_sysfs.c
 create mode 100644 drivers/video/adf/adf_sysfs.h
 create mode 100644 drivers/video/adf/adf_trace.h
 create mode 100644 drivers/video/display/Kconfig
 create mode 100644 drivers/video/display/Makefile
 create mode 100644 drivers/video/display/display-core.c
 create mode 100644 include/video/adf.h
 create mode 100644 include/video/adf_client.h
 create mode 100644 include/video/adf_display.h
 create mode 100644 include/video/adf_format.h
 create mode 100644 include/video/adf_memblock.h
 create mode 100644 include/video/display.h

CD: 3ms