1Name 2 3 EXT_protected_content 4 5Name Strings 6 7 EGL_EXT_protected_content 8 9Contributors 10 11 Ramesh Viswanathan 12 Brian Ellis 13 Colin Sharp 14 Rajeev Kulkarni 15 Mohan Maiya 16 Maurice Ribble 17 Craig Donner 18 Jan-Harald Fredriksen 19 Daniel Koch 20 Michael Golds 21 Ray Smith 22 23Contacts 24 25 Maurice Ribble (mribble 'at' qti.qualcomm.com) 26 27IP Status 28 29 No known IP claims. 30 31Status 32 33 Complete. 34 35Version 36 37 Version 12, April 14, 2016 38 39Number 40 41 EGL Extension #97 42 43Dependencies 44 45 Requires EGL 1.4. 46 47 Interactions with EGL_KHR_image_base extension. 48 49 This extension is written against the wording of the EGL 1.4. 50 Specification (12/04/2013) 51 52 This extension has interactions with EGL_EXT_protected_surface if that 53 extension is supported. The interactions are described in the main text. 54 55Overview 56 57 This extension introduces the concept of protected contexts and protected 58 resources, specifically surfaces and EGLImages. Applications can choose at 59 creation time whether a context, surface or EGLImage is protected or not. 60 61 A protected context is required to allow the GPU to operate on protected 62 resources, including protected surfaces and protected EGLImages. 63 64 An explanation of undefined behavior in this extension: Several places 65 in this extension mention undefined behavior can result, which can 66 include program termination. The reason for this is because one way 67 to handle protected content is by using a protected virtual to physical 68 memory translation layer. With this sort of solution a system may generate 69 read or write faults when a non-protected source tries to access a protected 70 buffer. Depending on the system these faults might be ignored or they might 71 cause process termination. This undefined behavior should not include 72 actually allowing a transfer of data from a protected surface to a 73 non-protected surface. 74 75New Types 76 77 None 78 79New Procedures and Functions 80 81 None 82 83New Tokens 84 85 New EGLSurface attribute name: 86 87 EGL_PROTECTED_CONTENT_EXT 0x32C0 88 89Add a new section 2.7 entitled "Protected Content" at the end of Chapter 2 (EGL 90Operation) 91 92 "The attribute EGL_PROTECTED_CONTENT_EXT can be applied to EGL contexts, 93 EGL surfaces and EGLImages. If the attribute EGL_PROTECTED_CONTENT_EXT 94 is set to EGL_TRUE by the application, then the newly created EGL object 95 is said to be protected. A protected context is required to allow the 96 GPU to operate on protected resources, including protected surfaces and 97 protected EGLImages. 98 99 GPU operations are grouped into pipeline stages. Pipeline stages can be 100 defined to be protected or not protected. Each stage defines 101 restrictions on whether it can read or write protected and unprotected 102 resources, as follows: 103 104 When a GPU stage is protected, it: 105 - Can read from protected resources 106 - Can read from unprotected resources 107 - Can write to protected resources 108 - Can NOT write to unprotected resources 109 110 When a GPU stage is not protected, it: 111 - Can NOT read from protected resources 112 - Can read from unprotected resources 113 - Can NOT write to protected resources 114 - Can write to unprotected resources 115 116 Any accesses not following these restrictions will result in undefined 117 behavior. 118 119 This extension does not specify which pipeline stages of a protected 120 context are protected or not. This is left to a client API extension to 121 define. All stages in a regular (not protected) context are not 122 protected. However, if EGL_EXT_protected_surface is also supported, a 123 regular (not protected) context will execute stages where one or more 124 protected resources is accessed as if it were a protected context. 125 126 Note that the protection state of a stage may be left implementation 127 defined by a client API extension. This means that no guarantees can be 128 made about whether the stage will be protected or not protected. 129 Practically this means that the permitted operations for such a stage 130 are the intersection of the allowed operations for protected and not 131 protected stages, i.e it: 132 133 - Can NOT read from protected resources 134 - Can read from unprotected resources 135 - Can NOT write to protected resources 136 - Can NOT write to unprotected resources 137 138 Since this is not a very useful set of operations refer to the client API 139 extension to see what operations are actually allowed. 140 141 This extension does not guarantee the implementation abides by a 142 system's digital rights management requirements. It must be verified 143 beyond the existence of this extension that the implementation of this 144 extension is trustworthy according to the requirements of a content 145 protection system." 146 147Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Contexts) 148 149 Change the fifth paragraph in section 3.7.1 Creating Rendering Contexts: 150 151 "attrib list specifies a list of attributes for the context. The 152 list has the same structure as described for eglChooseConfig. 153 Attributes that can be specified in attrib list include 154 EGL_CONTEXT_CLIENT_VERSION and EGL_PROTECTED_CONTENT_EXT. The 155 EGL_CONTEXT_CLIENT_VERSION attribute may only be specified when 156 creating a OpenGL ES context (e.g. when the current rendering API is 157 EGL_OPENGL_ES_API)." 158 159 Add the following paragraph in section 3.7.1 on p. 44 before "attrib list 160 may be NULL or empty (first attribute is EGL_NONE), in which case 161 attributes assume their default values as described below." 162 163 "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the new 164 context. If its value is EGL_TRUE, then the context is said to be 165 protected. If its value is EGL_FALSE, then the context is not 166 protected. See section 2.7 (Protected Content) for more information 167 about protected contexts. 168 169 The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." 170 171Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces) 172 173 Change the second paragraph in section 3.5 on p. 28 (describing 174 eglCreateWindowSurface): 175 176 "Attributes that can be specified in attrib list include 177 EGL_RENDER_BUFFER, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and 178 EGL_VG_ALPHA_FORMAT." 179 180 Add the following paragraph in section 3.5 on p. 28 before 181 "EGL_VG_COLORSPACE specifies the color space used by OpenVG" (describing 182 eglCreateWindowSurface(attrib_list): 183 184 "EGL_PROTECTED_CONTENT_EXT specifies the protected state of the 185 window surface. If its value is EGL_TRUE, then the surface content 186 is said to be protected. If its value is EGL_FALSE, then the surface 187 content is not protected. See section 2.7 (Protected Content) for 188 more information about protected and non-protected surfaces. 189 190 Client APIs will not allow contents of protected surfaces to be 191 accessed by non-protected contexts in the system (including 192 non-secure software running on the CPU). Such operations will result 193 in undefined behavior. 194 195 Calling eglSwapBuffers on such a protected surface will succeed, but 196 the contents may or may not be posted successfully depending on 197 whether those parts of the pipeline are capable of handling 198 protected content. Any disallowed operation will fail and result in 199 undefined behavior. 200 201 The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE." 202 203Additions to EGL_KHR_image_base extension specification 204 205 Add to section 2.5.1 Table bbb: 206 +-----------------------------+-------------------------+---------------+ 207 | Attribute | Description | Default Value | 208 +-----------------------------+-------------------------+---------------+ 209 | EGL_NONE | Marks the end of the | N/A | 210 | | attribute-value list | | 211 | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE | 212 | | pixel data | | 213 | EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE | 214 | | state | | 215 +-----------------------------+-------------------------+---------------+ 216 Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> 217 parameter 218 219 Add the following paragraph to section 2.5.1 before "Errors" (describing 220 eglCreateImageKHR): 221 222 "If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE 223 and the EGLImage sources can be guaranteed to be protected, then the 224 EGLImage is said to be protected. See section 2.7 (Protected Content) 225 for more information about protected resources including EGLImages. 226 227 If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE then: 228 229 - If EGLImage sources are not protected, the EGLImage is said to be 230 not protected. See section 2.7 (Protected Content) for more 231 information about non-protected resources including EGLImages. 232 - If EGLImage sources are protected then the EGLImage content will 233 be inaccessible to any client context irrespective of whether the 234 context is protected or not. Trying to access such an EGLImage's 235 content will result in undefined behavior." 236 237 Add the following to the Errors list in section 2.5.1 238 239 "If the value specified in <attrib_list> for EGL_PROTECTED_CONTENT_EXT 240 is EGL_TRUE, and EGL and its client is unable to make guarantees 241 regarding the protected state of the EGLImage source, the error 242 EGL_BAD_ACCESS is generated." 243 244Issues 245 1) Can a protected context be shared with a non-protected context? 246 247 RESOLVED - Yes. The rule that protected surfaces can only be used by 248 protected contexts still applies. An example use case is where 249 someone wants to render to unprotected textures within an unprotected 250 context and then share it with a protected context to be used as a texture. 251 252 2) Should all surfaces within a protected context be protected by default? 253 254 RESOLVED - No, several implementations have limited amounts of protected 255 memory, so the API will require opting into protected memory. 256 257 3) Can these protected surfaces be used by stages other than fragment 258 shader stage? 259 260 RESOLVED - Some hardware can't handle this so this behavior is undefined 261 unless there is explicit working in some new spec saying the behavior is 262 defined. This is put as an issue because this is an EGL extension and 263 should not be controlling OpenGL functionality. 264 265 4) Why is EGL_PROTECTED_CONTENT_EXT flag needed for EGLImages? 266 267 RESOLVED - A few reasons for having an explicit flag instead 268 of inferring the protected status from EGLImage sources - 269 270 1) There are multiple EGL image extensions (EGL QCOM image, EGL 271 android image and so on) that accept buffers from external modules 272 instead of client resources or allow internally allocated memory. 273 For these use cases a protected attribute is useful, so we want to 274 keep this flag. 275 2) An implementation might have a few non-standard setup steps that 276 need to be completed before a protected EGL image can be accessed. 277 This attribute along with a corresponding protected buffer will act 278 as a signal for the graphics driver to initiate/complete any such 279 steps. 280 3) An application creating an image from an external resource may not 281 be aware of the fact that the resource is protected or may be unable 282 to access its content. The successful mapping of and access to a 283 protected buffer through an EGLImage will be predicated on the 284 buffer being protected, having a protected context and the intent of 285 the application to access that buffer by passing in EGL_TRUE for the 286 attribute EGL_PROTECTED_CONTENT_EXT. 287 288 289Revision History 290 291 Rev. Date Author Changes 292 ---- -------- -------- ---------------------------------------------- 293 1 09/24/14 Ramesh Initial draft. 294 2 11/20/14 Rajeev Second draft. 295 3 03/07/16 mribble Make EXT and clean up for release. 296 4 03/10/16 mribble Cleanup. 297 5 03/18/16 mribble Fix issues brought up by Khronos group. 298 6 03/24/16 mribble Resolved some small issues found by Jan-Harald. 299 7 03/25/16 mribble Fix createContext wording. 300 8 03/30/16 mribble Added issue 5. 301 9 04/05/16 mribble Added issue 6 and better defined eglImage case. 302 10 04/08/16 rsmith - Added general section on protected content. 303 Protected context, surface and image creation now 304 refer to the general protected content principles. 305 - Added explicit definition of which stages are 306 protected, including allowing for the protected 307 state of a stage to be undefined. 308 - Formalised interactions with 309 EGL_EXT_protected_surface. 310 - Removed references to the GPU protected mode, 311 including issue 3. 312 11 04/10/16 mribble Merge and cleanup. 313 12 04/14/16 Jon Leech Cleanup formatting, reflow paragraphs and 314 quote additions consistently. Assign extension 315 number. 316