| 1 | ===================
|
| 2 | Sync File API Guide
|
| 3 | ===================
|
| 4 |
|
| 5 | :Author: Gustavo Padovan <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 dma_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
|
| 36 | dma_fence_signal(), when it has finished using (or processing) that buffer.
|
| 37 | Out-fences are fences 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'. Receiving 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 |
|
| 51 | struct sync_file *sync_file_create(struct dma_fence *fence);
|
| 52 |
|
| 53 | The caller pass the out-fence and gets back the sync_file. That is just the
|
| 54 | first step, next it needs to install an fd on sync_file->file. So it gets an
|
| 55 | fd::
|
| 56 |
|
| 57 | fd = get_unused_fd_flags(O_CLOEXEC);
|
| 58 |
|
| 59 | and installs it on sync_file->file::
|
| 60 |
|
| 61 | fd_install(fd, sync_file->file);
|
| 62 |
|
| 63 | The sync_file fd now can be sent to userspace.
|
| 64 |
|
| 65 | If the creation process fail, or the sync_file needs to be released by any
|
| 66 | other reason fput(sync_file->file) should be used.
|
| 67 |
|
| 68 | Receiving Sync Files from Userspace
|
| 69 | -----------------------------------
|
| 70 |
|
| 71 | When userspace needs to send an in-fence to the driver it passes file descriptor
|
| 72 | of the Sync File to the kernel. The kernel can then retrieve the fences
|
| 73 | from it.
|
| 74 |
|
| 75 | Interface::
|
| 76 |
|
| 77 | struct dma_fence *sync_file_get_fence(int fd);
|
| 78 |
|
| 79 |
|
| 80 | The returned reference is owned by the caller and must be disposed of
|
| 81 | afterwards using dma_fence_put(). In case of error, a NULL is returned instead.
|
| 82 |
|
| 83 | References:
|
| 84 |
|
| 85 | 1. struct sync_file in include/linux/sync_file.h
|
| 86 | 2. All interfaces mentioned above defined in include/linux/sync_file.h
|