• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    EXT_device_persistent_id
4
5Name Strings
6
7    EGL_EXT_device_persistent_id
8
9Contributors
10
11    Kyle Brenneman,  NVIDIA  (kbrenneman 'at' nvidia.com)
12
13Contact
14
15    Kyle Brenneman,  NVIDIA  (kbrenneman 'at' nvidia.com)
16
17Version
18
19    Version 1 - April 19, 2021
20
21Number
22
23    EGL Extension #142
24
25Extension Type
26
27    EGL device extension
28
29Dependencies
30
31    Written based on the wording of the EGL 1.5 specification.
32
33    EGL_EXT_device_query is required.
34
35Overview
36
37    Applications can query a list of EGLDeviceEXT handles, but those
38    handles are only valid within the process that queried them. An
39    application has no way, for example, to record its selection and
40    select the same device when run again later.
41
42    This extension provides a vendor name and a set of UUID's, which
43    provide a unique, persistent identifier for EGLDeviceEXT handles.
44    This allows applications to find the EGLDeviceEXT for the same
45    device across multiple processes, and across multiple APIs.
46
47New Procedures and Functions
48
49    EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
50                                      EGLint name,
51                                      EGLint max_size,
52                                      void *value,
53                                      EGLint *size);
54
55New Tokens
56
57    Accepted by the <name> parameter of eglQueryDeviceStringEXT:
58
59        EGL_DRIVER_NAME_EXT          0x335E
60
61    Accepted by the <name> parameter of eglQueryDeviceBinaryEXT:
62
63        EGL_DEVICE_UUID_EXT          0x335C
64        EGL_DRIVER_UUID_EXT          0x335D
65
66Changes to section 3.2 (Devices)
67
68    Add the following paragraph to the description of
69    eglQueryDeviceStringEXT:
70
71    EGL_DRIVER_NAME_EXT returns a string which identifies the driver
72    that controls the device. This string remains persistent across
73    multiple versions of a driver, and an application can use strcmp(3)
74    to compare the strings for equality. Otherwise, the contents are
75    implementation-defined.
76
77
78    Add to the end of section 3.2:
79
80    To query a binary attribute for a device, use:
81
82        EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
83                                          EGLint name,
84                                          EGLint max_size,
85                                          void *value,
86                                          EGLint *size);
87
88    On success, EGL_TRUE is returned. If <value> is NULL, then
89    <max_size> is ignored, and the size of the attribute in bytes is
90    returned in <size>.
91
92    On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is
93    generated if <name> is not a valid attribute. An EGL_BAD_DEVICE_EXT
94    error is generated if <device> is not a valid EGLDeviceEXT.
95
96    If <value> is not NULL, then the attribute value is returned in
97    <value>. At most <max_size> bytes are written. <size> returns the
98    number of bytes that were actually written.
99
100    Note that the EGL_DEVICE_UUID_EXT and EGL_DRIVER_UUID_EXT attributes
101    are always 16-byte values, and so the application can simply use a
102    16-byte buffer without needing to query the size beforehand. Future
103    extensions may add variable-length attributes.
104
105
106    EGL_DEVICE_UUID_EXT is a UUID that identifies a physical device,
107    returned as a 16-byte binary value. The device UUID uniquely
108    identifies a physical device, and is persistent across reboots,
109    processes, APIs, and (to the extent possible) driver versions.
110
111    EGL_DEVICE_UUID_EXT may or may not be persistent across changes in
112    hardware configuration. Similarly, it is not guaranteed to be unique
113    or persistent across different (physical or virtual) computers.
114
115    Note that EGL_DEVICE_UUID_EXT alone is not guaranteed to be unique
116    across all EGLDeviceEXT handles. If an EGL implementation supports
117    multiple drivers, and two drivers can use the same physical device,
118    then there will be a separate EGLDeviceEXT handle from each driver.
119    Both EGLDeviceEXT handles may use the same device UUID.
120
121    In that case, an application must use EGL_DRIVER_NAME_EXT or
122    EGL_DRIVER_UUID_EXT to distinguish between the two EGLDeviceEXT
123    handles.
124
125
126    EGL_DRIVER_UUID_EXT is a UUID that identifies a driver build
127    in use for a device. The driver UUID is persistent across reboots,
128    processes, and APIs, but is not persistent across driver versions.
129
130Issues
131
132    1.  Should we use UUID's or strings to identify devices?
133
134        RESOLVED: Use UUID's for devices, plus a vendor name string to
135        disambiguate devices that are supported by multiple drivers.
136
137        A device UUID and driver UUID allow an application to correlate
138        an EGLDeviceEXT with the same device in other APIs, such as a
139        VkPhysicalDevice in Vulkan.
140
141        A UUID does not impose any additional requirements on an EGL
142        implementation compared to a string: If an EGL implementation
143        could generate a string identifier, then the implementation can
144        simply hash that string to generate a UUID value.
145
146    2.  Can two EGLDeviceEXT handles have the same EGL_DEVICE_UUID_EXT?
147
148        RESOLVED: Yes, if they correspond to the same physical device.
149
150        The semantics of the device and driver UUID's are inherited from
151        Vulkan, which only requires that a device UUID be unique to a
152        physical device, not unique across VkPhysicalDevice handles.
153
154    3.  Do we need the EGL_DRIVER_NAME_EXT string?
155
156        RESOLVED: Yes, because the EGL_DEVICE_UUID_EXT alone is not
157        unique, and EGL_DRIVER_UUID_EXT is not persistent.
158
159        A (EGL_DRIVER_NAME_EXT, EGL_DEVICE_UUID_EXT) pair provides a
160        unique, persistent identifier.
161
162        In addition, on systems that use libglvnd, applications could
163        use EGL_DRIVER_NAME_EXT to match the vendor names from
164        GLX_EXT_libglvnd.
165
166    4.  What happens if an application stores a device UUID, and the
167        hardware configuration or driver version changes?
168
169        RESOLVED: The device UUID may become invalid, and the
170        application should select a new device.
171
172        If a device is removed from a system, then there will be no
173        EGLDeviceEXT handle for it, and thus no device UUID for it.
174
175        Similarly, if a device is moved within a system (e.g., plugged
176        into a different PCI slot), then a driver may not be able to
177        identify it as the same device, and so the device might get a
178        different UUID.
179
180        While not a requirement, drivers should still try to keep device
181        UUID's persistent whenever possible, to avoid invalidating
182        config files. Similarly, if a device is removed or replaced,
183        then a driver should try to ensure that the same device UUID
184        does not refer to a different device.
185
186        As an example, a driver could derive a UUID based on a PCI
187        vendor and device number, plus the PCI domain, bus, slot, and
188        function numbers:
189
190        * The PCI device number ensures that replacing a GPU with a
191          different model in the same PCI slot produces a different
192          device UUID string.
193        * Using the PCI bus numbers ensures that two identical
194          GPU's in the same system have unique UUID's.
195        * The whole tuple can easily stay persistent across driver
196          versions.
197
198Revision History
199
200    #1 (April 19, 2021) Kyle Brenneman
201
202        - Initial draft
203