dri3proto.txt revision 17ca54c3
1 The DRI3 Extension 2 Version 1.2 3 2018-02-28 4 5 Keith Packard 6 keithp@keithp.com 7 Intel Corporation 8 9 Daniel Stone 10 daniels@collabora.com 11 Collabora 12 13 141. Introduction 15 16The DRI3 extension provides mechanisms to translate between direct 17rendered buffers and X pixmaps. When combined with the Present extension, 18a complete direct rendering solution for hardware-accelerated devices 19such as GPUs is provided. 20 21The direct rendered buffers are passed across the protocol via 22standard POSIX file descriptor passing mechanisms. On Linux, these 23buffers are DMA-BUF objects. 24 25DRI3 also includes a mechanism to translate between Linux Futexes 26and X Sync extension Fences. This provides a synchronization mechanism 27which can be used to serialize access to shared render buffers. 28 291.1. Acknowledgments 30 31Eric Anholt <eric@anholt.net> 32Dave Airlie <airlied@redhat.com> 33Kristian Høgsberg <krh@bitplanet.net> 34James Jones <jajones@nvidia.com> 35Arthur Huillet <arthur.huillet@free.fr> 36Louis-Francis Ratté-Boulianne <lfrb@collabora.com> 37 38 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 39 402. Data Types 41 42The DRI3 extension uses the RandR extension Provider data type to 43select among multiple GPUs on a single screen and the Sync extension 44fence object to provide graphics object synchronization. 45 46 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 47 484. Errors 49 50DRI3 defines no errors. 51 52 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 53 545. Events 55 56DRI3 defines no events. 57 58 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 59 606. Protocol Types 61 62DRI3 defines no new protocol types. 63 64 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 65 667. Extension Initialization 67 68The name of this extension is "DRI3" 69 70┌─── 71 DRI3QueryVersion 72 client-major-version: CARD32 73 client-minor-version: CARD32 74 ▶ 75 major-version: CARD32 76 minor-version: CARD32 77└─── 78 79 The client sends the highest supported version to the server 80 and the server sends the highest version it supports, but no 81 higher than the requested version. Major versions changes can 82 introduce incompatibilities in existing functionality, minor 83 version changes introduce only backward compatible changes. 84 It is the clients responsibility to ensure that the server 85 supports a version which is compatible with its expectations. 86 87 Backwards compatible changes included addition of new 88 requests. 89 90 91 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 92 938. Extension Requests 94 95┌─── 96 DRI3Open 97 drawable: DRAWABLE 98 provider: PROVIDER 99 ▶ 100 nfd: CARD8 101 device: FD 102└─── 103 Errors: Drawable, Value, Match 104 105 This requests that the X server open the direct rendering 106 device associated with drawable and RandR provider. The 107 provider must support SourceOutput or SourceOffload. 108 109 The file descriptor for the device is returned in 110 'device'. 'nfd' will be set to one (this is strictly a 111 convenience for XCB which otherwise would need 112 request-specific information about how many file descriptors 113 were associated with this reply). 114 115┌─── 116 DRI3PixmapFromBuffer 117 pixmap: PIXMAP 118 drawable: DRAWABLE 119 size: CARD32 120 width, height, stride: CARD16 121 depth, bpp: CARD8 122 buffer: FD 123└─── 124 Errors: Alloc, Drawable, IDChoice, Value, Match 125 126 Creates a pixmap for the direct rendering object associated 127 with 'buffer' and the screen associated with 'drawable'. 128 Changes to pixmap will be visible in that direct rendered 129 object and changes to the direct rendered object will be 130 visible in the pixmap. 131 132 'size' specifies the total size of the buffer bytes. 'width', 133 'height' describe the geometry (in pixels) of the underlying 134 buffer. 'stride' specifies the number of bytes per scanline in 135 the buffer. The pixels within the buffer are not required to 136 be arranged in a simple linear fashion, but 'size' will be at 137 least 'height' * 'stride'. 138 139 Precisely how any additional information about the buffer is 140 shared is outside the scope of this extension. 141 142 If buffer cannot be used with the screen associated with 143 drawable, a Match error is returned. 144 145 If depth or bpp are not supported by the screen, a Value error 146 is returned. 147 148 For information on synchronization of buffer access between 149 the client and the X server, please see section 12. 150 151┌─── 152 DRI3BufferFromPixmap 153 pixmap: PIXMAP 154 ▶ 155 nfd: CARD8 156 size: CARD32 157 width, height, stride: CARD16 158 depth, bpp: CARD8 159 buffer: FD 160└─── 161 Errors: Pixmap, Match 162 163 Pass back a direct rendering object associated with 164 pixmap. Changes to pixmap will be visible in that 165 direct rendered object and changes to the direct rendered 166 object will be visible in the pixmap. 167 168 'size' specifies the total size of the buffer bytes. 'width', 169 'height' describe the geometry (in pixels) of the underlying 170 buffer. 'stride' specifies the number of bytes per scanline in 171 the buffer. The pixels within the buffer are not required to 172 be arranged in a simple linear fashion, but 'size' will be at 173 least 'height' * 'stride'. 174 175 Precisely how any additional information about the buffer is 176 shared is outside the scope of this extension. 177 178 If buffer cannot be used with the screen associated with 179 drawable, a Match error is returned. 180 181 For information on synchronization of buffer access between 182 the client and the X server, please see section 12. 183 184┌─── 185 DRI3FenceFromFD 186 drawable: DRAWABLE 187 fence: FENCE 188 initially-triggered: BOOL 189 fd: FD 190└─── 191 Errors: IDchoice, Drawable 192 193 Creates a Sync extension Fence that provides the regular Sync 194 extension semantics along with a file descriptor that provides 195 a device-specific mechanism to manipulate the fence directly. 196 Details about the mechanism used with this file descriptor are 197 outside the scope of the DRI3 extension. 198 199 For information on synchronization of buffer access between 200 the client and the X server, please see section 12. 201 202┌─── 203 DRI3FDFromFence 204 drawable: DRAWABLE 205 fence: FENCE 206 ▶ 207 fd: FD 208└─── 209 Errors: IDchoice, Drawable, Match 210 211 Given a Sync extension Fence that provides the regular Sync 212 extension semantics, returns a file descriptor that provides a 213 device-specific mechanism to manipulate the fence directly. 214 Details about the mechanism used with this file descriptor are 215 outside the scope of the DRI3 extension. 'drawable' must be 216 associated with a direct rendering device that 'fence' can 217 work with, otherwise a Match error results. 218 219 For information on synchronization of buffer access between 220 the client and the X server, please see section 12. 221 222┌─── 223 DRI3GetSupportedModifiers 224 window: WINDOW 225 depth: CARD8 226 bpp: CARD8 227 ▶ 228 num_window_modifiers: CARD32 229 num_screen_modifiers: CARD32 230 window_modifiers: ListOfCARD64 231 screen_modifiers: ListOfCARD64 232└─── 233 Errors: Window, Match 234 235 Return supported DRM FourCC modifiers for the specified 236 'window'. 237 238 The first list of 'window_modifiers' contains a set of 239 modifiers which the server considers optimal for the window's 240 current configuration. Using these modifiers to allocate, even 241 if locally suboptimal to the client driver, may result in a 242 more optimal display pipeline, e.g. by avoiding composition. 243 244 The second list of 'screen_modifiers', is the total set of 245 modifiers which are acceptable for use on the Screen associated 246 with 'window'. This set of modifiers will not change over the 247 lifetime of the client. Using this set of modifiers to allocate 248 may not result in a globally optimal pipeline, if separate 249 'window_modifiers' are available. 250 251 It is expected that a client calling this request will obtain 252 the modifiers for a particular window, allocate buffers using 253 the preferred modifier set as described above, create a Pixmap 254 referring to the storage of those buffers using the 255 DRI3BuffersFromPixmap request, then make the content visible 256 in the storage of those buffers visible with a request such as 257 the Present extension's PresentPixmap. 258 259 The meaning of any modifier is canonically defined in 260 drm_fourcc.h. 261 262┌─── 263 DRI3PixmapFromBuffers 264 pixmap: PIXMAP 265 window: WINDOW 266 num_buffers: CARD8 267 width, height: CARD16 268 stride0, offset0: CARD32 269 stride1, offset1: CARD32 270 stride2, offset2: CARD32 271 stride3, offset3: CARD32 272 depth, bpp: CARD8 273 modifier: CARD64 274 buffers: ListOfFD 275└─── 276 Errors: Alloc, Window, IDChoice, Value, Match 277 278 Creates a pixmap for the direct rendering object associated 279 with 'buffers' and the screen associated with 'window'. 280 Changes to pixmap will be visible in that direct rendered 281 object and changes to the direct rendered object will be 282 visible in the pixmap. The pixmap will be available for 283 presentation to the window. 284 285 In contrast to PixmapFromBuffer, multiple buffers may be 286 combined to specify a single logical source for pixel 287 sampling: 'num_buffers' may be set from 1 (single buffer, 288 akin to PixmapFromBuffer) to 4. This is the number of file 289 descriptors which will be sent with this request; one per 290 buffer. 291 292 Modifiers allow explicit specification of non-linear sources, 293 such as tiled or compressed buffers. The combination of bpp, 294 depth, and modifier allows unambiguous declaration of the 295 buffer layout in a manner defined by the DRM tokens. 296 297 If 'modifier' is DRM_FORMAT_MOD_INVALID, the client does 298 not have information on the buffer layout. In this case, the 299 buffer may only have a single plane. The driver may make its 300 own inference through unspecified means to determine the exact 301 buffer layout, however this is neither required nor defined 302 by the specification, and is considered an implementation 303 detail of the particular driver. 304 305 'width' and 'height' describe the geometry (in pixels) of the 306 logical pixel-sample source. 307 308 'strideN' and 'offsetN' define the number of bytes per logical 309 scanline, and the distance in bytes from the beginning of the 310 buffer passed for that plane until the start of the sample 311 source for that plane, respectively for plane N. If the plane 312 is not used according to the format and modifier specification, 313 both values for that plane must be zero. 314 315 Precisely how any additional information about the buffer (such 316 as memory placement) is shared is outside the scope of this 317 extension. 318 319 If the buffer(s) cannot be used with the screen associated with 320 'window', a Match error is returned. 321 322 If the bpp, depth, and modifier combination is not supported by 323 the screen, a Value error is returned. 324 325 For information on synchronization of buffer access between 326 the client and the X server, please see section 12. 327 328┌─── 329 DRI3BuffersFromPixmap 330 pixmap: PIXMAP 331 ▶ 332 nfd: CARD8 333 width, height: CARD16 334 depth, bpp: CARD8 335 modifier: CARD64 336 strides: ListOfCARD32 337 offsets: ListOfCARD32 338 buffers: ListOfFD 339└─── 340 Errors: Pixmap, Match 341 342 Returns direct rendering objects associated with 'pixmap'. 343 Changes to 'pixmap' will be visible in the direct rendered 344 objects and changes to the direct rendered objects will be 345 visible in 'pixmap' after flushing and synchronization. 346 347 'width' and 'height' describe the geometry (in pixels) of the 348 logical pixel-sample source from combining the direct rendering 349 objects. 350 351 See PixmapFromBuffers for more details on DRM modifiers usage. 352 353 'nfd' describes the number of buffers returned for the pixmap, 354 which must be combined together according to 'depth', 'bpp', and 355 'modifier'. 356 357 For each buffer, there is an entry in the 'strides', 358 'offsets', and 'buffers' list. 'buffer' contains a single file 359 descriptor referring to the buffer. 'stride' specifies the 360 number of bytes per logical scanline for this plane, and 361 'offset' specifies the distance in bytes from the beginning 362 of 'buffer' until the start of the sample source for that 363 plane. 364 365 Precisely how any additional information about the buffer is 366 shared is outside the scope of this extension. 367 368 If buffers cannot be exported from the the screen associated 369 with 'pixmap', a Match error is returned. 370 371 For information on synchronization of buffer access between 372 the client and the X server, please see section 12. 373 374 375 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 376 3779. Extension Events 378 379DRI3 defines no events. 380 381 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 382 38310. Extension Versioning 384 385The DRI3 extension is adapted from the DRI2 extension. 386 387 1.0: First published version 388 389 1.1: Cosmetic changes 390 391 1.2: Add GetSupportedModifiers, 392 PixmapFromBuffers, and BuffersFromPixmap requests. 393 394 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 395 396 39711. Relationship with other extensions 398 399As an extension designed to support other extensions, there is 400naturally some interactions with other extensions. 401 40211.1 GLX 403 404GLX is both an application interface and an X extension. OpenGL 405applications using the GLX API will use the GLX extension, DRI3 and 406Present when doing direct rendering. 407 40811.2 Present 409 410The Present extension provides a way to synchronize the display of pixmap 411contents to the screen. When used in conjunction with DRI3, they 412provide a complete direct rendering solution for OpenGL or other APIs. 413 41411.3 DRI2 415 416DRI3 provides similar functionality to the DRI2Connect and 417DRI2GetBuffersWithFormat requests, however DRI3 uses file descriptors 418to refer to the direct rendering device and buffers. 419 420Present and DRI3 are designed in conjunction to replace DRI2 421 42211.2 XvMC / Xv 423 424It might be nice to be able to reference YUV formatted direct rendered 425objects from the X server. 426 427 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 428 42912. Synchronization 430 431Synchronization of access to buffers shared between processes is not 432currently explicitly controlled by this protocol. 433 434Without the use of additional extensions not defined by the DRI3 435protocol as of version 1.2, synchronization between multiple 436processes and contexts is considered to follow the implicit model. 437 438In this model, the driver is required to have a global view of 439access requests issued by all processes with a reference to the 440buffer, and control scheduling of all operations on that buffer, 441whether performed by the CPU or auxiliary hardware. 442 443The driver is responsible for enforcing a strict ordering to protect 444against write-after-read or read-after-write hazards, such that any 445reads requested by one process or context, are fulfilled before any 446writes requested by another process or context, as long as that read 447was definitively submitted before the write. 448 449A similar dependency exists for reads submitted after writes: the 450driver must ensure that the write is fully visible and coherent to 451the read request. 452 453As a purely illustrative example, if two processes share a buffer, 454where one process reads from a buffer using an OpenGL texture 455sampler and submits this work by calling 'glFlush', and the other 456process submits work to the driver to write to that buffer, the 457driver is responsible for ensuring that the results of the latter 458write are not visible to the texture sampler. 459 460The Sync fences provided by DRI3 control only this submission of 461work and ensuing global visibility of the requests, rather than the 462completion of the work within any hardware. To further the example 463above, a fence used to prevent any writes to the buffer before the 464sampler had completed access, the fence would be signaled when 465'glFlush' had been called, at which point the request has become 466globally visible to the driver's request-scheduling and 467synchronization mechanisms. The logical ordering of requests made 468by software has been preserved, and the driver then takes care 469to ensure that these requests are scheduled such they do not 470observe effects from requests made later in time. 471 472This presents a fully coherent in-order FIFO-like model across 473processes, where synchronzation is handled externally to the DRI3 474client with no explicit intervention. 475 476This restriction also applies for cross-device usage. 477 478 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 479 480Appendix A. Protocol Encoding 481 482Syntactic Conventions 483 484This document uses the same syntactic conventions as the core X 485protocol encoding document. 486 487 488A.1 Common Types 489 490None. 491 492A.2 Protocol Requests 493 494┌─── 495 DRI3QueryVersion 496 1 CARD8 major opcode 497 1 0 DRI3 opcode 498 2 3 length 499 4 CARD32 major version 500 4 CARD32 minor version 501 ▶ 502 1 1 Reply 503 1 unused 504 2 CARD16 sequence number 505 4 0 reply length 506 4 CARD32 major version 507 4 CARD32 minor version 508 16 unused 509└─── 510 511 512┌─── 513 DRI3Open 514 1 CARD8 major opcode 515 1 1 DRI3 opcode 516 2 4 length 517 4 DRAWABLE drawable 518 4 PROVIDER provider 519 ▶ 520 1 1 Reply 521 1 1 nfd 522 2 CARD16 sequence number 523 4 0 reply length 524 24 unused 525 526 0 FD device 527└─── 528 529┌─── 530 DRI3PixmapFromBuffer 531 1 CARD8 major opcode 532 1 2 DRI3 opcode 533 2 6 length 534 4 Pixmap pixmap 535 4 Drawable drawable 536 4 CARD32 size 537 2 CARD16 width 538 2 CARD16 height 539 2 CARD16 stride 540 1 CARD8 depth 541 1 CARD8 bpp 542 543 0 FD buffer 544└─── 545 546┌─── 547 DRI3BufferFromPixmap 548 1 CARD8 major opcode 549 1 3 DRI3 opcode 550 2 2 length 551 4 Pixmap pixmap 552 ▶ 553 1 1 Reply 554 1 1 nfd 555 2 CARD16 sequence number 556 4 0 reply length 557 4 CARD32 size 558 2 CARD16 width 559 2 CARD16 height 560 2 CARD16 stride 561 1 CARD8 depth 562 1 CARD8 bpp 563 12 unused 564 565 0 FD buffer 566└─── 567 568┌─── 569 DRI3FenceFromFD 570 1 CARD8 major opcode 571 1 4 DRI3 opcode 572 2 4 length 573 4 Drawable drawable 574 4 Fence fence 575 1 BOOL initially triggered 576 3 unused 577 578 0 FD fence fd 579└─── 580 581┌─── 582 DRI3FDFromFence 583 1 CARD8 major opcode 584 1 5 DRI3 opcode 585 2 3 length 586 4 Drawable drawable 587 4 Fence fence 588 ▶ 589 1 1 Reply 590 1 1 nfd 591 2 CARD16 sequence number 592 4 0 reply length 593 24 unused 594 595 0 FD fence fd 596└─── 597 598┌─── 599 DRI3GetSupportedModifiers 600 1 CARD8 major opcode 601 1 7 DRI3 opcode 602 2 3 length 603 4 Window window 604 1 CARD8 depth 605 1 CARD8 bpp 606 2 unused 607 ▶ 608 1 1 Reply 609 1 0 unused 610 2 CARD16 sequence number 611 4 CARD32 reply length 612 4 CARD32 num_window_modifiers 613 4 CARD32 num_screen_modifiers 614 16 unused 615 616 4 ListOfCARD64 window_modifiers[num_window_modifiers] 617 4 ListOfCARD64 screen_modifiers[num_screen_modifiers] 618└─── 619 620┌─── 621 DRI3PixmapFromBuffers 622 1 CARD8 major opcode 623 1 8 DRI3 opcode 624 2 8 length 625 4 Pixmap pixmap 626 4 Window window 627 1 CARD8 num_buffers 628 3 unused 629 2 CARD16 width 630 2 CARD16 height 631 4 CARD32 stride0 632 4 CARD32 offset0 633 4 CARD32 stride1 634 4 CARD32 offset1 635 4 CARD32 stride2 636 4 CARD32 offset2 637 4 CARD32 stride3 638 4 CARD32 offset3 639 1 CARD8 depth 640 1 CARD8 bpp 641 2 unused 642 8 CARD64 modifier 643 644 0 ListOfFD buffers[num_buffers] 645└─── 646 647┌─── 648 DRI3BuffersFromPixmap 649 1 CARD8 major opcode 650 1 9 DRI3 opcode 651 2 2 length 652 4 Pixmap pixmap 653 ▶ 654 1 1 Reply 655 1 CARD8 nfd 656 2 CARD16 sequence number 657 4 CARD32 reply length 658 2 CARD16 width 659 2 CARD16 height 660 4 CARD8 unused 661 8 CARD64 modifier 662 1 CARD8 depth 663 1 CARD8 bpp 664 6 unused 665 666 0 ListOfFD buffer[nfd] 667 4 ListOfCARD32 strides[nfd] 668 4 ListOfCARD32 offsets[nfd] 669└─── 670 671A.3 Protocol Events 672 673The DRI3 extension defines no events. 674 675A.4 Protocol Errors 676 677The DRI3 extension defines no errors. 678 679 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 680