EXT_device_drm
EXT_output_drm

EGL_EXT_device_drm
EGL_EXT_output_drm

Daniel Kartch
James Jones
Christopher James Halse Rogers

Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)

Complete

Version 5 - December 28th, 2015

EGL Extension #79

EGL device extension for EGL_EXT_device_drm

EGL display extension for EGL_EXT_output_drm

EGL_EXT_device_drm requires EGL_EXT_device_base.

EGL_EXT_device_drm interacts with EGL_EXT_platform_device

EGL_EXT_device_drm requires a DRM driver.

EGL_EXT_output_drm requires EGL_EXT_output_base.

EGL_EXT_output_drm requires a DRM driver which supports KMS.

An EGLDisplay supporting EGL_EXT_output_drm must be associated
with an EGLDevice supporting EGL_EXT_device_drm.

Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems.  This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects.  The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways.  The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.

These extensions define how to map device and output handles between
EGL and DRM/KMS. An EGL implementation which provides these
extensions must have access to sufficient knowledge of the DRM
implementation to be able to perform these mappings. No requirements
are imposed on how this information is obtained, nor does this
support have any implications for how EGL devices and outputs are
implemented. Among the possibilities, support may be implemented in
a generic fashion by layering on top of DRM, or EGL and DRM backends
may be provided by the same vendor and share privileged lower level
resources. An implementation which supports these extensions may
support other low level device interfaces, such as OpenWF Display,
as well.

None

None

Added by EXT_device_drm:

    Accepted as the <name> parameter of eglQueryDeviceStringEXT

    EGL_DRM_DEVICE_FILE_EXT                 0x3233

    If EGL_EXT_platform_device is present, the following is accepted
    in the <attrib_list> of eglGetPlatformDisplayEXT().

    EGL_DRM_MASTER_FD_EXT                   0x333C

Added by EXT_output_drm:

    Accepted in the <attrib_list> of eglGetOutputLayersEXT and as
    the <attribute> parameter of eglQueryOutputLayerAttribEXT

    EGL_DRM_CRTC_EXT                        0x3234
    EGL_DRM_PLANE_EXT                       0x3235

    Accepted in the <attrib_list> of eglGetOutputPortsEXT and as
    the <attribute> parameter of eglQueryOutputPortAttribEXT

    EGL_DRM_CONNECTOR_EXT                   0x3236

EGLDeviceEXTs may be mapped to DRM device files.

To obtain a DRM device file for an EGLDeviceEXT, call
eglQueryDeviceStringEXT with <name> set to EGL_DRM_DEVICE_FILE_EXT.
The function will return a pointer to a string containing the name
of the device file (e.g. "/dev/dri/cardN").

When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute
name is EGL_DRM_MASTER_FD_EXT.  If specified, the value must be a file
descriptor with DRM master permissions on the DRM device associated
with the specified EGLDevice, as determined by EGL_DRM_DEVICE_FILE_EXT.
If the file descriptor does not refer to the correct DRM device or
does not have master permissions, the behavior is undefined.  Calls to
eglGetPlatformDeviceEXT() with the same values for <platform> and
<native_display> but distinct EGL_DRM_MASTER_FD_EXT values will return
separate EGLDisplays.

If EGL requires the use of the DRM file descriptor beyond the duration
of the call to eglGetPlatformDispay(), it will duplicate it.  If no
file descriptor is specified and EGL requires one, it will attempt to
open the device itself.  Applications should only need to specify a
file descriptor in situations where EGL may fail to open a file
descriptor itself, generally due to lack of permissions, or when EGL
will fail to acquire DRM master permissions due to conflicts with an
existing DRM client.  DRM master permissions are only required when EGL
must modify output attributes.  This extension does not define any
situations in which output attributes will be modified.

KMS CRTC, plane, and connector IDs may be used to restrict EGL
output handle searches and may be queried from EGL output handles.

Add to Table 3.10.3.1 in EGL_EXT_output_base:

    Attribute               Type      Access
    ---------------------   -------   ------
    EGL_DRM_CRTC_EXT        integer   S|R
    EGL_DRM_PLANE_EXT       integer   S|R

Add to Table 3.10.3.2 in EGL_EXT_output_base:

    Attribute               Type      Access
    ---------------------   -------   ------
    EGL_DRM_CONNECTOR_EXT   integer   S|R

Add to description of eglOutputLayerAttribEXT:

    If <layer> corresponds to a KMS CRTC and <attribute> is
    EGL_DRM_PLANE_EXT, or if <layer> corresponds to a KMS plane and
    <attribute> is EGL_DRM_CRTC_EXT, an EGL_BAD_MATCH error is
    generated.

1)  Should different values of EGL_DRM_MASTER_FD_EXT result in separate
    EGLDisplays?

    RESOLVED: Yes.  Consider an application made up of two independent
    modules running in two independently scheduled threads.  Each
    module calls eglGetPlatformDisplayEXT():

      int fd = open("/dev/dri/card0", O_RDWR);
      int attr1[] = { EGL_DRM_MASTER_FD_EXT, fd };
      dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
                                      eglDev,
                                      attr1);

    ...
                            
      dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
                                      eglDev,
                                      NULL);

    Presumably, if dpy1 == dpy2, they would both be using the same DRM
    fd for output operations internally.  That would mean display
    attribute updates would likely fail if dpy2 happened to be created
    before dpy1.  This would be painful to debug.  If dpy2 != dpy1,
    failure for dpy2 would be consistent and obvious.  The application
    author would be required to work out a scheme to share the master
    FD between modules before creating EGL displays.

#5  (December 28th, 2015) James Jones
    - Added EGL_DRM_MASTER_FD_EXT and associated
      language.
    - Added issue 1.

#4  (August 22nd, 2014) James Jones
    - Marked complete.
    - Listed Daniel as the contact.

#3  (June 5th, 2014) Daniel Kartch
    - Assigned enumerated values for constants.

#2  (May 28th, 2014) Daniel Kartch
    - Simplified description of new behavior based on refinements
      to EGL_EXT_output_base.

#1  (January 31st, 2014) Daniel Kartch
    - Initial draft, representing a signficant reworking of
      functionality previously proposed in
      EGL_EXT_native_device_drm.