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 parameter of eglQueryDeviceStringEXT: EGL_DRIVER_NAME_EXT 0x335E Accepted by the 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 is NULL, then is ignored, and the size of the attribute in bytes is returned in . On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is generated if is not a valid attribute. An EGL_BAD_DEVICE_EXT error is generated if is not a valid EGLDeviceEXT. If is not NULL, then the attribute value is returned in . At most bytes are written. 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