tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: add Sync File doc
Add sync_file documentation on dma-buf-sync_file.txt
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Gustavo Padovan
and committed by
Greg Kroah-Hartman
c784c82a
5b996e93
+69
+69
Documentation/sync_file.txt
+69
Documentation/sync_file.txt
···
1
+
Sync File API Guide
2
+
~~~~~~~~~~~~~~~~~~~
3
+
4
+
Gustavo Padovan
5
+
<gustavo at padovan dot org>
6
+
7
+
This document serves as a guide for device drivers writers on what the
8
+
sync_file API is, and how drivers can support it. Sync file is the carrier of
9
+
the fences(struct fence) that needs to synchronized between drivers or across
10
+
process boundaries.
11
+
12
+
The sync_file API is meant to be used to send and receive fence information
13
+
to/from userspace. It enables userspace to do explicit fencing, where instead
14
+
of attaching a fence to the buffer a producer driver (such as a GPU or V4L
15
+
driver) sends the fence related to the buffer to userspace via a sync_file.
16
+
17
+
The sync_file then can be sent to the consumer (DRM driver for example), that
18
+
will not use the buffer for anything before the fence(s) signals, i.e., the
19
+
driver that issued the fence is not using/processing the buffer anymore, so it
20
+
signals that the buffer is ready to use. And vice-versa for the consumer ->
21
+
producer part of the cycle.
22
+
23
+
Sync files allows userspace awareness on buffer sharing synchronization between
24
+
drivers.
25
+
26
+
Sync file was originally added in the Android kernel but current Linux Desktop
27
+
can benefit a lot from it.
28
+
29
+
in-fences and out-fences
30
+
------------------------
31
+
32
+
Sync files can go either to or from userspace. When a sync_file is sent from
33
+
the driver to userspace we call the fences it contains 'out-fences'. They are
34
+
related to a buffer that the driver is processing or is going to process, so
35
+
the driver an create out-fence to be able to notify, through fence_signal(),
36
+
when it has finished using (or processing) that buffer. Out-fences are fences
37
+
that the driver creates.
38
+
39
+
On the other hand if the driver receives fence(s) through a sync_file from
40
+
userspace we call these fence(s) 'in-fences'. Receiveing in-fences means that
41
+
we need to wait for the fence(s) to signal before using any buffer related to
42
+
the in-fences.
43
+
44
+
Creating Sync Files
45
+
-------------------
46
+
47
+
When a driver needs to send an out-fence userspace it creates a sync_file.
48
+
49
+
Interface:
50
+
struct sync_file *sync_file_create(struct fence *fence);
51
+
52
+
The caller pass the out-fence and gets back the sync_file. That is just the
53
+
first step, next it needs to install an fd on sync_file->file. So it gets an
54
+
fd:
55
+
56
+
fd = get_unused_fd_flags(O_CLOEXEC);
57
+
58
+
and installs it on sync_file->file:
59
+
60
+
fd_install(fd, sync_file->file);
61
+
62
+
The sync_file fd now can be sent to userspace.
63
+
64
+
If the creation process fail, or the sync_file needs to be released by any
65
+
other reason fput(sync_file->file) should be used.
66
+
67
+
References:
68
+
[1] struct sync_file in include/linux/sync_file.h
69
+
[2] All interfaces mentioned above defined in include/linux/sync_file.h