Documentation/dma-buf-sharing.txt

   1                     DMA Buffer Sharing API Guide
   2                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4                             Sumit Semwal
   5                 <sumit dot semwal at linaro dot org>
   6                  <sumit dot semwal at ti dot com>
   7
   8 This document serves as a guide to device-driver writers on what is the dma-buf
   9 buffer sharing API, how to use it for exporting and using shared buffers.
  10
  11 Any device driver which wishes to be a part of DMA buffer sharing, can do so as
  12 either the 'exporter' of buffers, or the 'user' of buffers.
  13
  14 Say a driver A wants to use buffers created by driver B, then we call B as the
  15 exporter, and A as buffer-user.
  16
  17 The exporter
  18 - implements and manages operations[1] for the buffer
  19 - allows other users to share the buffer by using dma_buf sharing APIs,
  20 - manages the details of buffer allocation,
  21 - decides about the actual backing storage where this allocation happens,
  22 - takes care of any migration of scatterlist - for all (shared) users of this
  23    buffer,
  24 - optionally, provides mmap capability for drivers that need it.
  25
  26 The buffer-user
  27 - is one of (many) sharing users of the buffer.
  28 - doesn't need to worry about how the buffer is allocated, or where.
  29 - needs a mechanism to get access to the scatterlist that makes up this buffer
  30    in memory, mapped into its own address space, so it can access the same area
  31    of memory.
  32
  33
  34 The dma_buf buffer sharing API usage contains the following steps:
  35
  36 1. Exporter announces that it wishes to export a buffer
  37 2. Userspace gets the file descriptor associated with the exported buffer, and
  38    passes it around to potential buffer-users based on use case
  39 3. Each buffer-user 'connects' itself to the buffer
  40 4. When needed, buffer-user requests access to the buffer from exporter
  41 5. When finished with its use, the buffer-user notifies end-of-DMA to exporter
  42 6. when buffer-user is done using this buffer completely, it 'disconnects'
  43    itself from the buffer.
  44
  45
  46 1. Exporter's announcement of buffer export
  47
  48    The buffer exporter announces its wish to export a buffer. In this, it
  49    connects its own private buffer data, provides implementation for operations
  50    that can be performed on the exported dma_buf, and flags for the file
  51    associated with this buffer.
  52
  53    Interface:
  54       struct dma_buf *dma_buf_export(void *priv, struct dma_buf_ops *ops,
  55                                 int flags)
  56
  57    If this succeeds, dma_buf_export allocates a dma_buf structure, and returns a
  58    pointer to the same. It also associates an anonymous file with this buffer,
  59    so it can be exported. On failure to allocate the dma_buf object, it returns
  60    NULL.
  61
  62 2. Userspace gets a handle to pass around to potential buffer-users
  63
  64    Userspace entity requests for a file-descriptor (fd) which is a handle to the
  65    anonymous file associated with the buffer. It can then share the fd with other
  66    drivers and/or processes.
  67
  68    Interface:
  69       int dma_buf_fd(struct dma_buf *dmabuf)
  70
  71    This API installs an fd for the anonymous file associated with this buffer;
  72    returns either 'fd', or error.
  73
  74 3. Each buffer-user 'connects' itself to the buffer
  75
  76    Each buffer-user now gets a reference to the buffer, using the fd passed to
  77    it.
  78
  79    Interface:
  80       struct dma_buf *dma_buf_get(int fd)
  81
  82    This API will return a reference to the dma_buf, and increment refcount for
  83    it.
  84
  85    After this, the buffer-user needs to attach its device with the buffer, which
  86    helps the exporter to know of device buffer constraints.
  87
  88    Interface:
  89       struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf,
  90                                                 struct device *dev)
  91
  92    This API returns reference to an attachment structure, which is then used
  93    for scatterlist operations. It will optionally call the 'attach' dma_buf
  94    operation, if provided by the exporter.
  95
  96    The dma-buf sharing framework does the bookkeeping bits related to managing
  97    the list of all attachments to a buffer.
  98
  99 Until this stage, the buffer-exporter has the option to choose not to actually
 100 allocate the backing storage for this buffer, but wait for the first buffer-user
 101 to request use of buffer for allocation.
 102
 103
 104 4. When needed, buffer-user requests access to the buffer
 105
 106    Whenever a buffer-user wants to use the buffer for any DMA, it asks for
 107    access to the buffer using dma_buf_map_attachment API. At least one attach to
 108    the buffer must have happened before map_dma_buf can be called.
 109
 110    Interface:
 111       struct sg_table * dma_buf_map_attachment(struct dma_buf_attachment *,
 112                                          enum dma_data_direction);
 113
 114    This is a wrapper to dma_buf->ops->map_dma_buf operation, which hides the
 115    "dma_buf->ops->" indirection from the users of this interface.
 116
 117    In struct dma_buf_ops, map_dma_buf is defined as
 118       struct sg_table * (*map_dma_buf)(struct dma_buf_attachment *,
 119                                                 enum dma_data_direction);
 120
 121    It is one of the buffer operations that must be implemented by the exporter.
 122    It should return the sg_table containing scatterlist for this buffer, mapped
 123    into caller's address space.
 124
 125    If this is being called for the first time, the exporter can now choose to
 126    scan through the list of attachments for this buffer, collate the requirements
 127    of the attached devices, and choose an appropriate backing storage for the
 128    buffer.
 129
 130    Based on enum dma_data_direction, it might be possible to have multiple users
 131    accessing at the same time (for reading, maybe), or any other kind of sharing
 132    that the exporter might wish to make available to buffer-users.
 133
 134
 135 5. When finished, the buffer-user notifies end-of-DMA to exporter
 136
 137    Once the DMA for the current buffer-user is over, it signals 'end-of-DMA' to
 138    the exporter using the dma_buf_unmap_attachment API.
 139
 140    Interface:
 141       void dma_buf_unmap_attachment(struct dma_buf_attachment *,
 142                                     struct sg_table *);
 143
 144    This is a wrapper to dma_buf->ops->unmap_dma_buf() operation, which hides the
 145    "dma_buf->ops->" indirection from the users of this interface.
 146
 147    In struct dma_buf_ops, unmap_dma_buf is defined as
 148       void (*unmap_dma_buf)(struct dma_buf_attachment *, struct sg_table *);
 149
 150    unmap_dma_buf signifies the end-of-DMA for the attachment provided. Like
 151    map_dma_buf, this API also must be implemented by the exporter.
 152
 153
 154 6. when buffer-user is done using this buffer, it 'disconnects' itself from the
 155    buffer.
 156
 157    After the buffer-user has no more interest in using this buffer, it should
 158    disconnect itself from the buffer:
 159
 160    - it first detaches itself from the buffer.
 161
 162    Interface:
 163       void dma_buf_detach(struct dma_buf *dmabuf,
 164                           struct dma_buf_attachment *dmabuf_attach);
 165
 166    This API removes the attachment from the list in dmabuf, and optionally calls
 167    dma_buf->ops->detach(), if provided by exporter, for any housekeeping bits.
 168
 169    - Then, the buffer-user returns the buffer reference to exporter.
 170
 171    Interface:
 172      void dma_buf_put(struct dma_buf *dmabuf);
 173
 174    This API then reduces the refcount for this buffer.
 175
 176    If, as a result of this call, the refcount becomes 0, the 'release' file
 177    operation related to this fd is called. It calls the dmabuf->ops->release()
 178    operation in turn, and frees the memory allocated for dmabuf when exported.
 179
 180 NOTES:
 181 - Importance of attach-detach and {map,unmap}_dma_buf operation pairs
 182    The attach-detach calls allow the exporter to figure out backing-storage
 183    constraints for the currently-interested devices. This allows preferential
 184    allocation, and/or migration of pages across different types of storage
 185    available, if possible.
 186
 187    Bracketing of DMA access with {map,unmap}_dma_buf operations is essential
 188    to allow just-in-time backing of storage, and migration mid-way through a
 189    use-case.
 190
 191 - Migration of backing storage if needed
 192    If after
 193    - at least one map_dma_buf has happened,
 194    - and the backing storage has been allocated for this buffer,
 195    another new buffer-user intends to attach itself to this buffer, it might
 196    be allowed, if possible for the exporter.
 197
 198    In case it is allowed by the exporter:
 199     if the new buffer-user has stricter 'backing-storage constraints', and the
 200     exporter can handle these constraints, the exporter can just stall on the
 201     map_dma_buf until all outstanding access is completed (as signalled by
 202     unmap_dma_buf).
 203     Once all ongoing access is completed, the exporter could potentially move
 204     the buffer to the stricter backing-storage, and then allow further
 205     {map,unmap}_dma_buf operations from any buffer-user from the migrated
 206     backing-storage.
 207
 208    If the exporter cannot fulfil the backing-storage constraints of the new
 209    buffer-user device as requested, dma_buf_attach() would return an error to
 210    denote non-compatibility of the new buffer-sharing request with the current
 211    buffer.
 212
 213    If the exporter chooses not to allow an attach() operation once a
 214    map_dma_buf() API has been called, it simply returns an error.
 215
 216 - mmap file operation
 217    An mmap() file operation is provided for the fd associated with the buffer.
 218    If the exporter defines an mmap operation, the mmap() fop calls this to allow
 219    mmap for devices that might need it; if not, it returns an error.
 220
 221 References:
 222 [1] struct dma_buf_ops in include/linux/dma-buf.h
 223 [2] All interfaces mentioned above defined in include/linux/dma-buf.h