1Buffer Sharing and Synchronization 2================================== 3 4The dma-buf subsystem provides the framework for sharing buffers for 5hardware (DMA) access across multiple device drivers and subsystems, and 6for synchronizing asynchronous hardware access. 7 8This is used, for example, by drm "prime" multi-GPU support, but is of 9course not limited to GPU use cases. 10 11The three main components of this are: (1) dma-buf, representing a 12sg_table and exposed to userspace as a file descriptor to allow passing 13between devices, (2) fence, which provides a mechanism to signal when 14one device as finished access, and (3) reservation, which manages the 15shared or exclusive fence(s) associated with the buffer. 16 17Shared DMA Buffers 18------------------ 19 20This document serves as a guide to device-driver writers on what is the dma-buf 21buffer sharing API, how to use it for exporting and using shared buffers. 22 23Any device driver which wishes to be a part of DMA buffer sharing, can do so as 24either the 'exporter' of buffers, or the 'user' or 'importer' of buffers. 25 26Say a driver A wants to use buffers created by driver B, then we call B as the 27exporter, and A as buffer-user/importer. 28 29The exporter 30 31 - implements and manages operations in :c:type:`struct dma_buf_ops 32 <dma_buf_ops>` for the buffer, 33 - allows other users to share the buffer by using dma_buf sharing APIs, 34 - manages the details of buffer allocation, wrapped int a :c:type:`struct 35 dma_buf <dma_buf>`, 36 - decides about the actual backing storage where this allocation happens, 37 - and takes care of any migration of scatterlist - for all (shared) users of 38 this buffer. 39 40The buffer-user 41 42 - is one of (many) sharing users of the buffer. 43 - doesn't need to worry about how the buffer is allocated, or where. 44 - and needs a mechanism to get access to the scatterlist that makes up this 45 buffer in memory, mapped into its own address space, so it can access the 46 same area of memory. This interface is provided by :c:type:`struct 47 dma_buf_attachment <dma_buf_attachment>`. 48 49Any exporters or users of the dma-buf buffer sharing framework must have a 50'select DMA_SHARED_BUFFER' in their respective Kconfigs. 51 52Userspace Interface Notes 53~~~~~~~~~~~~~~~~~~~~~~~~~ 54 55Mostly a DMA buffer file descriptor is simply an opaque object for userspace, 56and hence the generic interface exposed is very minimal. There's a few things to 57consider though: 58 59- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only 60 with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow 61 the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other 62 llseek operation will report -EINVAL. 63 64 If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all 65 cases. Userspace can use this to detect support for discovering the dma-buf 66 size using llseek. 67 68- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set 69 on the file descriptor. This is not just a resource leak, but a 70 potential security hole. It could give the newly exec'd application 71 access to buffers, via the leaked fd, to which it should otherwise 72 not be permitted access. 73 74 The problem with doing this via a separate fcntl() call, versus doing it 75 atomically when the fd is created, is that this is inherently racy in a 76 multi-threaded app[3]. The issue is made worse when it is library code 77 opening/creating the file descriptor, as the application may not even be 78 aware of the fd's. 79 80 To avoid this problem, userspace must have a way to request O_CLOEXEC 81 flag be set when the dma-buf fd is created. So any API provided by 82 the exporting driver to create a dmabuf fd must provide a way to let 83 userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd(). 84 85- Memory mapping the contents of the DMA buffer is also supported. See the 86 discussion below on `CPU Access to DMA Buffer Objects`_ for the full details. 87 88- The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for 89 details. 90 91Basic Operation and Device DMA Access 92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94.. kernel-doc:: drivers/dma-buf/dma-buf.c 95 :doc: dma buf device access 96 97CPU Access to DMA Buffer Objects 98~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 99 100.. kernel-doc:: drivers/dma-buf/dma-buf.c 101 :doc: cpu access 102 103Fence Poll Support 104~~~~~~~~~~~~~~~~~~ 105 106.. kernel-doc:: drivers/dma-buf/dma-buf.c 107 :doc: fence polling 108 109Kernel Functions and Structures Reference 110~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 112.. kernel-doc:: drivers/dma-buf/dma-buf.c 113 :export: 114 115.. kernel-doc:: include/linux/dma-buf.h 116 :internal: 117 118Reservation Objects 119------------------- 120 121.. kernel-doc:: drivers/dma-buf/reservation.c 122 :doc: Reservation Object Overview 123 124.. kernel-doc:: drivers/dma-buf/reservation.c 125 :export: 126 127.. kernel-doc:: include/linux/reservation.h 128 :internal: 129 130DMA Fences 131---------- 132 133.. kernel-doc:: drivers/dma-buf/dma-fence.c 134 :export: 135 136.. kernel-doc:: include/linux/dma-fence.h 137 :internal: 138 139Seqno Hardware Fences 140~~~~~~~~~~~~~~~~~~~~~ 141 142.. kernel-doc:: include/linux/seqno-fence.h 143 :internal: 144 145DMA Fence Array 146~~~~~~~~~~~~~~~ 147 148.. kernel-doc:: drivers/dma-buf/dma-fence-array.c 149 :export: 150 151.. kernel-doc:: include/linux/dma-fence-array.h 152 :internal: 153 154DMA Fence uABI/Sync File 155~~~~~~~~~~~~~~~~~~~~~~~~ 156 157.. kernel-doc:: drivers/dma-buf/sync_file.c 158 :export: 159 160.. kernel-doc:: include/linux/sync_file.h 161 :internal: 162 163