Current DRI3 specification
James Jones
jajones at nvidia.com
Wed Jun 5 13:46:53 PDT 2013
On 06/04/2013 04:51 PM, Keith Packard wrote:
> * PGP Signed by an unknown key
>
>
> I've gotten DRI3 working and posted an article about it here:
>
> http://keithp.com/blogs/dri3_extension/
I read through this and the extension specification below. The DRI3
stuff doesn't directly affect our driver at the moment of course, but I
like the direction it's going and the proposed/implied interactions
between DRI3 and Present. Hopefully this will provide a path in
X11/Mesa for the Nouveau guys to get rid of the implicit kernel-based
serialization if they choose to tackle that task.
I read through your futex-based fence sync implementation notes as well.
Seems reasonable to me. I didn't try too hard to poke holes in it though.
Thanks,
-James
> I thought now might be a great time to post the current DRI3 protocol
> specification and let people take a look (and comment!)
>
> The DRI3 Extension
> Version 1.0
> 2013-6-4
>
> Keith Packard
> keithp at keithp.com
> Intel Corporation
>
> 1. Introduction
>
> The DRI3 extension provides mechanisms to translate between direct
> rendered buffers and X pixmaps. When combined with the Present extension,
> a complete direct rendering solution for OpenGL is provided.
>
> The direct rendered buffers are passed across the protocol via
> standard POSIX file descriptor passing mechanisms. On Linux, these
> buffers are DMA-BUF objects.
>
> DRI3 also includes a mechanism to translate between Linux Futexes
> and X Sync extension Fences. This provides a synchronization mechanism
> which can be used to serialize access to shared render buffers.
>
> 1.1. Acknowledgments
>
> Eric Anholt <eric at anholt.net>
> Dave Airlie <airlied at redhat.com>
> Kristian Høgsberg <krh at bitplanet.net>
> James Jones <janomes at nvidia.com>
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 2. Data Types
>
> DRI3EVENTID { XID }
>
> Defines a unique event delivery target for DRI3
> events. Multiple event IDs can be allocated to provide
> multiple distinct event delivery contexts.
>
> DRI3EVENTMASK { DRI3ConfigureNotifyMask }
>
> The DRI3 extension also uses the RandR extension Provider data type to
> select among multiple GPUs on a single screen and the Sync extension
> fence object to provide graphics object synchronization.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 4. Errors
>
> No errors are defined by the DRI3 extension.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 5. Events
>
> DRI3 adds a ConfigureNotify event to inform clients about window
> configuration changes which can affect the allocation of
> window-related direct rendered buffers.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 6. Protocol Types
>
> DRI3DRIVER { DRI3DriverDRI
> DRI3DriverVDPAU }
>
> These values describe the type of driver the client will want
> to load. The server sends back the name of the driver to use
> for the screen in question.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 7. Extension Initialization
>
> The name of this extension is "DRI3"
>
> ┌───
> DRI3QueryVersion
> client-major-version: CARD32
> client-minor-version: CARD32
> ▶
> major-version: CARD32
> minor-version: CARD32
> └───
>
> The client sends the highest supported version to the server
> and the server sends the highest version it supports, but no
> higher than the requested version. Major versions changes can
> introduce incompatibilities in existing functionality, minor
> version changes introduce only backward compatible changes.
> It is the clients responsibility to ensure that the server
> supports a version which is compatible with its expectations.
>
> Backwards compatible changes included addition of new
> requests.
>
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 8. Extension Requests
>
> ┌───
> DRI3Open
> drawable: DRAWABLE
> driverType: DRI3DRIVER
> provider: PROVIDER
> ▶
> nfd: CARD8
> driver: STRING
> device: FD
> └───
> Errors: Drawable, Value, Match
>
> This requests that the X server open the direct rendering
> device associated with drawable, driverType and RandR
> provider. The provider must support SourceOutput or SourceOffload.
>
> The direct rendering library used to implement the specified
> 'driverType' is returned in 'driver'. The file
> descriptor for the device is returned in 'device'. 'nfd' will
> be set to one (this is strictly a convenience for XCB which
> otherwise would need request-specific information about how
> many file descriptors were associated with this reply).
>
> ┌───
> DRI3PixmapFromBuffer
> pixmap: PIXMAP
> drawable: DRAWABLE
> size: CARD32
> width, height, stride: CARD16
> depth, bpp: CARD8
> buffer: FD
> └───
> Errors: Alloc, Drawable, IDChoice, Value, Match
>
> Creates a pixmap for the direct rendering object associated
> with 'buffer'. Changes to pixmap will be visible in that
> direct rendered object and changes to the direct rendered
> object will be visible in the pixmap.
>
> 'size' specifies the total size of the buffer bytes. 'width',
> 'height' describe the geometry (in pixels) of the underlying
> buffer. 'stride' specifies the number of bytes per scanline in
> the buffer. The pixels within the buffer may not be arranged
> in a simple linear fashion, but 'size' will be at least
> 'height' * 'stride'.
>
> Precisely how any additional information about the buffer is
> shared is outside the scope of this extension.
>
> If buffer cannot be used with the screen associated with
> drawable, a Match error is returned.
>
> If depth or bpp are not supported by the screen, a Value error
> is returned.
>
> ┌───
> DRI3BufferFromPixmap
> pixmap: PIXMAP
> ▶
> nfd: CARD8
> size: CARD32
> width, height, stride: CARD16
> depth, bpp: CARD8
> buffer: FD
> └───
> Errors: Pixmap, Match
>
> Pass back a direct rendering object associated with
> pixmap. Changes to pixmap will be visible in that
> direct rendered object and changes to the direct rendered
> object will be visible in the pixmap.
>
> 'size' specifies the total size of the buffer bytes. 'width',
> 'height' describe the geometry (in pixels) of the underlying
> buffer. 'stride' specifies the number of bytes per scanline in
> the buffer. The pixels within the buffer may not be arranged
> in a simple linear fashion, but 'size' will be at least
> 'height' * 'stride'.
>
> Precisely how any additional information about the buffer is
> shared is outside the scope of this extension.
>
> If buffer cannot be used with the screen associated with
> drawable, a Match error is returned.
>
> ┌───
> DRI3SelectInput
> eventContext: DRI3EVENTID
> window: WINDOW
> eventMask: SETofDRI3EVENT
> └───
> Errors: Window, Value, Match, IDchoice
>
> Selects the set of DRI3 events to be delivered for the
> specified window and event context. DRI3SelectInput can
> create, modifiy or delete event contexts. An event context is
> associated with a specific window; using an existing event
> context with a different window generates a Match error.
>
> If eventContext specifies an existing event context, then if
> eventMask is empty, DRI3SelectInput deletes the specified
> context, otherwise the specified event context is changed to
> select a different set of events.
>
> If eventContext is an unused XID, then if eventMask is empty
> no operation is performed. Otherwise, a new event context is
> created selecting the specified events.
>
> ┌───
> DRI3FenceFromFD
> drawable: DRAWABLE
> fence: FENCE
> initially-triggered: BOOL
> fd: FD
> └───
> Errors: IDchoice, Drawable
>
> Creates a Sync extension Fence that provides the regular Sync
> extension semantics along with a file descriptor that provides
> a device-specific mechanism to manipulate the fence directly.
> Details about the mechanism used with this file descriptor are
> outside the scope of the DRI3 extension.
>
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 9. Extension Events
>
> DRI3ConfigureNotify is sent if DRI3SelectInput has requested it.
> DRI3ConfigureNotify events are XGE events and so do not have a unique
> event ID.
>
> ┌───
> DRI3ConfigureNotify
> type: CARD8 XGE event type (35)
> extension: CARD8 DRI3 extension request number
> length: CARD16 2
> evtype: CARD16 DRI3_ConfigureNotify
> eventID: DRI3EVENTID
> window: WINDOW
> x: INT16
> y: INT16
> width: CARD16
> height: CARD16
> off_x: INT16
> off_y: INT16
> pixmap_width: CARD16
> pixmap_height: CARD16
> pixmap_flags: CARD32
> └───
>
> 'x' and 'y' are the parent-relative location of 'window'.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> 10. Extension Versioning
>
> The DRI3 extension is adapted from the DRI2 extension.
>
> 1.0: First published version
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
>
> 11. Relationship with other extensions
>
> As an extension designed to support other extensions, there is
> naturally some interactions with other extensions.
>
> 11.1 GLX
>
> GLX has no direct relation with DRI3, but a direct rendering OpenGL
> application will presumably use both, and target
>
> 11.2 Present
>
> The Present extension provides a way to synchronize the display of pixmap
> contents to the screen. When used in conjunction with DRI3, they
> provide a complete direct rendering solution for OpenGL or other APIs.
>
> 11.3 DRI2
>
> DRI3 provides similar functionality to the DRI2Connect and
> DRI2GetBuffersWithFormat requests, however DRI3 uses file descriptors
> to refer to the direct rendering device and buffers.
>
> Present and DRI3 are designed in conjunction to replace DRI2
>
> 11.2 XvMC / Xv
>
> It might be nice to be able to reference YUV formatted direct rendered
> objects from the X server.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> Appendix A. Protocol Encoding
>
> Syntactic Conventions
>
> This document uses the same syntactic conventions as the core X
> protocol encoding document.
>
>
> A.1 Common Types
>
> ┌───
> DRI3DRIVER
> 0x0 DRI3DriverDRI
> 0x1 DRI3DriverVDPAU
> └───
>
> Note that these match the DRI2 values.
>
> A.2 Protocol Requests
>
> ┌───
> DRI3QueryVersion
> 1 CARD8 major opcode
> 1 0 DRI3 opcode
> 2 3 length
> 4 CARD32 major version
> 4 CARD32 minor version
> ▶
> 1 1 Reply
> 1 unused
> 2 CARD16 sequence number
> 4 0 reply length
> 4 CARD32 major version
> 4 CARD32 minor version
> 16 unused
> └───
>
>
> ┌───
> DRI3Open
> 1 CARD8 major opcode
> 1 1 DRI3 opcode
> 2 4 length
> 4 DRAWABLE drawable
> 4 CARD32 driver type
> 4 PROVIDER provider
> ▶
> 1 1 Reply
> 1 1 nfd
> 2 CARD16 sequence number
> 4 (n + p) / 4 reply length
> 4 n driver name length (n)
> 20 unused
> n CARD8 driver name
> p unused, p=pad(n)
>
> 0 FD device
> └───
>
> ┌───
> DRI3PixmapFromBuffer
> 1 CARD8 major opcode
> 1 2 DRI3 opcode
> 2 6 length
> 4 Pixmap pixmap
> 4 Drawable drawable
> 4 CARD32 size
> 2 CARD16 width
> 2 CARD16 height
> 2 CARD16 stride
> 1 CARD8 depth
> 1 CARD8 bpp
>
> 0 FD buffer
> └───
>
> ┌───
> DRI3BufferFromPixmap
> 1 CARD8 major opcode
> 1 3 DRI3 opcode
> 2 2 length
> 4 Pixmap pixmap
> ▶
> 1 1 Reply
> 1 1 nfd
> 2 CARD16 sequence number
> 4 0 reply length
> 4 CARD32 size
> 2 CARD16 width
> 2 CARD16 height
> 2 CARD16 stride
> 1 CARD8 depth
> 1 CARD8 bpp
> 12 unused
>
> 0 FD buffer
> └───
>
> ┌───
> DRI3SelectInput
> 1 CARD8 major opcode
> 1 4 DRI3 opcode
> 2 3 length
> 4 Window window
> 4 CARD32 eid
> 4 CARD32 event mask
> └───
>
> ┌───
> DRI3FenceFromFD
> 1 CARD8 major opcode
> 1 5 DRI3 opcode
> 2 4 length
> 4 Drawable drawable
> 4 Fence fence
> 1 BOOL initially triggered
> 3 unused
>
> 0 FD fence fd
> └───
>
> A.3 Protocol Events
>
> ┌───
> RRScreenChangeNotify
> 1 35 XGE
> 1 CARD8 DRI3 extension opcode
> 2 CARD16 sequence number
> 4 2 length
> 2 0 DRI3ConfigureNotify
> 2 unused
> 4 CARD32 event id
> 4 Window window
> 2 INT16 x
> 2 INT16 y
> 2 CARD16 width
> 2 CARD16 height
> 2 INT16 off x
> 2 INT16 off y
> 2 CARD16 pixmap width
> 2 CARD16 pixmap height
> 4 CARD32 pixmap flags
> └───
>
> A.4 Protocol Errors
>
> The DRI3 extension defines no errors.
>
> ❄ ❄ ❄ ❄ ❄ ❄ ❄
>
> --
> keith.packard at intel.com
>
> * Unknown Key
> * 0xD693AF2A
>
More information about the xorg-devel
mailing list