xref: /third_party/EGL/extensions/EXT/EGL_EXT_device_persistent_id.txt

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