blob: b63a68531afdedcab0944f9cd9b40742c9deac98
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 are needed to synchronize between drivers or |
10 | across 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 creates an 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 | Receiving Sync Files from Userspace |
68 | ----------------------------------- |
69 | |
70 | When userspace needs to send an in-fence to the driver it passes file descriptor |
71 | of the Sync File to the kernel. The kernel can then retrieve the fences |
72 | from it. |
73 | |
74 | Interface: |
75 | struct fence *sync_file_get_fence(int fd); |
76 | |
77 | |
78 | The returned reference is owned by the caller and must be disposed of |
79 | afterwards using fence_put(). In case of error, a NULL is returned instead. |
80 | |
81 | References: |
82 | [1] struct sync_file in include/linux/sync_file.h |
83 | [2] All interfaces mentioned above defined in include/linux/sync_file.h |
84 |