1Name 2 3 EXT_device_drm 4 EXT_output_drm 5 6Name Strings 7 8 EGL_EXT_device_drm 9 EGL_EXT_output_drm 10 11Contributors 12 13 Daniel Kartch 14 James Jones 15 Christopher James Halse Rogers 16 17Contacts 18 19 Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com) 20 21Status 22 23 Complete 24 25Version 26 27 Version 5 - December 28th, 2015 28 29Number 30 31 EGL Extension #79 32 33Extension Type 34 35 EGL device extension for EGL_EXT_device_drm 36 37 EGL display extension for EGL_EXT_output_drm 38 39Dependencies 40 41 EGL_EXT_device_drm requires EGL_EXT_device_base. 42 43 EGL_EXT_device_drm interacts with EGL_EXT_platform_device 44 45 EGL_EXT_device_drm requires a DRM driver. 46 47 EGL_EXT_output_drm requires EGL_EXT_output_base. 48 49 EGL_EXT_output_drm requires a DRM driver which supports KMS. 50 51 An EGLDisplay supporting EGL_EXT_output_drm must be associated 52 with an EGLDevice supporting EGL_EXT_device_drm. 53 54Overview 55 56 Increasingly, EGL and its client APIs are being used in place of 57 "native" rendering APIs to implement the basic graphics 58 functionality of native windowing systems. This creates demand 59 for a method to initialize EGL displays and surfaces directly on 60 top of native GPU or device objects rather than native window 61 system objects. The mechanics of enumerating the underlying 62 native devices and constructing EGL displays and surfaces from 63 them have been solved in various platform and implementation- 64 specific ways. The EGL device family of extensions offers a 65 standardized framework for bootstrapping EGL without the use of 66 any underlying "native" APIs or functionality. 67 68 These extensions define how to map device and output handles between 69 EGL and DRM/KMS. An EGL implementation which provides these 70 extensions must have access to sufficient knowledge of the DRM 71 implementation to be able to perform these mappings. No requirements 72 are imposed on how this information is obtained, nor does this 73 support have any implications for how EGL devices and outputs are 74 implemented. Among the possibilities, support may be implemented in 75 a generic fashion by layering on top of DRM, or EGL and DRM backends 76 may be provided by the same vendor and share privileged lower level 77 resources. An implementation which supports these extensions may 78 support other low level device interfaces, such as OpenWF Display, 79 as well. 80 81New Types 82 83 None 84 85New Procedures and Functions 86 87 None 88 89New Tokens 90 91 Added by EXT_device_drm: 92 93 Accepted as the <name> parameter of eglQueryDeviceStringEXT 94 95 EGL_DRM_DEVICE_FILE_EXT 0x3233 96 97 If EGL_EXT_platform_device is present, the following is accepted 98 in the <attrib_list> of eglGetPlatformDisplayEXT(). 99 100 EGL_DRM_MASTER_FD_EXT 0x333C 101 102 Added by EXT_output_drm: 103 104 Accepted in the <attrib_list> of eglGetOutputLayersEXT and as 105 the <attribute> parameter of eglQueryOutputLayerAttribEXT 106 107 EGL_DRM_CRTC_EXT 0x3234 108 EGL_DRM_PLANE_EXT 0x3235 109 110 Accepted in the <attrib_list> of eglGetOutputPortsEXT and as 111 the <attribute> parameter of eglQueryOutputPortAttribEXT 112 113 EGL_DRM_CONNECTOR_EXT 0x3236 114 115New Behavior for EXT_device_drm 116 117 EGLDeviceEXTs may be mapped to DRM device files. 118 119 To obtain a DRM device file for an EGLDeviceEXT, call 120 eglQueryDeviceStringEXT with <name> set to EGL_DRM_DEVICE_FILE_EXT. 121 The function will return a pointer to a string containing the name 122 of the device file (e.g. "/dev/dri/cardN"). 123 124If EGL_EXT_platform_device is present, replace the last sentence of the 125third paragraph in section 3.2 "Initialization" with the following: 126 127 When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute 128 name is EGL_DRM_MASTER_FD_EXT. If specified, the value must be a file 129 descriptor with DRM master permissions on the DRM device associated 130 with the specified EGLDevice, as determined by EGL_DRM_DEVICE_FILE_EXT. 131 If the file descriptor does not refer to the correct DRM device or 132 does not have master permissions, the behavior is undefined. Calls to 133 eglGetPlatformDeviceEXT() with the same values for <platform> and 134 <native_display> but distinct EGL_DRM_MASTER_FD_EXT values will return 135 separate EGLDisplays. 136 137 If EGL requires the use of the DRM file descriptor beyond the duration 138 of the call to eglGetPlatformDispay(), it will duplicate it. If no 139 file descriptor is specified and EGL requires one, it will attempt to 140 open the device itself. Applications should only need to specify a 141 file descriptor in situations where EGL may fail to open a file 142 descriptor itself, generally due to lack of permissions, or when EGL 143 will fail to acquire DRM master permissions due to conflicts with an 144 existing DRM client. DRM master permissions are only required when EGL 145 must modify output attributes. This extension does not define any 146 situations in which output attributes will be modified. 147 148New Behavior for EXT_output_drm 149 150 KMS CRTC, plane, and connector IDs may be used to restrict EGL 151 output handle searches and may be queried from EGL output handles. 152 153 Add to Table 3.10.3.1 in EGL_EXT_output_base: 154 155 Attribute Type Access 156 --------------------- ------- ------ 157 EGL_DRM_CRTC_EXT integer S|R 158 EGL_DRM_PLANE_EXT integer S|R 159 160 Add to Table 3.10.3.2 in EGL_EXT_output_base: 161 162 Attribute Type Access 163 --------------------- ------- ------ 164 EGL_DRM_CONNECTOR_EXT integer S|R 165 166 Add to description of eglOutputLayerAttribEXT: 167 168 If <layer> corresponds to a KMS CRTC and <attribute> is 169 EGL_DRM_PLANE_EXT, or if <layer> corresponds to a KMS plane and 170 <attribute> is EGL_DRM_CRTC_EXT, an EGL_BAD_MATCH error is 171 generated. 172 173Issues 174 175 1) Should different values of EGL_DRM_MASTER_FD_EXT result in separate 176 EGLDisplays? 177 178 RESOLVED: Yes. Consider an application made up of two independent 179 modules running in two independently scheduled threads. Each 180 module calls eglGetPlatformDisplayEXT(): 181 182 int fd = open("/dev/dri/card0", O_RDWR); 183 int attr1[] = { EGL_DRM_MASTER_FD_EXT, fd }; 184 dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, 185 eglDev, 186 attr1); 187 188 ... 189 190 dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT, 191 eglDev, 192 NULL); 193 194 Presumably, if dpy1 == dpy2, they would both be using the same DRM 195 fd for output operations internally. That would mean display 196 attribute updates would likely fail if dpy2 happened to be created 197 before dpy1. This would be painful to debug. If dpy2 != dpy1, 198 failure for dpy2 would be consistent and obvious. The application 199 author would be required to work out a scheme to share the master 200 FD between modules before creating EGL displays. 201 202Revision History: 203 204 #5 (December 28th, 2015) James Jones 205 - Added EGL_DRM_MASTER_FD_EXT and associated 206 language. 207 - Added issue 1. 208 209 #4 (August 22nd, 2014) James Jones 210 - Marked complete. 211 - Listed Daniel as the contact. 212 213 #3 (June 5th, 2014) Daniel Kartch 214 - Assigned enumerated values for constants. 215 216 #2 (May 28th, 2014) Daniel Kartch 217 - Simplified description of new behavior based on refinements 218 to EGL_EXT_output_base. 219 220 #1 (January 31st, 2014) Daniel Kartch 221 - Initial draft, representing a signficant reworking of 222 functionality previously proposed in 223 EGL_EXT_native_device_drm. 224