1Name 2 3 KHR_robustness 4 5Name Strings 6 7 GL_KHR_robustness 8 9Contributors 10 11 Daniel Koch, NVIDIA 12 Nicolas Capens, TransGaming 13 Contributors to ARB_robustness 14 15Contact 16 17 Jon Leech (oddhack 'at' sonic.net) 18 Greg Roth, NVIDIA (groth 'at' nvidia.com) 19 20Notice 21 22 Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Status 26 27 Complete. 28 Approved by the OpenGL ES Working Group on June 25, 2014. 29 Approved by the ARB on June 26, 2014. 30 Ratified by the Khronos Board of Promoters on August 7, 2014. 31 32Version 33 34 Version 11, August 21, 2014 35 36Number 37 38 ARB Extension #170 39 OpenGL ES Extension #190 40 41Dependencies 42 43 OpenGL ES 2.0 or OpenGL 3.2 are required. Some features of this 44 extension are supported by OpenGL ES only if OpenGL ES 3.0 or later is 45 supported. 46 47 EGL_EXT_create_context_robustness is used to determine if a context 48 implementing this extension supports robust buffer access, and if it 49 supports reset notification. 50 51 This extension is written against the OpenGL ES 3.1 Specification 52 (version of June 4, 2014) and the OpenGL ES 3.10.3 Shading Language 53 Specification (version of June 6, 2014). 54 55Overview 56 57 Several recent trends in how OpenGL ES integrates into modern computer 58 systems have created new requirements for robustness and security for GL 59 rendering contexts. 60 61 Additionally GPU architectures now support hardware fault detection; 62 for example, video memory supporting ECC (error correcting codes) 63 and error detection. GL contexts should be capable of recovering 64 from hardware faults such as uncorrectable memory errors. Along with 65 recovery from such hardware faults, the recovery mechanism can 66 also allow recovery from video memory access exceptions and system 67 software failures. System software failures can be due to device 68 changes or driver failures. 69 70 GL queries that return (write) some number of bytes to a 71 buffer indicated by a pointer parameter introduce risk of buffer 72 overflows that might be exploitable by malware. To address this, 73 queries with return value sizes that are not expressed directly by 74 the parameters to the query itself are given additional API 75 functions with an additional parameter that specifies the number of 76 bytes in the buffer and never writing bytes beyond that limit. This 77 is particularly useful for multi-threaded usage of GL contexts 78 in a "share group" where one context can change objects in ways that 79 can cause buffer overflows for another context's GL queries. 80 81 The original ARB_vertex_buffer_object extension includes an issue 82 that explicitly states program termination is allowed when 83 out-of-bounds vertex buffer object fetches occur. Modern graphics 84 hardware is capable of well-defined behavior in the case of out-of- 85 bounds vertex buffer object fetches. Older hardware may require 86 extra checks to enforce well-defined (and termination free) 87 behavior, but this expense is warranted when processing potentially 88 untrusted content. 89 90 The intent of this extension is to address some specific robustness 91 goals: 92 93 * For all existing GL queries, provide additional "safe" APIs 94 that limit data written to user pointers to a buffer size in 95 bytes that is an explicit additional parameter of the query. 96 97 * Provide a mechanism for a GL application to learn about 98 graphics resets that affect the context. When a graphics reset 99 occurs, the GL context becomes unusable and the application 100 must create a new context to continue operation. Detecting a 101 graphics reset happens through an inexpensive query. 102 103 * Define behavior of OpenGL calls made after a graphics reset. 104 105 * Provide an enable to guarantee that out-of-bounds buffer object 106 accesses by the GPU will have deterministic behavior and preclude 107 application instability or termination due to an incorrect buffer 108 access. Such accesses include vertex buffer fetches of 109 attributes and indices, and indexed reads of uniforms or 110 parameters from buffers. 111 112New Procedures and Functions 113 114 NOTE: when implemented in an OpenGL ES context, all entry points defined 115 by this extension must have a "KHR" suffix. When implemented in an 116 OpenGL context, all entry points must have NO suffix, as shown below. 117 118 enum GetGraphicsResetStatus(); 119 120 void ReadnPixels(int x, int y, sizei width, sizei height, 121 enum format, enum type, sizei bufSize, 122 void *data); 123 124 void GetnUniformfv(uint program, int location, sizei bufSize, 125 float *params); 126 void GetnUniformiv(uint program, int location, sizei bufSize, 127 int *params); 128 void GetnUniformuiv(uint program, int location, sizei bufSize, 129 uint *params); 130 131 132New Tokens 133 134 NOTE: when implemented in an OpenGL ES context, all tokens defined by 135 this extension must have a "_KHR" suffix. When implemented in an OpenGL 136 context, all tokens must have NO suffix, as described below. 137 138 Returned by GetGraphicsResetStatus: 139 140 NO_ERROR 0x0000 141 GUILTY_CONTEXT_RESET 0x8253 142 INNOCENT_CONTEXT_RESET 0x8254 143 UNKNOWN_CONTEXT_RESET 0x8255 144 145 Accepted by the <value> parameter of GetBooleanv, GetIntegerv, 146 and GetFloatv: 147 148 CONTEXT_ROBUST_ACCESS 0x90F3 149 RESET_NOTIFICATION_STRATEGY 0x8256 150 151 Returned by GetIntegerv and related simple queries when <value> is 152 RESET_NOTIFICATION_STRATEGY : 153 154 LOSE_CONTEXT_ON_RESET 0x8252 155 NO_RESET_NOTIFICATION 0x8261 156 157 Returned by GetError: 158 159 CONTEXT_LOST 0x0507 160 161 162Additions to the OpenGL ES 3.1 Specification 163 164 Add to section 2.3.1 "Errors" in the bullet list of implicit errors for 165 GL commands on p. 14, and modify the following paragraph: 166 167 * If the GL context has been reset as a result of a previous GL 168 command, or if the context is reset as a side effect of execution of 169 a command, a CONTEXT_LOST error is generated. 170 171 The Specification attempts to explicitly describe these implicit error 172 conditions (with the exception of OUT_OF_MEMORY [fn2] and CONTEXT_LOST 173 [fn3]) wherever they apply. However ... 174 175 [fn3] CONTEXT_LOST is not described because it occurs for reasons not 176 directly related to the affected commands, and applies to almost all GL 177 commands. 178 179 180 Add to table 2.3 "Summary of GL errors" on p. 15: 181 182 Error Description Offending command ignored? 183 ------------ ----------------------- -------------------------- 184 CONTEXT_LOST Context has been lost Except as noted for 185 and reset by the driver specific commands 186 187 188 Add a new subsection 2.3.1rob after 2.3.1 "GL Errors", and renumber 189 subsequent sections accordingly: 190 191 2.3.1rob "Graphics Reset Recovery" 192 193 Certain events can result in a reset of the GL context. After such an 194 event, it is referred to as a <lost context> and is unusable for almost 195 all purposes. Recovery requires creating a new context and recreating 196 all relevant state from the lost context. The current status of the 197 graphics reset state is returned by 198 199 enum GetGraphicsResetStatus(); 200 201 The value returned indicates if the GL context has been in a reset state 202 at any point since the last call to GetGraphicsResetStatus: 203 204 * NO_ERROR indicates that the GL context has not been in a reset state 205 since the last call. 206 * GUILTY_CONTEXT_RESET indicates that a reset has been detected 207 that is attributable to the current GL context. 208 * INNOCENT_CONTEXT_RESET indicates a reset has been detected that 209 is not attributable to the current GL context. 210 * UNKNOWN_CONTEXT_RESET indicates a detected graphics reset whose 211 cause is unknown. 212 213 If a reset status other than NO_ERROR is returned and subsequent calls 214 return NO_ERROR, the context reset was encountered and completed. If a 215 reset status is repeatedly returned, the context may be in the process 216 of resetting. 217 218 Reset notification behavior is determined at context creation time, and 219 may be queried by calling GetIntegerv with the symbolic constant 220 RESET_NOTIFICATION_STRATEGY. 221 222 If the reset notification behavior is NO_RESET_NOTIFICATION, then 223 the implementation will never deliver notification of reset events, and 224 GetGraphicsResetStatus will always return NO_ERROR[fn1]. 225 [fn1: In this case it is recommended that implementations should not 226 allow loss of context state no matter what events occur. However, 227 this is only a recommendation, and cannot be relied upon by 228 applications.] 229 230 If the behavior is LOSE_CONTEXT_ON_RESET, a graphics reset will 231 result in a lost context and require creating a new context as described 232 above. In this case GetGraphicsResetStatus will return an appropriate 233 value from those described above. 234 235 If a graphics reset notification occurs in a context, a notification 236 must also occur in all other contexts which share objects with that 237 context[fn2]. 238 [fn2: The values returned by GetGraphicsResetStatus in the 239 different contexts may differ.] 240 241 After a graphics reset has occurred on a context, subsequent GL commands 242 on that context (or any context which shares with that context) will 243 generate a CONTEXT_LOST error. Such commands will not have side effects 244 (in particular, they will not modify memory passed by pointer for query 245 results), and may not block indefinitely or cause termination of the 246 application. Exceptions to this behavior include: 247 248 * GetError and GetGraphicsResetStatus behave normally following a 249 graphics reset, so that the application can determine a reset has 250 occurred, and when it is safe to destroy and recreate the context. 251 * Any commands which might cause a polling application to block 252 indefinitely will generate a CONTEXT_LOST error, but will also 253 return a value indicating completion to the application. Such 254 commands include: 255 256 + GetSynciv with <pname> SYNC_STATUS ignores the other parameters 257 and returns SIGNALED in <values>. 258 + GetQueryObjectuiv with <pname> QUERY_RESULT_AVAILABLE ignores the 259 other parameters and returns TRUE in <params>. 260 261 262 Modify section 7.12 "Shader, Program, and Program Pipeline Queries" 263 on p. 125 to add the GetnUniform* commands: 264 265 The commands 266 267 [enumerate existing GetUniform*v commands, then add] 268 269 void GetnUniformfv(uint program, int location, sizei bufSize, 270 float *params); 271 void GetnUniformiv(uint program, int location, sizei bufSize, 272 int *params); 273 void GetnUniformuiv(uint program, int location, sizei bufSize, 274 uint *params); 275 276 return the value or values of the uniform at location <location> of the 277 default uniform block for program object <program> in the array 278 <params>. The type of the uniform at <location> determines the number of 279 values returned. Calling GetnUniform*v ensures that no more than 280 <bufSize> bytes are written into <params>. 281 282 Add to the Errors section for Get*Uniform* on p. 126: 283 284 An INVALID_OPERATION error is generated by GetnUniform* if the buffer 285 size required to store the requested data is greater than <bufSize> 286 287 288 Add subsection 10.3.1.1rob prior to section 10.3.2 "Vertex Attribute 289 Divisors" on p. 241: 290 291 10.3.1.1rob Robust Buffer Access Behavior 292 293 Robust buffer access is enabled by creating a context with robust access 294 enabled through the window system binding APIs. When enabled, indices 295 within the element array that reference vertex data that lies outside 296 the enabled attribute's vertex buffer object 297 [for OpenGL ES] result in undefined values 298 [for OpenGL] result in reading zero 299 for the corresponding attributes, but cannot result in application 300 failure. 301 302 Robust buffer access behavior may be queried by calling 303 GetIntegerv with the symbolic constant CONTEXT_ROBUST_ACCESS. 304 305 306 Modify section 16.1.2 "ReadPixels" on p. 332 to add the ReadnPixels 307 command: 308 309 Pixels are read using 310 311 void ReadPixels(int x, int y, sizei width, sizei height, 312 enum format, enum type, void *data); 313 void ReadnPixels(int x, int y, sizei width, sizei height, 314 enum format, enum type, sizei bufSize, 315 void *data); 316 317 The arguments after <x> and <y> to ReadPixels ... are summarized in 318 table 16.1. ReadnPixels behaves identically to ReadPixels except that 319 it does not write more than <bufSize> bytes into <data>. 320 321 322 Add to the Errors section for ReadPixels and ReadnPixels: 323 324 An INVALID_OPERATION error is generated by ReadnPixels if the buffer 325 size required to store the requested data is greater than <bufSize>. 326 327 328Additions to The OpenGL ES Shading Language Specification, Version 3.10 329 330 Modify the first paragraph of section 4.1.9 "Arrays" on p. 30: 331 332 Variables of the same type ... Undefined behavior results from indexing 333 an array with a non-constant expression that is greater than or equal to 334 the array size or less than 0. If robust buffer access is enabled (see 335 section 10.3.1.1rob of the OpenGL ES 3.1 API Specification), such 336 indexing must not result in abnormal program termination. The results 337 are still undefined, but implementations are encouraged to produce zero 338 values for such accesses. Arrays only have a single dimension ... 339 340Dependencies on OpenGL ES 341 342 For implementations against OpenGL ES, if OpenGL ES 3.0 or a later 343 version is not supported, remove all references to GetnUniformuiv and 344 remove the exceptional behavior of GetSynciv and GetQueryObjectuiv for 345 lost contexts. 346 347Interactions with EGL_EXT_create_context_robustness 348 349 If the EGL window-system binding API is used to create a context, the 350 EGL_EXT_create_context_robustness extension is supported, and the 351 attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to EGL_TRUE when 352 eglCreateContext is called, the resulting context will perform robust 353 buffer access as described above in section 10.3.1.1rob, and the 354 CONTEXT_ROBUST_ACCESS query will return GL_TRUE. 355 356 If the EGL window-system binding API is used to create a context and the 357 EGL_EXT_create_context_robustness extension is supported, then the value 358 of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT determines the 359 reset notification behavior and the value of 360 RESET_NOTIFICATION_STRATEGY, as described in section 2.3.1rob. 361 362New Implementation Dependent State 363 364 Get Value Type Get Command Minimum Value Description Sec. Attribute 365 --------------------------- ---- ----------- ----------------- --------------------------- ----------- --------- 366 CONTEXT_ROBUST_ACCESS B GetIntegerv - Robust access enabled 10.3.1.1rob - 367 RESET_NOTIFICATION_STRATEGY Z_2 GetIntegerv See sec. 2.3.1rob Reset notification behavior 2.3.1rob - 368 369Issues 370 371 (Issues 2-8 are identical to those in the base EXT_robustness 372 extension). 373 374 1. What should this extension be called? 375 376 RESOLVED: KHR_robustness 377 378 This is just the OpenGL ES EXT_robustness extension (itself based on 379 ARB_robustness) promoted to KHR status, with consistency with OpenGL 380 4.5 behavior and phrasing included. 381 382 2. How does this extension differ from Desktop GL's ARB_robustness? 383 384 RESOLVED: Because EGL_EXT_create_context_robustness uses a separate 385 attribute to enable robust buffer access, a corresponding query is 386 added here. 387 388 Also see issue 12. 389 390 3. Should we provide a context creation mechanism to enable this 391 extension? 392 393 RESOLVED. Yes. 394 395 Currently, EGL_EXT_create_context_robustness provides this mechanism 396 via two unique attributes. These attributes differ from those 397 specified by KHR_create_context to allow for differences in what 398 functionality those attributes define. 399 400 4. What can cause a graphics reset? 401 402 Either user or implementor errors may result in a graphics reset. If 403 the application attempts to perform a rendering that takes too long 404 whether due to an infinite loop in a shader or even just a rendering 405 operation that takes too long on the given hardware. Implementation 406 errors may produce badly formed hardware commands. Memory access 407 errors may result from user or implementor mistakes. On some systems, 408 power management events such as system sleep, screen saver 409 activation, or pre-emption may also context resets to occur. Any of 410 these events may result in a graphics reset event that will be 411 detectable by the mechanism described in this extension. 412 413 5. How should the application react to a reset context event? 414 415 RESOLVED: For this extension, the application is expected to query 416 the reset status until NO_ERROR is returned. If a reset is 417 encountered, at least one *RESET* status will be returned. Once 418 NO_ERROR is again encountered, the application can safely destroy the 419 old context and create a new one. 420 421 After a reset event, apps should not use a context for any purpose 422 other than determining its reset status (using either GetError to 423 identify a CONTEXT_LOST error, or GetGraphicsResetStatus()), and 424 then destroying it. If a context receives a reset event, all other 425 contexts in its share group will also receive reset events, and 426 should be destroyed and recreated. 427 428 Apps should be cautious in interpreting the GUILTY and INNOCENT reset 429 statuses. These are guidelines to the immediate cause of a reset, but 430 not guarantees of the ultimate cause. 431 432 6. If a graphics reset occurs in a shared context, what happens in 433 shared contexts? 434 435 RESOLVED: A reset in one context will result in a reset in all other 436 contexts in its share group. 437 438 7. How can an application query for robust buffer access support, since 439 this is now determined at context creation time? 440 441 RESOLVED. The application can query the value of 442 CONTEXT_ROBUST_ACCESS using GetIntegerv. If true, this 443 functionality is enabled. 444 445 8. How is the reset notification behavior controlled? 446 447 RESOLVED: Reset notification behavior is determined at context 448 creation time using EGL/GLX/WGL/etc. mechanisms. In order that shared 449 objects be handled predictably, a context cannot share with another 450 context unless both have the same reset notification behavior. 451 452 9. How does this extension differ from EXT_robustness? 453 454 RESOLVED: By adding the new CONTEXT_LOST error, removing support for 455 ES 1.1 (for logistical reasons), and changing suffixes from EXT to 456 KHR (for ES) or no suffix (for GL). 457 458 10. How should this extension be enabled via EGL? 459 460 PROPOSED: Either by using EGL 1.5 context creation APIs (see section 461 3.7.1.5 of the EGL 1.5 spec), or EGL_EXT_create_context_robustness. 462 This interaction will be noted in both the EGL 1.5 spec and the 463 extension spec by allowing at least one, and possibly both of 464 GL_EXT_robustness and GL_KHR_robustness to be supported by contexts 465 created via these mechanisms. If a context supporting 466 GL_KHR_robustness is created, it will optionally support 467 GL_KHR_robust_buffer_access_behavior as well (see issue 5 of that 468 extension). 469 470 11. What should the behavior of GL calls made after a context is lost be? 471 This can be expected to occur when the context has been lost, but the 472 app hasn't polled the reset status yet. 473 474 RESOLVED: Set a new CONTEXT_LOST error on all GL calls (except 475 GetError and GetGraphicsReset). 476 477 DISCUSSION: GetError and GetGraphicsResetStatus must continue to 478 work at least to the extent of their interactions with robustness 479 features, so that apps can determine a context was lost and see the 480 effect on other commands. Commands which might block indefinitely or 481 cause the app to block indefinitely while polling are defined to 482 return immediately, with values which should end a polling loop. Such 483 commands include sync and query object queries for completion. 484 485 Special handling of these commands is defined to return values which 486 should not cause blocking, but also to generate the CONTEXT_LOST 487 error. This is intended to deal well both with apps that are polling 488 on a query value, and apps that may test for the error immediately 489 after each command (such as debuggers). There has been no pushback 490 against 491 492 We believe there are no other commands requiring this special 493 handling in the core API. ClientWaitSync and WaitSync were also 494 proposed, but with the current language (which specifies that 495 commands on a lost context may not block) should not need exceptional 496 handling. 497 498 REJECTED OPTIONS: 499 500 A) GL will try to handle the call as best as possible. Depending on 501 the call this may use GPU resources which may now have undefined 502 contents. 503 504 B) GL calls become no-ops. This would be like having a null-dispatch 505 table installed when you don't have a current context. The problem 506 with this approach is that any call that has return parameters won't 507 fill them in and the application won't be able to detect that a value 508 was not returned. 509 510 REJECTED SUB-FEATURES: 511 512 We discussed using OUT_OF_MEMORY or INVALID_OPERATION. Both are 513 misleading and don't uniquely identify the problem as a runtime error 514 out of scope of anything the app did. 515 516 We discussed allowing all commands to have side effects in addition 517 to generating CONTEXT_LOST, such as putting a "safe" value into 518 return parameters. Without compelling reason to allow this behavior, 519 it is cleaner to define the spec to leave results unchanged aside 520 from the exceptional cases intended to prevent hanging on polling 521 loops. 522 523 12. What changed in promoting OES_robustness to KHR_robustness? What 524 remains to be done for consistency between GL and ES? 525 526 DISCUSSION: The ARB agreed to support robustness and 527 robust_buffer_access_behavior as a KHR extension, with the following 528 chnages and issues to be resolved during the ratification period 529 (none are IP-related): 530 531 a) As was done for KHR_debug, the extension is defined to have KHR 532 suffixes only in ES implementations. GL implementations do not 533 have suffixes. This is so KHR_robustness can be used as a 534 backwards-compatibility extension for OpenGL 4.5. 535 536 b) Minor spec language tweaks were done for consistency with OpenGL 537 4.5, to eliminate redundancy. None are functional with the 538 exception of a change in section 10.3.1.1rob, which imposes 539 stronger requirements on out-of-bounds indexed attribute access 540 for GL (returns zero) relative to ES (undefined return values). 541 542 c) The ARB wants to add these commands to the extension, as defined 543 in OpenGL 4.5. They would be only be supported in GL contexts: 544 545 GetnUniformdv 546 GetnTexImage 547 GetnCompressedTexImage 548 549 We do not think we need to add the compatibility-mode Getn* 550 queries defined by ARB_robustness. 551 552 d) OpenGL 4.5 exposes support for robustness by setting 553 CONTEXT_FLAG_ROBUST_ACCESS_BIT in the CONTEXT_FLAGS query. ES (and 554 this extension) expose it with the CONTEXT_ROBUST_ACCESS query. 555 Jon proposes we resolve this by only defining the CONTEXT_FLAGS 556 query for GL, but defining the CONTEXT_ROBUST_ACCESS query for 557 both GL and ES, and aliasing the flag bit with the access boolean. 558 This will result in minor changes to both GL 4.5 and this 559 extension. 560 561 e) This extension modifies the Shading Language specification in 562 section 4.1.9 to restrict behavior of out of bounds array 563 accesses. GLSL 4.50 has a considerably broader section 5.11 564 "Out-of-Bounds Accesses" which restricts behavior of arrays, 565 vectors, structs, etc. We will want to include that language in 566 KHR_robustness at least as GLSL-specific language; if ES wants to 567 adopt the broader language for GLSL-ES that might still be doable. 568 569Revision History 570 571 Rev. Date Author Changes 572 ---- ------------ --------- ------------------------------------------ 573 11 2014/08/21 Jon Leech Fix typo. 574 10 2014/06/26 Jon Leech Change from OES to KHR. Update issues 1 575 and 9; add issue 12 on ES / GL 576 differences. 577 9 2014/06/26 Jon Leech Minor phrasing fixes to be more consistent 578 with equivalent GL functionality. 579 8 2014/06/24 Jon Leech Fix typos & mention GetError in issue 5. 580 Reorder API spec edits in section order. 581 Resolve issues 9-11 (Bug 12104 comments 582 #42-45). Assign CONTEXT_LOST enum. 583 7 2014/06/02 Jon Leech Remove "safe" return value behavior for 584 queries when contexts are lost (Bug 12104 585 comment #27). 586 6 2014/06/02 Jon Leech Rebase extension on OpenGL ES 3.1 specs 587 and reflow paragraphs (no functionality 588 changes are made in this version). 589 5 2014/05/16 Jon Leech Add CONTEXT_LOST error and exceptional 590 behavior for potentially-blocking 591 commands (Bug 8411). 592 4 2014/05/14 Jon Leech Add issue 11 on behavior of GL calls made 593 after a context is lost. 594 3 2014/05/07 Jon Leech Add GetnUniformuivOES for ES 3.0. 595 2 2014/04/26 Jon Leech Updates based on Ken's comments in bug 596 12104 and to reference EGL 1.5. 597 1 2014/04/23 Jon Leech Branch from EXT_robustness version 3 and 598 promote to OES suffixes. Add issues 9-10. 599