extensions: Add EGL_EXT_device_persistent_id (#122)

* extensions: Add EGL_EXT_device_persistent_id

* EGL_EXT_device_persistent_id: Define error codes for eglQueryDeviceBinaryEXT.

Add a paragraph to eglQueryDeviceBinaryEXT to describe the error codes it can
generate.

* EGL_EXT_device_persistent_id: Change PROPOSED to RESOLVED for the issues section.

api/EGL/eglext.h

@@ -14,12 +14,12 @@ extern "C" {
 ** used to make the header, and the header can be found at
 **   http://www.khronos.org/registry/egl
 **
-** Khronos $Git commit SHA1: 5a9a7e3fcb $ on $Git commit date: 2020-08-24 11:05:32 -0700 $
+** Khronos $Git commit SHA1: 59522adade $ on $Git commit date: 2021-02-02 11:09:11 -0700 $
 */
 
 #include <EGL/eglplatform.h>
 
-#define EGL_EGLEXT_VERSION 20201001
+#define EGL_EGLEXT_VERSION 20210419
 
 /* Generated C header for:
  * API: egl
@@ -578,7 +578,7 @@ EGLAPI EGLBoolean EGLAPIENTRY eglQuerySurfacePointerANGLE (EGLDisplay dpy, EGLSu
 #define EGL_ANGLE_sync_control_rate 1
 typedef EGLBoolean (EGLAPIENTRYP PFNEGLGETMSCRATEANGLEPROC) (EGLDisplay dpy, EGLSurface surface, EGLint *numerator, EGLint *denominator);
 #ifdef EGL_EGLEXT_PROTOTYPES
-EGLAPI EGLBoolean EGLAPIENTRY eglGetMscRateANGLE(EGLDisplay dpy, EGLSurface surface, EGLint *numerator, EGLint *denominator);
+EGLAPI EGLBoolean EGLAPIENTRY eglGetMscRateANGLE (EGLDisplay dpy, EGLSurface surface, EGLint *numerator, EGLint *denominator);
 #endif
 #endif /* EGL_ANGLE_sync_control_rate */
 
@@ -692,6 +692,13 @@ EGLAPI EGLBoolean EGLAPIENTRY eglQueryDisplayAttribEXT (EGLDisplay dpy, EGLint a
 #define EGL_OPENWF_DEVICE_ID_EXT          0x3237
 #endif /* EGL_EXT_device_openwf */
 
+#ifndef EGL_EXT_device_persistent_id
+#define EGL_EXT_device_persistent_id 1
+#define EGL_DEVICE_UUID_EXT               0x335C
+#define EGL_DRIVER_UUID_EXT               0x335D
+#define EGL_DRIVER_NAME_EXT               0x335E
+#endif /* EGL_EXT_device_persistent_id */
+
 #ifndef EGL_EXT_device_query
 #define EGL_EXT_device_query 1
 #endif /* EGL_EXT_device_query */

api/egl.xml

@@ -853,7 +853,10 @@
         <enum value="0x3352" name="EGL_TRACK_REFERENCES_KHR"/>
             <unused start="0x3353" end="0x3356"/>
         <enum value="0x3357" name="EGL_CONTEXT_PRIORITY_REALTIME_NV"/>
-            <unused start="0x3358" end="0x335E"/>
+            <unused start="0x3358" end="0x335B"/>
+        <enum value="0x335C" name="EGL_DEVICE_UUID_EXT"/>
+        <enum value="0x335D" name="EGL_DRIVER_UUID_EXT"/>
+        <enum value="0x335E" name="EGL_DRIVER_NAME_EXT"/>
         <enum value="0x335F" name="EGL_RENDERER_EXT"/>
         <enum value="0x3360" name="EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT"/>
         <enum value="0x3361" name="EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT"/>
@@ -3417,5 +3420,12 @@
                 <enum name="EGL_RENDERER_EXT"/>
             </require>
         </extension>
+        <extension name="EGL_EXT_device_persistent_id" supported="egl">
+            <require>
+                <enum name="EGL_DEVICE_UUID_EXT"/>
+                <enum name="EGL_DRIVER_UUID_EXT"/>
+                <enum name="EGL_DRIVER_NAME_EXT"/>
+            </require>
+        </extension>
     </extensions>
 </registry>

extensions/EXT/EGL_EXT_device_persistent_id.txt

@@ -0,0 +1,202 @@
+Name
+
+    EXT_device_persistent_id
+
+Name Strings
+
+    EGL_EXT_device_persistent_id
+
+Contributors
+
+    Kyle Brenneman,  NVIDIA  (kbrenneman 'at' nvidia.com)
+
+Contact
+
+    Kyle Brenneman,  NVIDIA  (kbrenneman 'at' nvidia.com)
+
+Version
+
+    Version 1 - April 19, 2021
+
+Number
+
+    EGL Extension #142
+
+Extension Type
+
+    EGL device extension
+
+Dependencies
+
+    Written based on the wording of the EGL 1.5 specification.
+
+    EGL_EXT_device_query is required.
+
+Overview
+
+    Applications can query a list of EGLDeviceEXT handles, but those
+    handles are only valid within the process that queried them. An
+    application has no way, for example, to record its selection and
+    select the same device when run again later.
+
+    This extension provides a vendor name and a set of UUID's, which
+    provide a unique, persistent identifier for EGLDeviceEXT handles.
+    This allows applications to find the EGLDeviceEXT for the same
+    device across multiple processes, and across multiple APIs.
+
+New Procedures and Functions
+
+    EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
+                                      EGLint name,
+                                      EGLint max_size,
+                                      void *value,
+                                      EGLint *size);
+
+New Tokens
+
+    Accepted by the <name> parameter of eglQueryDeviceStringEXT:
+
+        EGL_DRIVER_NAME_EXT          0x335E
+
+    Accepted by the <name> parameter of eglQueryDeviceBinaryEXT:
+
+        EGL_DEVICE_UUID_EXT          0x335C
+        EGL_DRIVER_UUID_EXT          0x335D
+
+Changes to section 3.2 (Devices)
+
+    Add the following paragraph to the description of
+    eglQueryDeviceStringEXT:
+
+    EGL_DRIVER_NAME_EXT returns a string which identifies the driver
+    that controls the device. This string remains persistent across
+    multiple versions of a driver, and an application can use strcmp(3)
+    to compare the strings for equality. Otherwise, the contents are
+    implementation-defined.
+
+
+    Add to the end of section 3.2:
+
+    To query a binary attribute for a device, use:
+
+        EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
+                                          EGLint name,
+                                          EGLint max_size,
+                                          void *value,
+                                          EGLint *size);
+
+    On success, EGL_TRUE is returned. If <value> is NULL, then
+    <max_size> is ignored, and the size of the attribute in bytes is
+    returned in <size>.
+
+    On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is
+    generated if <name> is not a valid attribute. An EGL_BAD_DEVICE_EXT
+    error is generated if <device> is not a valid EGLDeviceEXT.
+
+    If <value> is not NULL, then the attribute value is returned in
+    <value>. At most <max_size> bytes are written. <size> returns the
+    number of bytes that were actually written.
+
+    Note that the EGL_DEVICE_UUID_EXT and EGL_DRIVER_UUID_EXT attributes
+    are always 16-byte values, and so the application can simply use a
+    16-byte buffer without needing to query the size beforehand. Future
+    extensions may add variable-length attributes.
+
+
+    EGL_DEVICE_UUID_EXT is a UUID that identifies a physical device,
+    returned as a 16-byte binary value. The device UUID uniquely
+    identifies a physical device, and is persistent across reboots,
+    processes, APIs, and (to the extent possible) driver versions.
+
+    EGL_DEVICE_UUID_EXT may or may not be persistent across changes in
+    hardware configuration. Similarly, it is not guaranteed to be unique
+    or persistent across different (physical or virtual) computers.
+
+    Note that EGL_DEVICE_UUID_EXT alone is not guaranteed to be unique
+    across all EGLDeviceEXT handles. If an EGL implementation supports
+    multiple drivers, and two drivers can use the same physical device,
+    then there will be a separate EGLDeviceEXT handle from each driver.
+    Both EGLDeviceEXT handles may use the same device UUID.
+
+    In that case, an application must use EGL_DRIVER_NAME_EXT or
+    EGL_DRIVER_UUID_EXT to distinguish between the two EGLDeviceEXT
+    handles.
+
+
+    EGL_DRIVER_UUID_EXT is a UUID that identifies a driver build
+    in use for a device. The driver UUID is persistent across reboots,
+    processes, and APIs, but is not persistent across driver versions.
+
+Issues
+
+    1.  Should we use UUID's or strings to identify devices?
+
+        RESOLVED: Use UUID's for devices, plus a vendor name string to
+        disambiguate devices that are supported by multiple drivers.
+
+        A device UUID and driver UUID allow an application to correlate
+        an EGLDeviceEXT with the same device in other APIs, such as a
+        VkPhysicalDevice in Vulkan.
+
+        A UUID does not impose any additional requirements on an EGL
+        implementation compared to a string: If an EGL implementation
+        could generate a string identifier, then the implementation can
+        simply hash that string to generate a UUID value.
+
+    2.  Can two EGLDeviceEXT handles have the same EGL_DEVICE_UUID_EXT?
+
+        RESOLVED: Yes, if they correspond to the same physical device.
+
+        The semantics of the device and driver UUID's are inherited from
+        Vulkan, which only requires that a device UUID be unique to a
+        physical device, not unique across VkPhysicalDevice handles.
+
+    3.  Do we need the EGL_DRIVER_NAME_EXT string?
+
+        RESOLVED: Yes, because the EGL_DEVICE_UUID_EXT alone is not
+        unique, and EGL_DRIVER_UUID_EXT is not persistent.
+
+        A (EGL_DRIVER_NAME_EXT, EGL_DEVICE_UUID_EXT) pair provides a
+        unique, persistent identifier.
+
+        In addition, on systems that use libglvnd, applications could
+        use EGL_DRIVER_NAME_EXT to match the vendor names from
+        GLX_EXT_libglvnd.
+
+    4.  What happens if an application stores a device UUID, and the
+        hardware configuration or driver version changes?
+
+        RESOLVED: The device UUID may become invalid, and the
+        application should select a new device.
+
+        If a device is removed from a system, then there will be no
+        EGLDeviceEXT handle for it, and thus no device UUID for it.
+
+        Similarly, if a device is moved within a system (e.g., plugged
+        into a different PCI slot), then a driver may not be able to
+        identify it as the same device, and so the device might get a
+        different UUID.
+
+        While not a requirement, drivers should still try to keep device
+        UUID's persistent whenever possible, to avoid invalidating
+        config files. Similarly, if a device is removed or replaced,
+        then a driver should try to ensure that the same device UUID
+        does not refer to a different device.
+
+        As an example, a driver could derive a UUID based on a PCI
+        vendor and device number, plus the PCI domain, bus, slot, and
+        function numbers:
+
+        * The PCI device number ensures that replacing a GPU with a
+          different model in the same PCI slot produces a different
+          device UUID string.
+        * Using the PCI bus numbers ensures that two identical
+          GPU's in the same system have unique UUID's.
+        * The whole tuple can easily stay persistent across driver
+          versions.
+
+Revision History
+
+    #1 (April 19, 2021) Kyle Brenneman
+
+        - Initial draft

index.php

@@ -351,6 +351,8 @@
 </li>
 <li value=142> <a href="extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt">EGL_ANGLE_sync_control_rate</a>
 </li>
+<li value=143> <a href="extensions/EXT/EGL_EXT_device_persistent_id.txt">EGL_EXT_device_persistent_id</a>
+</li>
 </ol>
 
 <h6> Providing Feedback on the Registry </h6>

registry.tcl

@@ -737,4 +737,9 @@ extension EGL_ANGLE_sync_control_rate {
     flags       public
     filename    extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt
 }
-# Next free extension number: 143
+extension EGL_EXT_device_persistent_id {
+    number      143
+    flags       public
+    filename    extensions/EXT/EGL_EXT_device_persistent_id.txt
+}
+# Next free extension number: 144