blob: a2d05e7fa1932a0fcb657c1521c4dd33470680be [file] [log] [blame]
Erik Gillingdd673382012-09-14 14:36:34 -07001Motivation:
2
3In complicated DMA pipelines such as graphics (multimedia, camera, gpu, display)
4a consumer of a buffer needs to know when the producer has finished producing
5it. Likewise the producer needs to know when the consumer is finished with the
6buffer so it can reuse it. A particular buffer may be consumed by multiple
7consumers which will retain the buffer for different amounts of time. In
8addition, a consumer may consume multiple buffers atomically.
9The sync framework adds an API which allows synchronization between the
10producers and consumers in a generic way while also allowing platforms which
11have shared hardware synchronization primitives to exploit them.
12
13Goals:
14 * provide a generic API for expressing synchronization dependencies
15 * allow drivers to exploit hardware synchronization between hardware
16 blocks
17 * provide a userspace API that allows a compositor to manage
18 dependencies.
19 * provide rich telemetry data to allow debugging slowdowns and stalls of
20 the graphics pipeline.
21
22Objects:
23 * sync_timeline
24 * sync_pt
25 * sync_fence
26
27sync_timeline:
28
29A sync_timeline is an abstract monotonically increasing counter. In general,
30each driver/hardware block context will have one of these. They can be backed
31by the appropriate hardware or rely on the generic sw_sync implementation.
32Timelines are only ever created through their specific implementations
33(i.e. sw_sync.)
34
35sync_pt:
36
37A sync_pt is an abstract value which marks a point on a sync_timeline. Sync_pts
38have a single timeline parent. They have 3 states: active, signaled, and error.
39They start in active state and transition, once, to either signaled (when the
40timeline counter advances beyond the sync_pt’s value) or error state.
41
42sync_fence:
43
44Sync_fences are the primary primitives used by drivers to coordinate
45synchronization of their buffers. They are a collection of sync_pts which may
46or may not have the same timeline parent. A sync_pt can only exist in one fence
47and the fence's list of sync_pts is immutable once created. Fences can be
48waited on synchronously or asynchronously. Two fences can also be merged to
49create a third fence containing a copy of the two fences’ sync_pts. Fences are
50backed by file descriptors to allow userspace to coordinate the display pipeline
51dependencies.
52
53Use:
54
55A driver implementing sync support should have a work submission function which:
56 * takes a fence argument specifying when to begin work
57 * asynchronously queues that work to kick off when the fence is signaled
58 * returns a fence to indicate when its work will be done.
59 * signals the returned fence once the work is completed.
60
61Consider an imaginary display driver that has the following API:
62/*
63 * assumes buf is ready to be displayed.
64 * blocks until the buffer is on screen.
65 */
66 void display_buffer(struct dma_buf *buf);
67
68The new API will become:
69/*
70 * will display buf when fence is signaled.
71 * returns immediately with a fence that will signal when buf
72 * is no longer displayed.
73 */
74struct sync_fence* display_buffer(struct dma_buf *buf,
75 struct sync_fence *fence);