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