aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorErik Gilling2012-09-14 16:36:34 -0500
committerArve Hjønnevåg2013-02-19 19:55:48 -0600
commitd51b8aba9392a580ee76def6be492d967d9c1b43 (patch)
tree5c13b3042f27b8c8a33e549123e78e3f1546bd5d /Documentation
parentfcba5c3a28847b39348ee9f9f634b7c5118cef01 (diff)
downloadkernel-common-d51b8aba9392a580ee76def6be492d967d9c1b43.tar.gz
kernel-common-d51b8aba9392a580ee76def6be492d967d9c1b43.tar.xz
kernel-common-d51b8aba9392a580ee76def6be492d967d9c1b43.zip
sync: add Documentation/sync.txt
Change-Id: Ic7f3a6d4622083be607b82ddd8d676609225bb8f Signed-off-by: Erik Gilling <konkers@android.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/sync.txt75
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/sync.txt b/Documentation/sync.txt
new file mode 100644
index 00000000000..a2d05e7fa19
--- /dev/null
+++ b/Documentation/sync.txt
@@ -0,0 +1,75 @@
1Motivation:
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);