summaryrefslogtreecommitdiff
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorDave Airlie <airlied@redhat.com>2017-01-09 02:55:57 +0300
committerDave Airlie <airlied@redhat.com>2017-01-09 02:55:57 +0300
commit3806a271bf4be375f304e492148edb2507181158 (patch)
treecd1b2410e8a98e63e44c4cee058b2beeb1924cf4 /Documentation/driver-api
parenta121103c922847ba5010819a3f250f1f7fc84ab8 (diff)
parent9b8b75de4cb379187c481a5332a12429f31c0887 (diff)
downloadlinux-3806a271bf4be375f304e492148edb2507181158.tar.xz
Merge tag 'drm-misc-next-2016-12-30' of git://anongit.freedesktop.org/git/drm-misc into drm-next
First -misc pull for 4.11: - drm_mm rework + lots of selftests (Chris Wilson) - new connector_list locking+iterators - plenty of kerneldoc updates - format handling rework from Ville - atomic helper changes from Maarten for better plane corner-case handling in drivers, plus the i915 legacy cursor patch that needs this - bridge cleanup from Laurent - plus plenty of small stuff all over - also contains a merge of the 4.10 docs tree so that we could apply the dma-buf kerneldoc patches It's a lot more than usual, but due to the merge window blackout it also covers about 4 weeks, so all in line again on a per-week basis. The more annoying part with no pull request for 4 weeks is managing cross-tree work. The -intel pull request I'll follow up with does conflict quite a bit with -misc here. Longer-term (if drm-misc keeps growing) a drm-next-queued to accept pull request for the next merge window during this time might be useful. I'd also like to backmerge -rc2+this into drm-intel next week, we have quite a pile of patches waiting for the stuff in here. * tag 'drm-misc-next-2016-12-30' of git://anongit.freedesktop.org/git/drm-misc: (126 commits) drm: Add kerneldoc markup for new @scan parameters in drm_mm drm/mm: Document locking rules drm: Use drm_mm_insert_node_in_range_generic() for everyone drm: Apply range restriction after color adjustment when allocation drm: Wrap drm_mm_node.hole_follows drm: Apply tight eviction scanning to color_adjust drm: Simplify drm_mm scan-list manipulation drm: Optimise power-of-two alignments in drm_mm_scan_add_block() drm: Compute tight evictions for drm_mm_scan drm: Fix application of color vs range restriction when scanning drm_mm drm: Unconditionally do the range check in drm_mm_scan_add_block() drm: Rename prev_node to hole in drm_mm_scan_add_block() drm: Fix O= out-of-tree builds for selftests drm: Extract struct drm_mm_scan from struct drm_mm drm: Add asserts to catch overflow in drm_mm_init() and drm_mm_init_scan() drm: Simplify drm_mm_clean() drm: Detect overflow in drm_mm_reserve_node() drm: Fix kerneldoc for drm_mm_scan_remove_block() drm: Promote drm_mm alignment to u64 drm: kselftest for drm_mm and restricted color eviction ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/dma-buf.rst92
1 files changed, 92 insertions, 0 deletions
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index a9b457a4b949..31671b469627 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -17,6 +17,98 @@ shared or exclusive fence(s) associated with the buffer.
Shared DMA Buffers
------------------
+This document serves as a guide to device-driver writers on what is the dma-buf
+buffer sharing API, how to use it for exporting and using shared buffers.
+
+Any device driver which wishes to be a part of DMA buffer sharing, can do so as
+either the 'exporter' of buffers, or the 'user' or 'importer' of buffers.
+
+Say a driver A wants to use buffers created by driver B, then we call B as the
+exporter, and A as buffer-user/importer.
+
+The exporter
+
+ - implements and manages operations in :c:type:`struct dma_buf_ops
+ <dma_buf_ops>` for the buffer,
+ - allows other users to share the buffer by using dma_buf sharing APIs,
+ - manages the details of buffer allocation, wrapped int a :c:type:`struct
+ dma_buf <dma_buf>`,
+ - decides about the actual backing storage where this allocation happens,
+ - and takes care of any migration of scatterlist - for all (shared) users of
+ this buffer.
+
+The buffer-user
+
+ - is one of (many) sharing users of the buffer.
+ - doesn't need to worry about how the buffer is allocated, or where.
+ - and needs a mechanism to get access to the scatterlist that makes up this
+ buffer in memory, mapped into its own address space, so it can access the
+ same area of memory. This interface is provided by :c:type:`struct
+ dma_buf_attachment <dma_buf_attachment>`.
+
+Any exporters or users of the dma-buf buffer sharing framework must have a
+'select DMA_SHARED_BUFFER' in their respective Kconfigs.
+
+Userspace Interface Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mostly a DMA buffer file descriptor is simply an opaque object for userspace,
+and hence the generic interface exposed is very minimal. There's a few things to
+consider though:
+
+- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only
+ with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow
+ the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other
+ llseek operation will report -EINVAL.
+
+ If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all
+ cases. Userspace can use this to detect support for discovering the dma-buf
+ size using llseek.
+
+- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set
+ on the file descriptor. This is not just a resource leak, but a
+ potential security hole. It could give the newly exec'd application
+ access to buffers, via the leaked fd, to which it should otherwise
+ not be permitted access.
+
+ The problem with doing this via a separate fcntl() call, versus doing it
+ atomically when the fd is created, is that this is inherently racy in a
+ multi-threaded app[3]. The issue is made worse when it is library code
+ opening/creating the file descriptor, as the application may not even be
+ aware of the fd's.
+
+ To avoid this problem, userspace must have a way to request O_CLOEXEC
+ flag be set when the dma-buf fd is created. So any API provided by
+ the exporting driver to create a dmabuf fd must provide a way to let
+ userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd().
+
+- Memory mapping the contents of the DMA buffer is also supported. See the
+ discussion below on `CPU Access to DMA Buffer Objects`_ for the full details.
+
+- The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for
+ details.
+
+Basic Operation and Device DMA Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
+ :doc: dma buf device access
+
+CPU Access to DMA Buffer Objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
+ :doc: cpu access
+
+Fence Poll Support
+~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
+ :doc: fence polling
+
+Kernel Functions and Structures Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
.. kernel-doc:: drivers/dma-buf/dma-buf.c
:export: