Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1390226

[PATCH v2 13/13] Documentation: add Sync File doc

Show all headers | View raw

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Add sync_file documentation on dma-buf-sync_file.txt
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/sync_file.txt | 69 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 Documentation/sync_file.txt

diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt
new file mode 100644
index 0000000..eaf8297
--- /dev/null
+++ b/Documentation/sync_file.txt
@@ -0,0 +1,69 @@
+			      Sync File API Guide
+			      ~~~~~~~~~~~~~~~~~~~
+
+				Gustavo Padovan
+			  <gustavo at padovan dot org>
+
+This document serves as a guide for device drivers writers on what the
+sync_file API is, and how drivers can support it. Sync file is the carrier of
+the fences(struct fence) that needs to synchronized between drivers or across
+process boundaries.
+
+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 a GPU or V4L
+driver) sends the fence related to the buffer to userspace via a sync_file.
+
+The sync_file then can be sent to the consumer (DRM driver for example), that
+will not use the buffer for anything before the fence(s) 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 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 an create out-fence 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(struct fence *fence);
+
+The caller pass 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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH v2 00/13] De-stage Sync File Framework Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 06/13] staging/android: remove name arg from sync_file_create() Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 08/13] staging/android: improve documentation for sync_file Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 11/13] dma-buf/sync_file: de-stage sync_file Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 04/13] staging/android: make sync_file_merge() static Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 07/13] staging/android: prepare sync_file for de-staging Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 12/13] Documentation: include sync_file into DocBook Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 02/13] staging/android: drop sync_file_install() and sync_file_put() Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 09/13] staging/android: style fix: alignment to match the open parenthesis Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 13/13] Documentation: add Sync File doc Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 15:50 +0200
  [PATCH v2 01/13] staging/android: remove redundant comments on sync_merge_data Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 16:00 +0200
  [PATCH v2 03/13] staging/android: move sync_file functions comments to sync.c Gustavo Padovan <gustavo@padovan.org> - 2016-04-28 16:00 +0200
  Re: [PATCH v2 00/13] De-stage Sync File Framework Greg Kroah-Hartman <gregkh@linuxfoundation.org> - 2016-04-30 02:40 +0200

csiph-web