Edit
kc3-lang/angle/extensions/EXT_robustness.txt
daniel@transgaming.com
- extensions/EXT_robustness.txt
-
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 <value> parameter of GetBooleanv, GetIntegerv, and GetFloatv: CONTEXT_ROBUST_ACCESS_EXT 0x90F3 RESET_NOTIFICATION_STRATEGY_EXT 0x8256 Returned by GetIntegerv and related simple queries when <value> 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 <bufSize> bytes into <data>. If the buffer size required to fill all the requested data is greater than <bufSize> an INVALID_OPERATION error is generated and <data> 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 <location> for program object <program> in the array <params>. Calling GetnUniformfvEXT or GetnUniformivEXT ensures that no more than <bufSize> bytes are written into <params>. If the buffer size required to fill all the requested data is greater than <bufSize> an INVALID_OPERATION error is generated and <params> 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 <bufSize>. 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