dri3proto.txt revision 452262e1
1 The DRI3 Extension 2 Version 1.3 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 63DRI3 defines no new protocol types. 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 4009. Extension Events 401 402DRI3 defines no events. 403 404 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 405 40610. Extension Versioning 407 408The DRI3 extension is adapted from the DRI2 extension. 409 410 1.0: First published version 411 412 1.1: Cosmetic changes 413 414 1.2: Add GetSupportedModifiers, 415 PixmapFromBuffers, and BuffersFromPixmap requests. 416 417 1.3: Add SetDRMDeviceInUse 418 419 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 420 421 42211. Relationship with other extensions 423 424As an extension designed to support other extensions, there is 425naturally some interactions with other extensions. 426 42711.1 GLX 428 429GLX is both an application interface and an X extension. OpenGL 430applications using the GLX API will use the GLX extension, DRI3 and 431Present when doing direct rendering. 432 43311.2 Present 434 435The Present extension provides a way to synchronize the display of pixmap 436contents to the screen. When used in conjunction with DRI3, they 437provide a complete direct rendering solution for OpenGL or other APIs. 438 43911.3 DRI2 440 441DRI3 provides similar functionality to the DRI2Connect and 442DRI2GetBuffersWithFormat requests, however DRI3 uses file descriptors 443to refer to the direct rendering device and buffers. 444 445Present and DRI3 are designed in conjunction to replace DRI2 446 44711.2 XvMC / Xv 448 449It might be nice to be able to reference YUV formatted direct rendered 450objects from the X server. 451 452 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 453 45412. Synchronization 455 456Synchronization of access to buffers shared between processes is not 457currently explicitly controlled by this protocol. 458 459Without the use of additional extensions not defined by the DRI3 460protocol as of version 1.2, synchronization between multiple 461processes and contexts is considered to follow the implicit model. 462 463In this model, the driver is required to have a global view of 464access requests issued by all processes with a reference to the 465buffer, and control scheduling of all operations on that buffer, 466whether performed by the CPU or auxiliary hardware. 467 468The driver is responsible for enforcing a strict ordering to protect 469against write-after-read or read-after-write hazards, such that any 470reads requested by one process or context, are fulfilled before any 471writes requested by another process or context, as long as that read 472was definitively submitted before the write. 473 474A similar dependency exists for reads submitted after writes: the 475driver must ensure that the write is fully visible and coherent to 476the read request. 477 478As a purely illustrative example, if two processes share a buffer, 479where one process reads from a buffer using an OpenGL texture 480sampler and submits this work by calling 'glFlush', and the other 481process submits work to the driver to write to that buffer, the 482driver is responsible for ensuring that the results of the latter 483write are not visible to the texture sampler. 484 485The Sync fences provided by DRI3 control only this submission of 486work and ensuing global visibility of the requests, rather than the 487completion of the work within any hardware. To further the example 488above, a fence used to prevent any writes to the buffer before the 489sampler had completed access, the fence would be signaled when 490'glFlush' had been called, at which point the request has become 491globally visible to the driver's request-scheduling and 492synchronization mechanisms. The logical ordering of requests made 493by software has been preserved, and the driver then takes care 494to ensure that these requests are scheduled such they do not 495observe effects from requests made later in time. 496 497This presents a fully coherent in-order FIFO-like model across 498processes, where synchronzation is handled externally to the DRI3 499client with no explicit intervention. 500 501This restriction also applies for cross-device usage. 502 503 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 504 505Appendix A. Protocol Encoding 506 507Syntactic Conventions 508 509This document uses the same syntactic conventions as the core X 510protocol encoding document. 511 512 513A.1 Common Types 514 515None. 516 517A.2 Protocol Requests 518 519┌─── 520 DRI3QueryVersion 521 1 CARD8 major opcode 522 1 0 DRI3 opcode 523 2 3 length 524 4 CARD32 major version 525 4 CARD32 minor version 526 ▶ 527 1 1 Reply 528 1 unused 529 2 CARD16 sequence number 530 4 0 reply length 531 4 CARD32 major version 532 4 CARD32 minor version 533 16 unused 534└─── 535 536 537┌─── 538 DRI3Open 539 1 CARD8 major opcode 540 1 1 DRI3 opcode 541 2 4 length 542 4 DRAWABLE drawable 543 4 PROVIDER provider 544 ▶ 545 1 1 Reply 546 1 1 nfd 547 2 CARD16 sequence number 548 4 0 reply length 549 24 unused 550 551 0 FD device 552└─── 553 554┌─── 555 DRI3PixmapFromBuffer 556 1 CARD8 major opcode 557 1 2 DRI3 opcode 558 2 6 length 559 4 Pixmap pixmap 560 4 Drawable drawable 561 4 CARD32 size 562 2 CARD16 width 563 2 CARD16 height 564 2 CARD16 stride 565 1 CARD8 depth 566 1 CARD8 bpp 567 568 0 FD buffer 569└─── 570 571┌─── 572 DRI3BufferFromPixmap 573 1 CARD8 major opcode 574 1 3 DRI3 opcode 575 2 2 length 576 4 Pixmap pixmap 577 ▶ 578 1 1 Reply 579 1 1 nfd 580 2 CARD16 sequence number 581 4 0 reply length 582 4 CARD32 size 583 2 CARD16 width 584 2 CARD16 height 585 2 CARD16 stride 586 1 CARD8 depth 587 1 CARD8 bpp 588 12 unused 589 590 0 FD buffer 591└─── 592 593┌─── 594 DRI3FenceFromFD 595 1 CARD8 major opcode 596 1 4 DRI3 opcode 597 2 4 length 598 4 Drawable drawable 599 4 Fence fence 600 1 BOOL initially triggered 601 3 unused 602 603 0 FD fence fd 604└─── 605 606┌─── 607 DRI3FDFromFence 608 1 CARD8 major opcode 609 1 5 DRI3 opcode 610 2 3 length 611 4 Drawable drawable 612 4 Fence fence 613 ▶ 614 1 1 Reply 615 1 1 nfd 616 2 CARD16 sequence number 617 4 0 reply length 618 24 unused 619 620 0 FD fence fd 621└─── 622 623┌─── 624 DRI3GetSupportedModifiers 625 1 CARD8 major opcode 626 1 7 DRI3 opcode 627 2 3 length 628 4 Window window 629 1 CARD8 depth 630 1 CARD8 bpp 631 2 unused 632 ▶ 633 1 1 Reply 634 1 0 unused 635 2 CARD16 sequence number 636 4 CARD32 reply length 637 4 CARD32 num_window_modifiers 638 4 CARD32 num_screen_modifiers 639 16 unused 640 641 4 ListOfCARD64 window_modifiers[num_window_modifiers] 642 4 ListOfCARD64 screen_modifiers[num_screen_modifiers] 643└─── 644 645┌─── 646 DRI3PixmapFromBuffers 647 1 CARD8 major opcode 648 1 8 DRI3 opcode 649 2 8 length 650 4 Pixmap pixmap 651 4 Window window 652 1 CARD8 num_buffers 653 3 unused 654 2 CARD16 width 655 2 CARD16 height 656 4 CARD32 stride0 657 4 CARD32 offset0 658 4 CARD32 stride1 659 4 CARD32 offset1 660 4 CARD32 stride2 661 4 CARD32 offset2 662 4 CARD32 stride3 663 4 CARD32 offset3 664 1 CARD8 depth 665 1 CARD8 bpp 666 2 unused 667 8 CARD64 modifier 668 669 0 ListOfFD buffers[num_buffers] 670└─── 671 672┌─── 673 DRI3BuffersFromPixmap 674 1 CARD8 major opcode 675 1 9 DRI3 opcode 676 2 2 length 677 4 Pixmap pixmap 678 ▶ 679 1 1 Reply 680 1 CARD8 nfd 681 2 CARD16 sequence number 682 4 CARD32 reply length 683 2 CARD16 width 684 2 CARD16 height 685 4 CARD8 unused 686 8 CARD64 modifier 687 1 CARD8 depth 688 1 CARD8 bpp 689 6 unused 690 691 0 ListOfFD buffer[nfd] 692 4 ListOfCARD32 strides[nfd] 693 4 ListOfCARD32 offsets[nfd] 694└─── 695 696┌─── 697 DRI3SetDRMDeviceInUse 698 1 CARD8 major opcode 699 1 10 DRI3 opcode 700 2 4 length 701 4 Window window 702 4 CARD32 drmMajor 703 4 CARD32 drmMinor 704└─── 705 706A.3 Protocol Events 707 708The DRI3 extension defines no events. 709 710A.4 Protocol Errors 711 712The DRI3 extension defines no errors. 713 714 ❄ ❄ ❄ ❄ ❄ ❄ ❄ 715