diff -r 000000000000 -r 6474c204b198 gfx/angle/extensions/EXT_robustness.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gfx/angle/extensions/EXT_robustness.txt Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,365 @@ +Name + + EXT_robustness + +Name Strings + + GL_EXT_robustness + +Contributors + + Daniel Koch, TransGaming + Nicolas Capens, TransGaming + Contributors to ARB_robustness + +Contact + + Greg Roth, NVIDIA (groth 'at' nvidia.com) + +Status + + Complete. + +Version + + Version 3, 2011/10/31 + +Number + + OpenGL ES Extension #107 + +Dependencies + + This extension is written against the OpenGL ES 2.0 Specification + but can apply to OpenGL ES 1.1 and up. + + EGL_EXT_create_context_robustness is used to determine if a context + implementing this extension supports robust buffer access, and if it + supports reset notification. + +Overview + + Several recent trends in how OpenGL integrates into modern computer + systems have created new requirements for robustness and security + for OpenGL rendering contexts. + + Additionally GPU architectures now support hardware fault detection; + for example, video memory supporting ECC (error correcting codes) + and error detection. OpenGL contexts should be capable of recovering + from hardware faults such as uncorrectable memory errors. Along with + recovery from such hardware faults, the recovery mechanism can + also allow recovery from video memory access exceptions and system + software failures. System software failures can be due to device + changes or driver failures. + + OpenGL queries that that return (write) some number of bytes to a + buffer indicated by a pointer parameter introduce risk of buffer + overflows that might be exploitable by malware. To address this, + queries with return value sizes that are not expressed directly by + the parameters to the query itself are given additional API + functions with an additional parameter that specifies the number of + bytes in the buffer and never writing bytes beyond that limit. This + is particularly useful for multi-threaded usage of OpenGL contexts + in a "share group" where one context can change objects in ways that + can cause buffer overflows for another context's OpenGL queries. + + The original ARB_vertex_buffer_object extension includes an issue + that explicitly states program termination is allowed when + out-of-bounds vertex buffer object fetches occur. Modern graphics + hardware is capable well-defined behavior in the case of out-of- + bounds vertex buffer object fetches. Older hardware may require + extra checks to enforce well-defined (and termination free) + behavior, but this expense is warranted when processing potentially + untrusted content. + + The intent of this extension is to address some specific robustness + goals: + + * For all existing OpenGL queries, provide additional "safe" APIs + that limit data written to user pointers to a buffer size in + bytes that is an explicit additional parameter of the query. + + * Provide a mechanism for an OpenGL application to learn about + graphics resets that affect the context. When a graphics reset + occurs, the OpenGL context becomes unusable and the application + must create a new context to continue operation. Detecting a + graphics reset happens through an inexpensive query. + + * Provide an enable to guarantee that out-of-bounds buffer object + accesses by the GPU will have deterministic behavior and preclude + application instability or termination due to an incorrect buffer + access. Such accesses include vertex buffer fetches of + attributes and indices, and indexed reads of uniforms or + parameters from buffers. + +New Procedures and Functions + + enum GetGraphicsResetStatusEXT(); + + void ReadnPixelsEXT(int x, int y, sizei width, sizei height, + enum format, enum type, sizei bufSize, + void *data); + + void GetnUniformfvEXT(uint program, int location, sizei bufSize, + float *params); + void GetnUniformivEXT(uint program, int location, sizei bufSize, + int *params); + +New Tokens + + Returned by GetGraphicsResetStatusEXT: + + NO_ERROR 0x0000 + GUILTY_CONTEXT_RESET_EXT 0x8253 + INNOCENT_CONTEXT_RESET_EXT 0x8254 + UNKNOWN_CONTEXT_RESET_EXT 0x8255 + + Accepted by the parameter of GetBooleanv, GetIntegerv, + and GetFloatv: + + CONTEXT_ROBUST_ACCESS_EXT 0x90F3 + RESET_NOTIFICATION_STRATEGY_EXT 0x8256 + + Returned by GetIntegerv and related simple queries when is + RESET_NOTIFICATION_STRATEGY_EXT : + + LOSE_CONTEXT_ON_RESET_EXT 0x8252 + NO_RESET_NOTIFICATION_EXT 0x8261 + +Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) + +Add a new subsection after 2.5 "GL Errors" and renumber subsequent +sections accordingly. + + 2.6 "Graphics Reset Recovery" + + Certain events can result in a reset of the GL context. Such a reset + causes all context state to be lost. Recovery from such events + requires recreation of all objects in the affected context. The + current status of the graphics reset state is returned by + + enum GetGraphicsResetStatusEXT(); + + The symbolic constant returned indicates if the GL context has been + in a reset state at any point since the last call to + GetGraphicsResetStatusEXT. NO_ERROR indicates that the GL context + has not been in a reset state since the last call. + GUILTY_CONTEXT_RESET_EXT indicates that a reset has been detected + that is attributable to the current GL context. + INNOCENT_CONTEXT_RESET_EXT indicates a reset has been detected that + is not attributable to the current GL context. + UNKNOWN_CONTEXT_RESET_EXT indicates a detected graphics reset whose + cause is unknown. + + If a reset status other than NO_ERROR is returned and subsequent + calls return NO_ERROR, the context reset was encountered and + completed. If a reset status is repeatedly returned, the context may + be in the process of resetting. + + Reset notification behavior is determined at context creation time, + and may be queried by calling GetIntegerv with the symbolic constant + RESET_NOTIFICATION_STRATEGY_EXT. + + If the reset notification behavior is NO_RESET_NOTIFICATION_EXT, + then the implementation will never deliver notification of reset + events, and GetGraphicsResetStatusEXT will always return + NO_ERROR[fn1]. + [fn1: In this case it is recommended that implementations should + not allow loss of context state no matter what events occur. + However, this is only a recommendation, and cannot be relied + upon by applications.] + + If the behavior is LOSE_CONTEXT_ON_RESET_EXT, a graphics reset will + result in the loss of all context state, requiring the recreation of + all associated objects. In this case GetGraphicsResetStatusEXT may + return any of the values described above. + + If a graphics reset notification occurs in a context, a notification + must also occur in all other contexts which share objects with that + context[fn2]. + [fn2: The values returned by GetGraphicsResetStatusEXT in the + different contexts may differ.] + + Add to Section 2.8 "Vertex Arrays" before subsection "Transferring + Array Elements" + + Robust buffer access is enabled by creating a context with robust + access enabled through the window system binding APIs. When enabled, + indices within the vertex array that lie outside the arrays defined + for enabled attributes result in undefined values for the + corresponding attributes, but cannot result in application failure. + Robust buffer access behavior may be queried by calling GetIntegerv + with the symbolic constant CONTEXT_ROBUST_ACCESS_EXT. + +Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment +Operations and the Frame Buffer) + + Modify section 4.3.1 "Reading Pixels" + + Pixels are read using + + void ReadPixels(int x, int y, sizei width, sizei height, + enum format, enum type, void *data); + void ReadnPixelsEXT(int x, int y, sizei width, sizei height, + enum format, enum type, sizei bufSize, + void *data); + + Add to the description of ReadPixels: + + ReadnPixelsEXT behaves identically to ReadPixels except that it does + not write more than bytes into . If the buffer size + required to fill all the requested data is greater than an + INVALID_OPERATION error is generated and is not altered. + +Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special +Functions): + + None + +Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and +State Requests) + + Modify Section 6.1.8 "Shader and Program Queries" + + The commands + + void GetUniformfv(uint program, int location, float *params); + void GetnUniformfvEXT(uint program, int location, sizei bufSize, + float *params); + void GetUniformiv(uint program, int location, int *params); + void GetnUniformivEXT(uint program, int location, sizei bufSize, + int *params); + + return the value or values of the uniform at location + for program object in the array . Calling + GetnUniformfvEXT or GetnUniformivEXT ensures that no more than + bytes are written into . If the buffer size + required to fill all the requested data is greater than an + INVALID_OPERATION error is generated and is not altered. + ... + +Additions to The OpenGL ES Shading Language Specification, Version 1. + + Append to the third paragraph of section 4.1.9 "Arrays" + + If robust buffer access is enabled via the OpenGL ES API, such + indexing must not result in abnormal program termination. The + results are still undefined, but implementations are encouraged to + produce zero values for such accesses. + +Interactions with EGL_EXT_create_context_robustness + + If the EGL window-system binding API is used to create a context, + the EGL_EXT_create_context_robustness extension is supported, and + the attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to + EGL_TRUE when eglCreateContext is called, the resulting context will + perform robust buffer access as described above in section 2.8, and + the CONTEXT_ROBUST_ACCESS_EXT query will return GL_TRUE as described + above in section 6.1.5. + + If the EGL window-system binding API is used to create a context and + the EGL_EXT_create_context_robustness extension is supported, then + the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT + determines the reset notification behavior and the value of + RESET_NOTIFICATION_STRATEGY_EXT, as described in section 2.6. + +Errors + + ReadnPixelsEXT, GetnUniformfvEXT, and GetnUniformivEXT share all the + errors of their unsized buffer query counterparts with the addition + that INVALID_OPERATION is generated if the buffer size required to + fill all the requested data is greater than . + +New Implementation Dependent State + + Get Value Type Get Command Minimum Value Description Sec. Attribute + --------- ---- ----------- ------------- --------------------------- ----- --------- + CONTEXT_ROBUST_ACCESS_EXT B GetIntegerv - Robust access enabled 6.1.5 - + RESET_NOTIFICATION_STRATEGY_EXT Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 - + +Issues + + + 1. What should this extension be called? + + RESOLVED: EXT_robustness + + Since this is intended to be a version of ARB_robustness for + OpenGL ES, it should be named accordingly. + + 2. How does this extension differ from Desktop GL's ARB_robustness? + + RESOLVED: Because EGL_EXT_create_context_robustness uses a + separate attribute to enable robust buffer access, a + corresponding query is added here. + + 3. Should we provide a context creation mechanism to enable this extension? + + RESOLVED. Yes. + + Currently, EGL_EXT_create_context_robustness provides this + mechanism via two unique attributes. These attributes differ + from those specified by KHR_create_context to allow for + differences in what functionality those attributes define. + + 4. What can cause a graphics reset? + + Either user or implementor errors may result in a graphics reset. + If the application attempts to perform a rendering that takes too long + whether due to an infinite loop in a shader or even just a rendering + operation that takes too long on the given hardware. Implementation + errors may produce badly formed hardware commands. Memory access errors + may result from user or implementor mistakes. On some systems, power + management events such as system sleep, screen saver activation, or + pre-emption may also context resets to occur. Any of these events may + result in a graphics reset event that will be detectable by the + mechanism described in this extension. + + 5. How should the application react to a reset context event? + + RESOLVED: For this extension, the application is expected to query + the reset status until NO_ERROR is returned. If a reset is encountered, + at least one *RESET* status will be returned. Once NO_ERROR is again + encountered, the application can safely destroy the old context and + create a new one. + + After a reset event, apps should not use a context for any purpose + other than determining its reset status, and then destroying it. If a + context receives a reset event, all other contexts in its share group + will also receive reset events, and should be destroyed and + recreated. + + Apps should be cautious in interpreting the GUILTY and INNOCENT reset + statuses. These are guidelines to the immediate cause of a reset, but + not guarantees of the ultimate cause. + + 6. If a graphics reset occurs in a shared context, what happens in + shared contexts? + + RESOLVED: A reset in one context will result in a reset in all other + contexts in its share group. + + 7. How can an application query for robust buffer access support, + since this is now determined at context creation time? + + RESOLVED. The application can query the value of ROBUST_ACCESS_EXT + using GetIntegerv. If true, this functionality is enabled. + + 8. How is the reset notification behavior controlled? + + RESOLVED: Reset notification behavior is determined at context + creation time using EGL/GLX/WGL/etc. mechanisms. In order that shared + objects be handled predictably, a context cannot share with + another context unless both have the same reset notification + behavior. + + +Revision History + + Rev. Date Author Changes + ---- ------------ --------- ---------------------------------------- + 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a + companion to rather than subset of KHR_create_context + 2 11 Oct 2011 groth Merged ANGLE and NV extensions. + Convert to using flag to indicate robust access. + 1 15 July 2011 groth Initial version