1Name 2 3 EXT_robustness 4 5Name Strings 6 7 GL_EXT_robustness 8 9Contributors 10 11 Daniel Koch, TransGaming 12 Nicolas Capens, TransGaming 13 Contributors to ARB_robustness 14 15Contact 16 17 Greg Roth, NVIDIA (groth 'at' nvidia.com) 18 19Status 20 21 Complete. 22 23Version 24 25 Version 3, 2011/10/31 26 27Number 28 29 OpenGL ES Extension #107 30 31Dependencies 32 33 This extension is written against the OpenGL ES 2.0 Specification 34 but can apply to OpenGL ES 1.1 and up. 35 36 EGL_EXT_create_context_robustness is used to determine if a context 37 implementing this extension supports robust buffer access, and if it 38 supports reset notification. 39 40Overview 41 42 Several recent trends in how OpenGL integrates into modern computer 43 systems have created new requirements for robustness and security 44 for OpenGL rendering contexts. 45 46 Additionally GPU architectures now support hardware fault detection; 47 for example, video memory supporting ECC (error correcting codes) 48 and error detection. OpenGL contexts should be capable of recovering 49 from hardware faults such as uncorrectable memory errors. Along with 50 recovery from such hardware faults, the recovery mechanism can 51 also allow recovery from video memory access exceptions and system 52 software failures. System software failures can be due to device 53 changes or driver failures. 54 55 OpenGL queries that that return (write) some number of bytes to a 56 buffer indicated by a pointer parameter introduce risk of buffer 57 overflows that might be exploitable by malware. To address this, 58 queries with return value sizes that are not expressed directly by 59 the parameters to the query itself are given additional API 60 functions with an additional parameter that specifies the number of 61 bytes in the buffer and never writing bytes beyond that limit. This 62 is particularly useful for multi-threaded usage of OpenGL contexts 63 in a "share group" where one context can change objects in ways that 64 can cause buffer overflows for another context's OpenGL queries. 65 66 The original ARB_vertex_buffer_object extension includes an issue 67 that explicitly states program termination is allowed when 68 out-of-bounds vertex buffer object fetches occur. Modern graphics 69 hardware is capable well-defined behavior in the case of out-of- 70 bounds vertex buffer object fetches. Older hardware may require 71 extra checks to enforce well-defined (and termination free) 72 behavior, but this expense is warranted when processing potentially 73 untrusted content. 74 75 The intent of this extension is to address some specific robustness 76 goals: 77 78 * For all existing OpenGL queries, provide additional "safe" APIs 79 that limit data written to user pointers to a buffer size in 80 bytes that is an explicit additional parameter of the query. 81 82 * Provide a mechanism for an OpenGL application to learn about 83 graphics resets that affect the context. When a graphics reset 84 occurs, the OpenGL context becomes unusable and the application 85 must create a new context to continue operation. Detecting a 86 graphics reset happens through an inexpensive query. 87 88 * Provide an enable to guarantee that out-of-bounds buffer object 89 accesses by the GPU will have deterministic behavior and preclude 90 application instability or termination due to an incorrect buffer 91 access. Such accesses include vertex buffer fetches of 92 attributes and indices, and indexed reads of uniforms or 93 parameters from buffers. 94 95New Procedures and Functions 96 97 enum GetGraphicsResetStatusEXT(); 98 99 void ReadnPixelsEXT(int x, int y, sizei width, sizei height, 100 enum format, enum type, sizei bufSize, 101 void *data); 102 103 void GetnUniformfvEXT(uint program, int location, sizei bufSize, 104 float *params); 105 void GetnUniformivEXT(uint program, int location, sizei bufSize, 106 int *params); 107 108New Tokens 109 110 Returned by GetGraphicsResetStatusEXT: 111 112 NO_ERROR 0x0000 113 GUILTY_CONTEXT_RESET_EXT 0x8253 114 INNOCENT_CONTEXT_RESET_EXT 0x8254 115 UNKNOWN_CONTEXT_RESET_EXT 0x8255 116 117 Accepted by the <value> parameter of GetBooleanv, GetIntegerv, 118 and GetFloatv: 119 120 CONTEXT_ROBUST_ACCESS_EXT 0x90F3 121 RESET_NOTIFICATION_STRATEGY_EXT 0x8256 122 123 Returned by GetIntegerv and related simple queries when <value> is 124 RESET_NOTIFICATION_STRATEGY_EXT : 125 126 LOSE_CONTEXT_ON_RESET_EXT 0x8252 127 NO_RESET_NOTIFICATION_EXT 0x8261 128 129Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) 130 131Add a new subsection after 2.5 "GL Errors" and renumber subsequent 132sections accordingly. 133 134 2.6 "Graphics Reset Recovery" 135 136 Certain events can result in a reset of the GL context. Such a reset 137 causes all context state to be lost. Recovery from such events 138 requires recreation of all objects in the affected context. The 139 current status of the graphics reset state is returned by 140 141 enum GetGraphicsResetStatusEXT(); 142 143 The symbolic constant returned indicates if the GL context has been 144 in a reset state at any point since the last call to 145 GetGraphicsResetStatusEXT. NO_ERROR indicates that the GL context 146 has not been in a reset state since the last call. 147 GUILTY_CONTEXT_RESET_EXT indicates that a reset has been detected 148 that is attributable to the current GL context. 149 INNOCENT_CONTEXT_RESET_EXT indicates a reset has been detected that 150 is not attributable to the current GL context. 151 UNKNOWN_CONTEXT_RESET_EXT indicates a detected graphics reset whose 152 cause is unknown. 153 154 If a reset status other than NO_ERROR is returned and subsequent 155 calls return NO_ERROR, the context reset was encountered and 156 completed. If a reset status is repeatedly returned, the context may 157 be in the process of resetting. 158 159 Reset notification behavior is determined at context creation time, 160 and may be queried by calling GetIntegerv with the symbolic constant 161 RESET_NOTIFICATION_STRATEGY_EXT. 162 163 If the reset notification behavior is NO_RESET_NOTIFICATION_EXT, 164 then the implementation will never deliver notification of reset 165 events, and GetGraphicsResetStatusEXT will always return 166 NO_ERROR[fn1]. 167 [fn1: In this case it is recommended that implementations should 168 not allow loss of context state no matter what events occur. 169 However, this is only a recommendation, and cannot be relied 170 upon by applications.] 171 172 If the behavior is LOSE_CONTEXT_ON_RESET_EXT, a graphics reset will 173 result in the loss of all context state, requiring the recreation of 174 all associated objects. In this case GetGraphicsResetStatusEXT may 175 return any of the values described above. 176 177 If a graphics reset notification occurs in a context, a notification 178 must also occur in all other contexts which share objects with that 179 context[fn2]. 180 [fn2: The values returned by GetGraphicsResetStatusEXT in the 181 different contexts may differ.] 182 183 Add to Section 2.8 "Vertex Arrays" before subsection "Transferring 184 Array Elements" 185 186 Robust buffer access is enabled by creating a context with robust 187 access enabled through the window system binding APIs. When enabled, 188 indices within the vertex array that lie outside the arrays defined 189 for enabled attributes result in undefined values for the 190 corresponding attributes, but cannot result in application failure. 191 Robust buffer access behavior may be queried by calling GetIntegerv 192 with the symbolic constant CONTEXT_ROBUST_ACCESS_EXT. 193 194Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 195Operations and the Frame Buffer) 196 197 Modify section 4.3.1 "Reading Pixels" 198 199 Pixels are read using 200 201 void ReadPixels(int x, int y, sizei width, sizei height, 202 enum format, enum type, void *data); 203 void ReadnPixelsEXT(int x, int y, sizei width, sizei height, 204 enum format, enum type, sizei bufSize, 205 void *data); 206 207 Add to the description of ReadPixels: 208 209 ReadnPixelsEXT behaves identically to ReadPixels except that it does 210 not write more than <bufSize> bytes into <data>. If the buffer size 211 required to fill all the requested data is greater than <bufSize> an 212 INVALID_OPERATION error is generated and <data> is not altered. 213 214Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special 215Functions): 216 217 None 218 219Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and 220State Requests) 221 222 Modify Section 6.1.8 "Shader and Program Queries" 223 224 The commands 225 226 void GetUniformfv(uint program, int location, float *params); 227 void GetnUniformfvEXT(uint program, int location, sizei bufSize, 228 float *params); 229 void GetUniformiv(uint program, int location, int *params); 230 void GetnUniformivEXT(uint program, int location, sizei bufSize, 231 int *params); 232 233 return the value or values of the uniform at location <location> 234 for program object <program> in the array <params>. Calling 235 GetnUniformfvEXT or GetnUniformivEXT ensures that no more than 236 <bufSize> bytes are written into <params>. If the buffer size 237 required to fill all the requested data is greater than <bufSize> an 238 INVALID_OPERATION error is generated and <params> is not altered. 239 ... 240 241Additions to The OpenGL ES Shading Language Specification, Version 1. 242 243 Append to the third paragraph of section 4.1.9 "Arrays" 244 245 If robust buffer access is enabled via the OpenGL ES API, such 246 indexing must not result in abnormal program termination. The 247 results are still undefined, but implementations are encouraged to 248 produce zero values for such accesses. 249 250Interactions with EGL_EXT_create_context_robustness 251 252 If the EGL window-system binding API is used to create a context, 253 the EGL_EXT_create_context_robustness extension is supported, and 254 the attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to 255 EGL_TRUE when eglCreateContext is called, the resulting context will 256 perform robust buffer access as described above in section 2.8, and 257 the CONTEXT_ROBUST_ACCESS_EXT query will return GL_TRUE as described 258 above in section 6.1.5. 259 260 If the EGL window-system binding API is used to create a context and 261 the EGL_EXT_create_context_robustness extension is supported, then 262 the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT 263 determines the reset notification behavior and the value of 264 RESET_NOTIFICATION_STRATEGY_EXT, as described in section 2.6. 265 266Errors 267 268 ReadnPixelsEXT, GetnUniformfvEXT, and GetnUniformivEXT share all the 269 errors of their unsized buffer query counterparts with the addition 270 that INVALID_OPERATION is generated if the buffer size required to 271 fill all the requested data is greater than <bufSize>. 272 273New Implementation Dependent State 274 275 Get Value Type Get Command Minimum Value Description Sec. Attribute 276 --------- ---- ----------- ------------- --------------------------- ----- --------- 277 CONTEXT_ROBUST_ACCESS_EXT B GetIntegerv - Robust access enabled 6.1.5 - 278 RESET_NOTIFICATION_STRATEGY_EXT Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 - 279 280Issues 281 282 283 1. What should this extension be called? 284 285 RESOLVED: EXT_robustness 286 287 Since this is intended to be a version of ARB_robustness for 288 OpenGL ES, it should be named accordingly. 289 290 2. How does this extension differ from Desktop GL's ARB_robustness? 291 292 RESOLVED: Because EGL_EXT_create_context_robustness uses a 293 separate attribute to enable robust buffer access, a 294 corresponding query is added here. 295 296 3. Should we provide a context creation mechanism to enable this extension? 297 298 RESOLVED. Yes. 299 300 Currently, EGL_EXT_create_context_robustness provides this 301 mechanism via two unique attributes. These attributes differ 302 from those specified by KHR_create_context to allow for 303 differences in what functionality those attributes define. 304 305 4. What can cause a graphics reset? 306 307 Either user or implementor errors may result in a graphics reset. 308 If the application attempts to perform a rendering that takes too long 309 whether due to an infinite loop in a shader or even just a rendering 310 operation that takes too long on the given hardware. Implementation 311 errors may produce badly formed hardware commands. Memory access errors 312 may result from user or implementor mistakes. On some systems, power 313 management events such as system sleep, screen saver activation, or 314 pre-emption may also context resets to occur. Any of these events may 315 result in a graphics reset event that will be detectable by the 316 mechanism described in this extension. 317 318 5. How should the application react to a reset context event? 319 320 RESOLVED: For this extension, the application is expected to query 321 the reset status until NO_ERROR is returned. If a reset is encountered, 322 at least one *RESET* status will be returned. Once NO_ERROR is again 323 encountered, the application can safely destroy the old context and 324 create a new one. 325 326 After a reset event, apps should not use a context for any purpose 327 other than determining its reset status, and then destroying it. If a 328 context receives a reset event, all other contexts in its share group 329 will also receive reset events, and should be destroyed and 330 recreated. 331 332 Apps should be cautious in interpreting the GUILTY and INNOCENT reset 333 statuses. These are guidelines to the immediate cause of a reset, but 334 not guarantees of the ultimate cause. 335 336 6. If a graphics reset occurs in a shared context, what happens in 337 shared contexts? 338 339 RESOLVED: A reset in one context will result in a reset in all other 340 contexts in its share group. 341 342 7. How can an application query for robust buffer access support, 343 since this is now determined at context creation time? 344 345 RESOLVED. The application can query the value of ROBUST_ACCESS_EXT 346 using GetIntegerv. If true, this functionality is enabled. 347 348 8. How is the reset notification behavior controlled? 349 350 RESOLVED: Reset notification behavior is determined at context 351 creation time using EGL/GLX/WGL/etc. mechanisms. In order that shared 352 objects be handled predictably, a context cannot share with 353 another context unless both have the same reset notification 354 behavior. 355 356 357Revision History 358 359 Rev. Date Author Changes 360 ---- ------------ --------- ---------------------------------------- 361 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a 362 companion to rather than subset of KHR_create_context 363 2 11 Oct 2011 groth Merged ANGLE and NV extensions. 364 Convert to using flag to indicate robust access. 365 1 15 July 2011 groth Initial version 366