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