1baa293e9SMauro Carvalho Chehab=================== 2baa293e9SMauro Carvalho ChehabSync File API Guide 3baa293e9SMauro Carvalho Chehab=================== 4baa293e9SMauro Carvalho Chehab 5baa293e9SMauro Carvalho Chehab:Author: Gustavo Padovan <gustavo at padovan dot org> 6baa293e9SMauro Carvalho Chehab 7baa293e9SMauro Carvalho ChehabThis document serves as a guide for device drivers writers on what the 8baa293e9SMauro Carvalho Chehabsync_file API is, and how drivers can support it. Sync file is the carrier of 9baa293e9SMauro Carvalho Chehabthe fences(struct dma_fence) that are needed to synchronize between drivers or 10baa293e9SMauro Carvalho Chehabacross process boundaries. 11baa293e9SMauro Carvalho Chehab 12baa293e9SMauro Carvalho ChehabThe sync_file API is meant to be used to send and receive fence information 13baa293e9SMauro Carvalho Chehabto/from userspace. It enables userspace to do explicit fencing, where instead 14baa293e9SMauro Carvalho Chehabof attaching a fence to the buffer a producer driver (such as a GPU or V4L 15baa293e9SMauro Carvalho Chehabdriver) sends the fence related to the buffer to userspace via a sync_file. 16baa293e9SMauro Carvalho Chehab 17baa293e9SMauro Carvalho ChehabThe sync_file then can be sent to the consumer (DRM driver for example), that 18baa293e9SMauro Carvalho Chehabwill not use the buffer for anything before the fence(s) signals, i.e., the 19baa293e9SMauro Carvalho Chehabdriver that issued the fence is not using/processing the buffer anymore, so it 20baa293e9SMauro Carvalho Chehabsignals that the buffer is ready to use. And vice-versa for the consumer -> 21baa293e9SMauro Carvalho Chehabproducer part of the cycle. 22baa293e9SMauro Carvalho Chehab 23baa293e9SMauro Carvalho ChehabSync files allows userspace awareness on buffer sharing synchronization between 24baa293e9SMauro Carvalho Chehabdrivers. 25baa293e9SMauro Carvalho Chehab 26baa293e9SMauro Carvalho ChehabSync file was originally added in the Android kernel but current Linux Desktop 27baa293e9SMauro Carvalho Chehabcan benefit a lot from it. 28baa293e9SMauro Carvalho Chehab 29baa293e9SMauro Carvalho Chehabin-fences and out-fences 30baa293e9SMauro Carvalho Chehab------------------------ 31baa293e9SMauro Carvalho Chehab 32baa293e9SMauro Carvalho ChehabSync files can go either to or from userspace. When a sync_file is sent from 33baa293e9SMauro Carvalho Chehabthe driver to userspace we call the fences it contains 'out-fences'. They are 34baa293e9SMauro Carvalho Chehabrelated to a buffer that the driver is processing or is going to process, so 35baa293e9SMauro Carvalho Chehabthe driver creates an out-fence to be able to notify, through 36baa293e9SMauro Carvalho Chehabdma_fence_signal(), when it has finished using (or processing) that buffer. 37baa293e9SMauro Carvalho ChehabOut-fences are fences that the driver creates. 38baa293e9SMauro Carvalho Chehab 39baa293e9SMauro Carvalho ChehabOn the other hand if the driver receives fence(s) through a sync_file from 40baa293e9SMauro Carvalho Chehabuserspace we call these fence(s) 'in-fences'. Receiving in-fences means that 41baa293e9SMauro Carvalho Chehabwe need to wait for the fence(s) to signal before using any buffer related to 42baa293e9SMauro Carvalho Chehabthe in-fences. 43baa293e9SMauro Carvalho Chehab 44baa293e9SMauro Carvalho ChehabCreating Sync Files 45baa293e9SMauro Carvalho Chehab------------------- 46baa293e9SMauro Carvalho Chehab 47baa293e9SMauro Carvalho ChehabWhen a driver needs to send an out-fence userspace it creates a sync_file. 48baa293e9SMauro Carvalho Chehab 49baa293e9SMauro Carvalho ChehabInterface:: 50baa293e9SMauro Carvalho Chehab 51baa293e9SMauro Carvalho Chehab struct sync_file *sync_file_create(struct dma_fence *fence); 52baa293e9SMauro Carvalho Chehab 53baa293e9SMauro Carvalho ChehabThe caller pass the out-fence and gets back the sync_file. That is just the 54baa293e9SMauro Carvalho Chehabfirst step, next it needs to install an fd on sync_file->file. So it gets an 55baa293e9SMauro Carvalho Chehabfd:: 56baa293e9SMauro Carvalho Chehab 57baa293e9SMauro Carvalho Chehab fd = get_unused_fd_flags(O_CLOEXEC); 58baa293e9SMauro Carvalho Chehab 59baa293e9SMauro Carvalho Chehaband installs it on sync_file->file:: 60baa293e9SMauro Carvalho Chehab 61baa293e9SMauro Carvalho Chehab fd_install(fd, sync_file->file); 62baa293e9SMauro Carvalho Chehab 63baa293e9SMauro Carvalho ChehabThe sync_file fd now can be sent to userspace. 64baa293e9SMauro Carvalho Chehab 65baa293e9SMauro Carvalho ChehabIf the creation process fail, or the sync_file needs to be released by any 66baa293e9SMauro Carvalho Chehabother reason fput(sync_file->file) should be used. 67baa293e9SMauro Carvalho Chehab 68baa293e9SMauro Carvalho ChehabReceiving Sync Files from Userspace 69baa293e9SMauro Carvalho Chehab----------------------------------- 70baa293e9SMauro Carvalho Chehab 71baa293e9SMauro Carvalho ChehabWhen userspace needs to send an in-fence to the driver it passes file descriptor 72baa293e9SMauro Carvalho Chehabof the Sync File to the kernel. The kernel can then retrieve the fences 73baa293e9SMauro Carvalho Chehabfrom it. 74baa293e9SMauro Carvalho Chehab 75baa293e9SMauro Carvalho ChehabInterface:: 76baa293e9SMauro Carvalho Chehab 77baa293e9SMauro Carvalho Chehab struct dma_fence *sync_file_get_fence(int fd); 78baa293e9SMauro Carvalho Chehab 79baa293e9SMauro Carvalho Chehab 80baa293e9SMauro Carvalho ChehabThe returned reference is owned by the caller and must be disposed of 81baa293e9SMauro Carvalho Chehabafterwards using dma_fence_put(). In case of error, a NULL is returned instead. 82baa293e9SMauro Carvalho Chehab 83baa293e9SMauro Carvalho ChehabReferences: 84baa293e9SMauro Carvalho Chehab 85baa293e9SMauro Carvalho Chehab1. struct sync_file in include/linux/sync_file.h 86baa293e9SMauro Carvalho Chehab2. All interfaces mentioned above defined in include/linux/sync_file.h 87