From: Gustavo Padovan <gustavo.padovan@xxxxxxxxxxxxxxx> Add sync_file documentation on dma-buf-sync_file.txt --- Documentation/dma-buf-sync_file.txt | 65 +++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/dma-buf-sync_file.txt diff --git a/Documentation/dma-buf-sync_file.txt b/Documentation/dma-buf-sync_file.txt new file mode 100644 index 0000000..aa7320f --- /dev/null +++ b/Documentation/dma-buf-sync_file.txt @@ -0,0 +1,65 @@ + DMA Buffer Sync File API Guide + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Gustavo Padovan + <gustavo at padovan dot org> + +This document serves as a guide for device drivers writers on what is the +dma-buf sync_file API, and how drivers can support it. Sync file is the +carrier of the fences(struct fence) that needs to synchronized between drivers. + +The sync_file API is meant to be used to send and receive fence information +to/from userspace. It enables userspace to do explicit fencing, where instead +of attaching a fence to the buffer a Producer driver (such as GPU or V4L +driver) it sends the fence related to the buffer to userspace. The fence then +can be sent to the Consumer (DRM driver for example), that will not use the +buffer for anything before the fence signals, i.e., the driver that issued the +fence is not using/processing the buffer anymore, so it signals that the buffer +is ready to use. And vice-versa for the Consumer -> Producer part of the cycle. +Sync files allows userspace awareness on the DMA buffer sharing synchronization +between drivers. + +Sync file was originally added in the Android kernel but current Linux Desktop +can benefit a lot from it. + +in-fences and out-fences +------------------------ + +Sync files can go either to or from userspace. When a sync_file is sent from +the driver to userspace we call the fences it contains 'out-fences'. They are +related to a buffer that the driver is processing or is going to process, so +the driver create out-fences to be able to notify, through fence_signal(), when +it has finished using (or processing) that buffer. Out-fences are fences that +the driver creates. + +On the other hand if the driver receives fence(s) through a sync_file from +userspace we call these fence(s) 'in-fences'. Receiveing in-fences means that +we need to wait for the fence(s) to signal before using any buffer related to +the in-fences. + +Creating Sync Files +------------------- + +When a driver needs to send an out-fence userspace it creates a sync_file. + +Interface: + struct sync_file *sync_file_create(const char *name, struct fence *fence); + +The caller pass the name and the out-fence and gets back the sync_file. That is +just the first step, next it needs to install an fd on sync_file->file. So it +gets an fd: + + fd = get_unused_fd_flags(O_CLOEXEC); + +and installs it on sync_file->file: + + fd_install(fd, sync_file->file); + +The sync_file fd now can be sent to userspace. + +If the creation process fail, or the sync_file needs to be released by any +other reason fput(sync_file->file) should be used. + +References: +[1] struct sync_file in include/linux/sync_file.h +[2] All interfaces mentioned above defined in include/linux/sync_file.h -- 2.5.5 _______________________________________________ devel mailing list devel@xxxxxxxxxxxxxxxxxxxxxx http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
