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