The Tor Browser: gfx/angle/extensions/EXT_robustness.txt@6474c204b198 (annotated)

gfx/angle/extensions/EXT_robustness.txt@6474c204b198 (annotated)

gfx/angle/extensions/EXT_robustness.txt

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 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.
 .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
 .  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.
 .  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.
 .  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.
 . 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.
 . 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.
 . 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.
 . 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.
 . 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
     ----  ------------ ---------  ----------------------------------------
 31 Oct  2011 groth      Reverted to attribute for robust access. Now it's a
                                   companion to rather than subset of KHR_create_context
 11 Oct  2011 groth      Merged ANGLE and NV extensions.
                                   Convert to using flag to indicate robust access.
 15 July 2011 groth      Initial version

The Tor Browser / annotate

gfx/angle/extensions/EXT_robustness.txt@6474c204b198 (annotated)

gfx/angle/extensions/EXT_robustness.txt