daniel@transgaming.com | 5933c44 | 2011-11-12 04:44:03 +0000 | [diff] [blame] | 1 | Name |
| 2 | |
| 3 | EXT_robustness |
| 4 | |
| 5 | Name Strings |
| 6 | |
| 7 | GL_EXT_robustness |
| 8 | |
| 9 | Contributors |
| 10 | |
| 11 | Daniel Koch, TransGaming |
| 12 | Nicolas Capens, TransGaming |
| 13 | Contributors to ARB_robustness |
| 14 | |
| 15 | Contact |
| 16 | |
| 17 | Greg Roth, NVIDIA (groth 'at' nvidia.com) |
| 18 | |
| 19 | Status |
| 20 | |
| 21 | Complete. |
| 22 | |
| 23 | Version |
| 24 | |
| 25 | Version 3, 2011/10/31 |
| 26 | |
| 27 | Number |
| 28 | |
daniel@transgaming.com | 5569383 | 2012-01-17 14:28:13 +0000 | [diff] [blame] | 29 | OpenGL ES Extension #107 |
daniel@transgaming.com | 5933c44 | 2011-11-12 04:44:03 +0000 | [diff] [blame] | 30 | |
| 31 | Dependencies |
| 32 | |
| 33 | This extension is written against the OpenGL ES 2.0 Specification |
| 34 | but can apply to OpenGL ES 1.1 and up. |
| 35 | |
| 36 | EGL_EXT_create_context_robustness is used to determine if a context |
| 37 | implementing this extension supports robust buffer access, and if it |
| 38 | supports reset notification. |
| 39 | |
| 40 | Overview |
| 41 | |
| 42 | Several recent trends in how OpenGL integrates into modern computer |
| 43 | systems have created new requirements for robustness and security |
| 44 | for OpenGL rendering contexts. |
| 45 | |
| 46 | Additionally GPU architectures now support hardware fault detection; |
| 47 | for example, video memory supporting ECC (error correcting codes) |
| 48 | and error detection. OpenGL contexts should be capable of recovering |
| 49 | from hardware faults such as uncorrectable memory errors. Along with |
| 50 | recovery from such hardware faults, the recovery mechanism can |
| 51 | also allow recovery from video memory access exceptions and system |
| 52 | software failures. System software failures can be due to device |
| 53 | changes or driver failures. |
| 54 | |
| 55 | OpenGL queries that that return (write) some number of bytes to a |
| 56 | buffer indicated by a pointer parameter introduce risk of buffer |
| 57 | overflows that might be exploitable by malware. To address this, |
| 58 | queries with return value sizes that are not expressed directly by |
| 59 | the parameters to the query itself are given additional API |
| 60 | functions with an additional parameter that specifies the number of |
| 61 | bytes in the buffer and never writing bytes beyond that limit. This |
| 62 | is particularly useful for multi-threaded usage of OpenGL contexts |
| 63 | in a "share group" where one context can change objects in ways that |
| 64 | can cause buffer overflows for another context's OpenGL queries. |
| 65 | |
| 66 | The original ARB_vertex_buffer_object extension includes an issue |
| 67 | that explicitly states program termination is allowed when |
| 68 | out-of-bounds vertex buffer object fetches occur. Modern graphics |
| 69 | hardware is capable well-defined behavior in the case of out-of- |
| 70 | bounds vertex buffer object fetches. Older hardware may require |
| 71 | extra checks to enforce well-defined (and termination free) |
| 72 | behavior, but this expense is warranted when processing potentially |
| 73 | untrusted content. |
| 74 | |
| 75 | The intent of this extension is to address some specific robustness |
| 76 | goals: |
| 77 | |
| 78 | * For all existing OpenGL queries, provide additional "safe" APIs |
| 79 | that limit data written to user pointers to a buffer size in |
| 80 | bytes that is an explicit additional parameter of the query. |
| 81 | |
| 82 | * Provide a mechanism for an OpenGL application to learn about |
| 83 | graphics resets that affect the context. When a graphics reset |
| 84 | occurs, the OpenGL context becomes unusable and the application |
| 85 | must create a new context to continue operation. Detecting a |
| 86 | graphics reset happens through an inexpensive query. |
| 87 | |
| 88 | * Provide an enable to guarantee that out-of-bounds buffer object |
| 89 | accesses by the GPU will have deterministic behavior and preclude |
| 90 | application instability or termination due to an incorrect buffer |
| 91 | access. Such accesses include vertex buffer fetches of |
| 92 | attributes and indices, and indexed reads of uniforms or |
| 93 | parameters from buffers. |
| 94 | |
| 95 | New Procedures and Functions |
| 96 | |
| 97 | enum GetGraphicsResetStatusEXT(); |
| 98 | |
| 99 | void ReadnPixelsEXT(int x, int y, sizei width, sizei height, |
| 100 | enum format, enum type, sizei bufSize, |
| 101 | void *data); |
| 102 | |
| 103 | void GetnUniformfvEXT(uint program, int location, sizei bufSize, |
| 104 | float *params); |
| 105 | void GetnUniformivEXT(uint program, int location, sizei bufSize, |
| 106 | int *params); |
| 107 | |
| 108 | New Tokens |
| 109 | |
| 110 | Returned by GetGraphicsResetStatusEXT: |
| 111 | |
| 112 | NO_ERROR 0x0000 |
| 113 | GUILTY_CONTEXT_RESET_EXT 0x8253 |
| 114 | INNOCENT_CONTEXT_RESET_EXT 0x8254 |
| 115 | UNKNOWN_CONTEXT_RESET_EXT 0x8255 |
| 116 | |
| 117 | Accepted by the <value> parameter of GetBooleanv, GetIntegerv, |
| 118 | and GetFloatv: |
| 119 | |
| 120 | CONTEXT_ROBUST_ACCESS_EXT 0x90F3 |
| 121 | RESET_NOTIFICATION_STRATEGY_EXT 0x8256 |
| 122 | |
| 123 | Returned by GetIntegerv and related simple queries when <value> is |
| 124 | RESET_NOTIFICATION_STRATEGY_EXT : |
| 125 | |
| 126 | LOSE_CONTEXT_ON_RESET_EXT 0x8252 |
| 127 | NO_RESET_NOTIFICATION_EXT 0x8261 |
| 128 | |
| 129 | Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) |
| 130 | |
| 131 | Add a new subsection after 2.5 "GL Errors" and renumber subsequent |
| 132 | sections accordingly. |
| 133 | |
| 134 | 2.6 "Graphics Reset Recovery" |
| 135 | |
| 136 | Certain events can result in a reset of the GL context. Such a reset |
| 137 | causes all context state to be lost. Recovery from such events |
| 138 | requires recreation of all objects in the affected context. The |
| 139 | current status of the graphics reset state is returned by |
| 140 | |
| 141 | enum GetGraphicsResetStatusEXT(); |
| 142 | |
| 143 | The symbolic constant returned indicates if the GL context has been |
| 144 | in a reset state at any point since the last call to |
| 145 | GetGraphicsResetStatusEXT. NO_ERROR indicates that the GL context |
| 146 | has not been in a reset state since the last call. |
| 147 | GUILTY_CONTEXT_RESET_EXT indicates that a reset has been detected |
| 148 | that is attributable to the current GL context. |
| 149 | INNOCENT_CONTEXT_RESET_EXT indicates a reset has been detected that |
| 150 | is not attributable to the current GL context. |
| 151 | UNKNOWN_CONTEXT_RESET_EXT indicates a detected graphics reset whose |
| 152 | cause is unknown. |
| 153 | |
| 154 | If a reset status other than NO_ERROR is returned and subsequent |
| 155 | calls return NO_ERROR, the context reset was encountered and |
| 156 | completed. If a reset status is repeatedly returned, the context may |
| 157 | be in the process of resetting. |
| 158 | |
| 159 | Reset notification behavior is determined at context creation time, |
| 160 | and may be queried by calling GetIntegerv with the symbolic constant |
| 161 | RESET_NOTIFICATION_STRATEGY_EXT. |
| 162 | |
| 163 | If the reset notification behavior is NO_RESET_NOTIFICATION_EXT, |
| 164 | then the implementation will never deliver notification of reset |
| 165 | events, and GetGraphicsResetStatusEXT will always return |
| 166 | NO_ERROR[fn1]. |
| 167 | [fn1: In this case it is recommended that implementations should |
| 168 | not allow loss of context state no matter what events occur. |
| 169 | However, this is only a recommendation, and cannot be relied |
| 170 | upon by applications.] |
| 171 | |
| 172 | If the behavior is LOSE_CONTEXT_ON_RESET_EXT, a graphics reset will |
| 173 | result in the loss of all context state, requiring the recreation of |
| 174 | all associated objects. In this case GetGraphicsResetStatusEXT may |
| 175 | return any of the values described above. |
| 176 | |
| 177 | If a graphics reset notification occurs in a context, a notification |
| 178 | must also occur in all other contexts which share objects with that |
| 179 | context[fn2]. |
| 180 | [fn2: The values returned by GetGraphicsResetStatusEXT in the |
| 181 | different contexts may differ.] |
| 182 | |
| 183 | Add to Section 2.8 "Vertex Arrays" before subsection "Transferring |
| 184 | Array Elements" |
| 185 | |
| 186 | Robust buffer access is enabled by creating a context with robust |
| 187 | access enabled through the window system binding APIs. When enabled, |
| 188 | indices within the vertex array that lie outside the arrays defined |
| 189 | for enabled attributes result in undefined values for the |
| 190 | corresponding attributes, but cannot result in application failure. |
| 191 | Robust buffer access behavior may be queried by calling GetIntegerv |
| 192 | with the symbolic constant CONTEXT_ROBUST_ACCESS_EXT. |
| 193 | |
| 194 | Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment |
| 195 | Operations and the Frame Buffer) |
| 196 | |
| 197 | Modify section 4.3.1 "Reading Pixels" |
| 198 | |
| 199 | Pixels are read using |
| 200 | |
| 201 | void ReadPixels(int x, int y, sizei width, sizei height, |
| 202 | enum format, enum type, void *data); |
| 203 | void ReadnPixelsEXT(int x, int y, sizei width, sizei height, |
| 204 | enum format, enum type, sizei bufSize, |
| 205 | void *data); |
| 206 | |
| 207 | Add to the description of ReadPixels: |
| 208 | |
| 209 | ReadnPixelsEXT behaves identically to ReadPixels except that it does |
| 210 | not write more than <bufSize> bytes into <data>. If the buffer size |
| 211 | required to fill all the requested data is greater than <bufSize> an |
| 212 | INVALID_OPERATION error is generated and <data> is not altered. |
| 213 | |
| 214 | Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special |
| 215 | Functions): |
| 216 | |
| 217 | None |
| 218 | |
| 219 | Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and |
| 220 | State Requests) |
| 221 | |
| 222 | Modify Section 6.1.8 "Shader and Program Queries" |
| 223 | |
| 224 | The commands |
| 225 | |
| 226 | void GetUniformfv(uint program, int location, float *params); |
| 227 | void GetnUniformfvEXT(uint program, int location, sizei bufSize, |
| 228 | float *params); |
| 229 | void GetUniformiv(uint program, int location, int *params); |
| 230 | void GetnUniformivEXT(uint program, int location, sizei bufSize, |
| 231 | int *params); |
| 232 | |
| 233 | return the value or values of the uniform at location <location> |
| 234 | for program object <program> in the array <params>. Calling |
| 235 | GetnUniformfvEXT or GetnUniformivEXT ensures that no more than |
| 236 | <bufSize> bytes are written into <params>. If the buffer size |
| 237 | required to fill all the requested data is greater than <bufSize> an |
| 238 | INVALID_OPERATION error is generated and <params> is not altered. |
| 239 | ... |
| 240 | |
| 241 | Additions to The OpenGL ES Shading Language Specification, Version 1. |
| 242 | |
| 243 | Append to the third paragraph of section 4.1.9 "Arrays" |
| 244 | |
| 245 | If robust buffer access is enabled via the OpenGL ES API, such |
| 246 | indexing must not result in abnormal program termination. The |
| 247 | results are still undefined, but implementations are encouraged to |
| 248 | produce zero values for such accesses. |
| 249 | |
| 250 | Interactions with EGL_EXT_create_context_robustness |
| 251 | |
| 252 | If the EGL window-system binding API is used to create a context, |
| 253 | the EGL_EXT_create_context_robustness extension is supported, and |
| 254 | the attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to |
| 255 | EGL_TRUE when eglCreateContext is called, the resulting context will |
| 256 | perform robust buffer access as described above in section 2.8, and |
| 257 | the CONTEXT_ROBUST_ACCESS_EXT query will return GL_TRUE as described |
| 258 | above in section 6.1.5. |
| 259 | |
| 260 | If the EGL window-system binding API is used to create a context and |
| 261 | the EGL_EXT_create_context_robustness extension is supported, then |
| 262 | the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT |
| 263 | determines the reset notification behavior and the value of |
| 264 | RESET_NOTIFICATION_STRATEGY_EXT, as described in section 2.6. |
| 265 | |
| 266 | Errors |
| 267 | |
| 268 | ReadnPixelsEXT, GetnUniformfvEXT, and GetnUniformivEXT share all the |
| 269 | errors of their unsized buffer query counterparts with the addition |
| 270 | that INVALID_OPERATION is generated if the buffer size required to |
| 271 | fill all the requested data is greater than <bufSize>. |
| 272 | |
| 273 | New Implementation Dependent State |
| 274 | |
| 275 | Get Value Type Get Command Minimum Value Description Sec. Attribute |
| 276 | --------- ---- ----------- ------------- --------------------------- ----- --------- |
| 277 | CONTEXT_ROBUST_ACCESS_EXT B GetIntegerv - Robust access enabled 6.1.5 - |
| 278 | RESET_NOTIFICATION_STRATEGY_EXT Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 - |
| 279 | |
| 280 | Issues |
| 281 | |
| 282 | |
| 283 | 1. What should this extension be called? |
| 284 | |
| 285 | RESOLVED: EXT_robustness |
| 286 | |
| 287 | Since this is intended to be a version of ARB_robustness for |
| 288 | OpenGL ES, it should be named accordingly. |
| 289 | |
| 290 | 2. How does this extension differ from Desktop GL's ARB_robustness? |
| 291 | |
| 292 | RESOLVED: Because EGL_EXT_create_context_robustness uses a |
| 293 | separate attribute to enable robust buffer access, a |
| 294 | corresponding query is added here. |
| 295 | |
| 296 | 3. Should we provide a context creation mechanism to enable this extension? |
| 297 | |
| 298 | RESOLVED. Yes. |
| 299 | |
| 300 | Currently, EGL_EXT_create_context_robustness provides this |
| 301 | mechanism via two unique attributes. These attributes differ |
| 302 | from those specified by KHR_create_context to allow for |
| 303 | differences in what functionality those attributes define. |
| 304 | |
| 305 | 4. What can cause a graphics reset? |
| 306 | |
| 307 | Either user or implementor errors may result in a graphics reset. |
| 308 | If the application attempts to perform a rendering that takes too long |
| 309 | whether due to an infinite loop in a shader or even just a rendering |
| 310 | operation that takes too long on the given hardware. Implementation |
| 311 | errors may produce badly formed hardware commands. Memory access errors |
| 312 | may result from user or implementor mistakes. On some systems, power |
| 313 | management events such as system sleep, screen saver activation, or |
| 314 | pre-emption may also context resets to occur. Any of these events may |
| 315 | result in a graphics reset event that will be detectable by the |
| 316 | mechanism described in this extension. |
| 317 | |
| 318 | 5. How should the application react to a reset context event? |
| 319 | |
| 320 | RESOLVED: For this extension, the application is expected to query |
| 321 | the reset status until NO_ERROR is returned. If a reset is encountered, |
| 322 | at least one *RESET* status will be returned. Once NO_ERROR is again |
| 323 | encountered, the application can safely destroy the old context and |
| 324 | create a new one. |
| 325 | |
| 326 | After a reset event, apps should not use a context for any purpose |
| 327 | other than determining its reset status, and then destroying it. If a |
| 328 | context receives a reset event, all other contexts in its share group |
| 329 | will also receive reset events, and should be destroyed and |
| 330 | recreated. |
| 331 | |
| 332 | Apps should be cautious in interpreting the GUILTY and INNOCENT reset |
| 333 | statuses. These are guidelines to the immediate cause of a reset, but |
| 334 | not guarantees of the ultimate cause. |
| 335 | |
| 336 | 6. If a graphics reset occurs in a shared context, what happens in |
| 337 | shared contexts? |
| 338 | |
| 339 | RESOLVED: A reset in one context will result in a reset in all other |
| 340 | contexts in its share group. |
| 341 | |
| 342 | 7. How can an application query for robust buffer access support, |
| 343 | since this is now determined at context creation time? |
| 344 | |
| 345 | RESOLVED. The application can query the value of ROBUST_ACCESS_EXT |
| 346 | using GetIntegerv. If true, this functionality is enabled. |
| 347 | |
| 348 | 8. How is the reset notification behavior controlled? |
| 349 | |
| 350 | RESOLVED: Reset notification behavior is determined at context |
| 351 | creation time using EGL/GLX/WGL/etc. mechanisms. In order that shared |
| 352 | objects be handled predictably, a context cannot share with |
| 353 | another context unless both have the same reset notification |
| 354 | behavior. |
| 355 | |
| 356 | |
| 357 | Revision History |
| 358 | |
| 359 | Rev. Date Author Changes |
| 360 | ---- ------------ --------- ---------------------------------------- |
| 361 | 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a |
| 362 | companion to rather than subset of KHR_create_context |
| 363 | 2 11 Oct 2011 groth Merged ANGLE and NV extensions. |
| 364 | Convert to using flag to indicate robust access. |
| 365 | 1 15 July 2011 groth Initial version |