1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/angle/extensions/EXT_robustness.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,365 @@
1.4 +Name
1.5 +
1.6 + EXT_robustness
1.7 +
1.8 +Name Strings
1.9 +
1.10 + GL_EXT_robustness
1.11 +
1.12 +Contributors
1.13 +
1.14 + Daniel Koch, TransGaming
1.15 + Nicolas Capens, TransGaming
1.16 + Contributors to ARB_robustness
1.17 +
1.18 +Contact
1.19 +
1.20 + Greg Roth, NVIDIA (groth 'at' nvidia.com)
1.21 +
1.22 +Status
1.23 +
1.24 + Complete.
1.25 +
1.26 +Version
1.27 +
1.28 + Version 3, 2011/10/31
1.29 +
1.30 +Number
1.31 +
1.32 + OpenGL ES Extension #107
1.33 +
1.34 +Dependencies
1.35 +
1.36 + This extension is written against the OpenGL ES 2.0 Specification
1.37 + but can apply to OpenGL ES 1.1 and up.
1.38 +
1.39 + EGL_EXT_create_context_robustness is used to determine if a context
1.40 + implementing this extension supports robust buffer access, and if it
1.41 + supports reset notification.
1.42 +
1.43 +Overview
1.44 +
1.45 + Several recent trends in how OpenGL integrates into modern computer
1.46 + systems have created new requirements for robustness and security
1.47 + for OpenGL rendering contexts.
1.48 +
1.49 + Additionally GPU architectures now support hardware fault detection;
1.50 + for example, video memory supporting ECC (error correcting codes)
1.51 + and error detection. OpenGL contexts should be capable of recovering
1.52 + from hardware faults such as uncorrectable memory errors. Along with
1.53 + recovery from such hardware faults, the recovery mechanism can
1.54 + also allow recovery from video memory access exceptions and system
1.55 + software failures. System software failures can be due to device
1.56 + changes or driver failures.
1.57 +
1.58 + OpenGL queries that that return (write) some number of bytes to a
1.59 + buffer indicated by a pointer parameter introduce risk of buffer
1.60 + overflows that might be exploitable by malware. To address this,
1.61 + queries with return value sizes that are not expressed directly by
1.62 + the parameters to the query itself are given additional API
1.63 + functions with an additional parameter that specifies the number of
1.64 + bytes in the buffer and never writing bytes beyond that limit. This
1.65 + is particularly useful for multi-threaded usage of OpenGL contexts
1.66 + in a "share group" where one context can change objects in ways that
1.67 + can cause buffer overflows for another context's OpenGL queries.
1.68 +
1.69 + The original ARB_vertex_buffer_object extension includes an issue
1.70 + that explicitly states program termination is allowed when
1.71 + out-of-bounds vertex buffer object fetches occur. Modern graphics
1.72 + hardware is capable well-defined behavior in the case of out-of-
1.73 + bounds vertex buffer object fetches. Older hardware may require
1.74 + extra checks to enforce well-defined (and termination free)
1.75 + behavior, but this expense is warranted when processing potentially
1.76 + untrusted content.
1.77 +
1.78 + The intent of this extension is to address some specific robustness
1.79 + goals:
1.80 +
1.81 + * For all existing OpenGL queries, provide additional "safe" APIs
1.82 + that limit data written to user pointers to a buffer size in
1.83 + bytes that is an explicit additional parameter of the query.
1.84 +
1.85 + * Provide a mechanism for an OpenGL application to learn about
1.86 + graphics resets that affect the context. When a graphics reset
1.87 + occurs, the OpenGL context becomes unusable and the application
1.88 + must create a new context to continue operation. Detecting a
1.89 + graphics reset happens through an inexpensive query.
1.90 +
1.91 + * Provide an enable to guarantee that out-of-bounds buffer object
1.92 + accesses by the GPU will have deterministic behavior and preclude
1.93 + application instability or termination due to an incorrect buffer
1.94 + access. Such accesses include vertex buffer fetches of
1.95 + attributes and indices, and indexed reads of uniforms or
1.96 + parameters from buffers.
1.97 +
1.98 +New Procedures and Functions
1.99 +
1.100 + enum GetGraphicsResetStatusEXT();
1.101 +
1.102 + void ReadnPixelsEXT(int x, int y, sizei width, sizei height,
1.103 + enum format, enum type, sizei bufSize,
1.104 + void *data);
1.105 +
1.106 + void GetnUniformfvEXT(uint program, int location, sizei bufSize,
1.107 + float *params);
1.108 + void GetnUniformivEXT(uint program, int location, sizei bufSize,
1.109 + int *params);
1.110 +
1.111 +New Tokens
1.112 +
1.113 + Returned by GetGraphicsResetStatusEXT:
1.114 +
1.115 + NO_ERROR 0x0000
1.116 + GUILTY_CONTEXT_RESET_EXT 0x8253
1.117 + INNOCENT_CONTEXT_RESET_EXT 0x8254
1.118 + UNKNOWN_CONTEXT_RESET_EXT 0x8255
1.119 +
1.120 + Accepted by the <value> parameter of GetBooleanv, GetIntegerv,
1.121 + and GetFloatv:
1.122 +
1.123 + CONTEXT_ROBUST_ACCESS_EXT 0x90F3
1.124 + RESET_NOTIFICATION_STRATEGY_EXT 0x8256
1.125 +
1.126 + Returned by GetIntegerv and related simple queries when <value> is
1.127 + RESET_NOTIFICATION_STRATEGY_EXT :
1.128 +
1.129 + LOSE_CONTEXT_ON_RESET_EXT 0x8252
1.130 + NO_RESET_NOTIFICATION_EXT 0x8261
1.131 +
1.132 +Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation)
1.133 +
1.134 +Add a new subsection after 2.5 "GL Errors" and renumber subsequent
1.135 +sections accordingly.
1.136 +
1.137 + 2.6 "Graphics Reset Recovery"
1.138 +
1.139 + Certain events can result in a reset of the GL context. Such a reset
1.140 + causes all context state to be lost. Recovery from such events
1.141 + requires recreation of all objects in the affected context. The
1.142 + current status of the graphics reset state is returned by
1.143 +
1.144 + enum GetGraphicsResetStatusEXT();
1.145 +
1.146 + The symbolic constant returned indicates if the GL context has been
1.147 + in a reset state at any point since the last call to
1.148 + GetGraphicsResetStatusEXT. NO_ERROR indicates that the GL context
1.149 + has not been in a reset state since the last call.
1.150 + GUILTY_CONTEXT_RESET_EXT indicates that a reset has been detected
1.151 + that is attributable to the current GL context.
1.152 + INNOCENT_CONTEXT_RESET_EXT indicates a reset has been detected that
1.153 + is not attributable to the current GL context.
1.154 + UNKNOWN_CONTEXT_RESET_EXT indicates a detected graphics reset whose
1.155 + cause is unknown.
1.156 +
1.157 + If a reset status other than NO_ERROR is returned and subsequent
1.158 + calls return NO_ERROR, the context reset was encountered and
1.159 + completed. If a reset status is repeatedly returned, the context may
1.160 + be in the process of resetting.
1.161 +
1.162 + Reset notification behavior is determined at context creation time,
1.163 + and may be queried by calling GetIntegerv with the symbolic constant
1.164 + RESET_NOTIFICATION_STRATEGY_EXT.
1.165 +
1.166 + If the reset notification behavior is NO_RESET_NOTIFICATION_EXT,
1.167 + then the implementation will never deliver notification of reset
1.168 + events, and GetGraphicsResetStatusEXT will always return
1.169 + NO_ERROR[fn1].
1.170 + [fn1: In this case it is recommended that implementations should
1.171 + not allow loss of context state no matter what events occur.
1.172 + However, this is only a recommendation, and cannot be relied
1.173 + upon by applications.]
1.174 +
1.175 + If the behavior is LOSE_CONTEXT_ON_RESET_EXT, a graphics reset will
1.176 + result in the loss of all context state, requiring the recreation of
1.177 + all associated objects. In this case GetGraphicsResetStatusEXT may
1.178 + return any of the values described above.
1.179 +
1.180 + If a graphics reset notification occurs in a context, a notification
1.181 + must also occur in all other contexts which share objects with that
1.182 + context[fn2].
1.183 + [fn2: The values returned by GetGraphicsResetStatusEXT in the
1.184 + different contexts may differ.]
1.185 +
1.186 + Add to Section 2.8 "Vertex Arrays" before subsection "Transferring
1.187 + Array Elements"
1.188 +
1.189 + Robust buffer access is enabled by creating a context with robust
1.190 + access enabled through the window system binding APIs. When enabled,
1.191 + indices within the vertex array that lie outside the arrays defined
1.192 + for enabled attributes result in undefined values for the
1.193 + corresponding attributes, but cannot result in application failure.
1.194 + Robust buffer access behavior may be queried by calling GetIntegerv
1.195 + with the symbolic constant CONTEXT_ROBUST_ACCESS_EXT.
1.196 +
1.197 +Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
1.198 +Operations and the Frame Buffer)
1.199 +
1.200 + Modify section 4.3.1 "Reading Pixels"
1.201 +
1.202 + Pixels are read using
1.203 +
1.204 + void ReadPixels(int x, int y, sizei width, sizei height,
1.205 + enum format, enum type, void *data);
1.206 + void ReadnPixelsEXT(int x, int y, sizei width, sizei height,
1.207 + enum format, enum type, sizei bufSize,
1.208 + void *data);
1.209 +
1.210 + Add to the description of ReadPixels:
1.211 +
1.212 + ReadnPixelsEXT behaves identically to ReadPixels except that it does
1.213 + not write more than <bufSize> bytes into <data>. If the buffer size
1.214 + required to fill all the requested data is greater than <bufSize> an
1.215 + INVALID_OPERATION error is generated and <data> is not altered.
1.216 +
1.217 +Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special
1.218 +Functions):
1.219 +
1.220 + None
1.221 +
1.222 +Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and
1.223 +State Requests)
1.224 +
1.225 + Modify Section 6.1.8 "Shader and Program Queries"
1.226 +
1.227 + The commands
1.228 +
1.229 + void GetUniformfv(uint program, int location, float *params);
1.230 + void GetnUniformfvEXT(uint program, int location, sizei bufSize,
1.231 + float *params);
1.232 + void GetUniformiv(uint program, int location, int *params);
1.233 + void GetnUniformivEXT(uint program, int location, sizei bufSize,
1.234 + int *params);
1.235 +
1.236 + return the value or values of the uniform at location <location>
1.237 + for program object <program> in the array <params>. Calling
1.238 + GetnUniformfvEXT or GetnUniformivEXT ensures that no more than
1.239 + <bufSize> bytes are written into <params>. If the buffer size
1.240 + required to fill all the requested data is greater than <bufSize> an
1.241 + INVALID_OPERATION error is generated and <params> is not altered.
1.242 + ...
1.243 +
1.244 +Additions to The OpenGL ES Shading Language Specification, Version 1.
1.245 +
1.246 + Append to the third paragraph of section 4.1.9 "Arrays"
1.247 +
1.248 + If robust buffer access is enabled via the OpenGL ES API, such
1.249 + indexing must not result in abnormal program termination. The
1.250 + results are still undefined, but implementations are encouraged to
1.251 + produce zero values for such accesses.
1.252 +
1.253 +Interactions with EGL_EXT_create_context_robustness
1.254 +
1.255 + If the EGL window-system binding API is used to create a context,
1.256 + the EGL_EXT_create_context_robustness extension is supported, and
1.257 + the attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to
1.258 + EGL_TRUE when eglCreateContext is called, the resulting context will
1.259 + perform robust buffer access as described above in section 2.8, and
1.260 + the CONTEXT_ROBUST_ACCESS_EXT query will return GL_TRUE as described
1.261 + above in section 6.1.5.
1.262 +
1.263 + If the EGL window-system binding API is used to create a context and
1.264 + the EGL_EXT_create_context_robustness extension is supported, then
1.265 + the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT
1.266 + determines the reset notification behavior and the value of
1.267 + RESET_NOTIFICATION_STRATEGY_EXT, as described in section 2.6.
1.268 +
1.269 +Errors
1.270 +
1.271 + ReadnPixelsEXT, GetnUniformfvEXT, and GetnUniformivEXT share all the
1.272 + errors of their unsized buffer query counterparts with the addition
1.273 + that INVALID_OPERATION is generated if the buffer size required to
1.274 + fill all the requested data is greater than <bufSize>.
1.275 +
1.276 +New Implementation Dependent State
1.277 +
1.278 + Get Value Type Get Command Minimum Value Description Sec. Attribute
1.279 + --------- ---- ----------- ------------- --------------------------- ----- ---------
1.280 + CONTEXT_ROBUST_ACCESS_EXT B GetIntegerv - Robust access enabled 6.1.5 -
1.281 + RESET_NOTIFICATION_STRATEGY_EXT Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 -
1.282 +
1.283 +Issues
1.284 +
1.285 +
1.286 + 1. What should this extension be called?
1.287 +
1.288 + RESOLVED: EXT_robustness
1.289 +
1.290 + Since this is intended to be a version of ARB_robustness for
1.291 + OpenGL ES, it should be named accordingly.
1.292 +
1.293 + 2. How does this extension differ from Desktop GL's ARB_robustness?
1.294 +
1.295 + RESOLVED: Because EGL_EXT_create_context_robustness uses a
1.296 + separate attribute to enable robust buffer access, a
1.297 + corresponding query is added here.
1.298 +
1.299 + 3. Should we provide a context creation mechanism to enable this extension?
1.300 +
1.301 + RESOLVED. Yes.
1.302 +
1.303 + Currently, EGL_EXT_create_context_robustness provides this
1.304 + mechanism via two unique attributes. These attributes differ
1.305 + from those specified by KHR_create_context to allow for
1.306 + differences in what functionality those attributes define.
1.307 +
1.308 + 4. What can cause a graphics reset?
1.309 +
1.310 + Either user or implementor errors may result in a graphics reset.
1.311 + If the application attempts to perform a rendering that takes too long
1.312 + whether due to an infinite loop in a shader or even just a rendering
1.313 + operation that takes too long on the given hardware. Implementation
1.314 + errors may produce badly formed hardware commands. Memory access errors
1.315 + may result from user or implementor mistakes. On some systems, power
1.316 + management events such as system sleep, screen saver activation, or
1.317 + pre-emption may also context resets to occur. Any of these events may
1.318 + result in a graphics reset event that will be detectable by the
1.319 + mechanism described in this extension.
1.320 +
1.321 + 5. How should the application react to a reset context event?
1.322 +
1.323 + RESOLVED: For this extension, the application is expected to query
1.324 + the reset status until NO_ERROR is returned. If a reset is encountered,
1.325 + at least one *RESET* status will be returned. Once NO_ERROR is again
1.326 + encountered, the application can safely destroy the old context and
1.327 + create a new one.
1.328 +
1.329 + After a reset event, apps should not use a context for any purpose
1.330 + other than determining its reset status, and then destroying it. If a
1.331 + context receives a reset event, all other contexts in its share group
1.332 + will also receive reset events, and should be destroyed and
1.333 + recreated.
1.334 +
1.335 + Apps should be cautious in interpreting the GUILTY and INNOCENT reset
1.336 + statuses. These are guidelines to the immediate cause of a reset, but
1.337 + not guarantees of the ultimate cause.
1.338 +
1.339 + 6. If a graphics reset occurs in a shared context, what happens in
1.340 + shared contexts?
1.341 +
1.342 + RESOLVED: A reset in one context will result in a reset in all other
1.343 + contexts in its share group.
1.344 +
1.345 + 7. How can an application query for robust buffer access support,
1.346 + since this is now determined at context creation time?
1.347 +
1.348 + RESOLVED. The application can query the value of ROBUST_ACCESS_EXT
1.349 + using GetIntegerv. If true, this functionality is enabled.
1.350 +
1.351 + 8. How is the reset notification behavior controlled?
1.352 +
1.353 + RESOLVED: Reset notification behavior is determined at context
1.354 + creation time using EGL/GLX/WGL/etc. mechanisms. In order that shared
1.355 + objects be handled predictably, a context cannot share with
1.356 + another context unless both have the same reset notification
1.357 + behavior.
1.358 +
1.359 +
1.360 +Revision History
1.361 +
1.362 + Rev. Date Author Changes
1.363 + ---- ------------ --------- ----------------------------------------
1.364 + 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a
1.365 + companion to rather than subset of KHR_create_context
1.366 + 2 11 Oct 2011 groth Merged ANGLE and NV extensions.
1.367 + Convert to using flag to indicate robust access.
1.368 + 1 15 July 2011 groth Initial version
