The Tor Browser / file revision

 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