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