display:Buffer Sharing and Synchronization

Buffer Sharing and Synchronization

dma-buf子系统提供了用于在多个设备驱动程序和子系统之间共享用于硬件（DMA）访问的缓冲区以及用于同步异步硬件访问的框架。

例如，drm的“prime”多GPU支持可使用此功能，但当然不限于GPU用例。

它的三个主要组成部分是：（1）dma-buf，表示一个sg_table，并作为文件描述符公开给用户空间，以允许在设备之间传递；（2）fence，该机制提供了一种机制，用于在一个设备完成访问时发出信号， （3）保留，它管理与缓冲区关联的共享或专用fence。

NOTE：

• dma-buf 的出现就是为了解决各个驱动之间 buffer 共享的问题，因此它本质上是 buffer 与 file 的结合，即 dma-buf 既是块物理 buffer，又是个 linux file。buffer 是内容，file 是媒介，只有通过 file 这个媒介才能实现同一 buffer 在不同驱动之间的流转。
• dma-buf 和 iommu 驱动本身就是相互独立的，不应该把 dma-buf 和 iommu 在概念上关联起来。iommu 驱动的核心是你给它一个sgtable，它返回给你一段连续的 device 虚拟地址。而 dma-buf 的 map attachment 接口就是用来获取共享内存的 sgtable 的。因此如果想通过 SMMU 来访问这段共享内存，只需要实现好 dma-buf 的 map_dma_buf callback 函数就可以了，即返回正确的 sgtable 即可。至于 SMMU 如何将这个 sgtable 映射到设备虚拟地址上，是 SMMU 驱动人员应该关心的问题。

———————————————— 版权声明：本文为CSDN博主「何小龙」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。 原文链接：https://blog.csdn.net/hexiaolong2009/article/details/102596744

Shared DMA Buffers

本文档为设备驱动程序编写者提供了有关什么是dma-buf缓冲区共享API，如何将其用于导出和使用共享缓冲区的指南。

任何希望成为DMA缓冲区共享一部分的设备驱动程序都可以作为缓冲区的“导出器Exporter”或缓冲区的“用户user”或“导入器Importer”来实现。

假设驱动程序A要使用驱动程序B创建的缓冲区，那么我们将B称为导出器exporter，将A称为缓冲区用户/导入器importer。

The exporter

• implements and manages operations in struct dma_buf_ops for the buffer, ---实现和管理dma_buf_ops结构的操作，

• allows other users to share the buffer by using dma_buf sharing APIs,---允许其他用户通过使用dma_buf共享api共享缓冲区，

• manages the details of buffer allocation, wrapped in a 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.---并负责对该缓冲区的所有(共享)用户的scatterlist的任何迁移。上文提到的sgtable，wowo的文章里有详细描述

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 struct dma_buf_attachment.

• ---并且需要一种机制来访问组成内存缓冲区的scatterlist，映射到它自己的地址空间，这样它就可以访问相同的内存区域。该接口由结构体dma_buf_attachment提供。

任何dma-buf缓冲区共享框架的导出器exporter或用户user/importer必须在他们各自的kconfig中有一个' select DMA_SHARED_BUFFER '。

Userspace Interface Notes

通常，DMA缓冲区文件描述符只是用户空间的不透明对象，因此公开的通用接口非常少。不过，您需要考虑以下几点：

• 从内核3.12开始，dma-buf FD支持llseek系统调用，但仅具有offset = 0和whence = SEEK_END | SEEK_SET的情况。支持SEEK_SET，以允许通常的大小发现模式大小= SEEK_END（0）; SEEK_SET（0）。每隔llseek操作将报告-EINVAL。如果不支持dma-buf FD的llseek，则内核将在所有情况下报告-ESPIPE。用户空间可以使用它来检测对使用llseek发现dma-buf大小的支持。

• 为了避免exec上的fd泄漏，必须在文件描述符上设置FD_CLOEXEC标志。这不仅是资源泄漏，而且是潜在的安全漏洞。它可以使新执行的应用程序通过泄漏的fd访问缓冲区，否则不应允许对其进行访问。通过单独的fcntl（）调用进行此操作（与在创建fd时原子地进行操作相比）的问题是，这在多线程应用程序中固有地不合理[3]。当库代码打开/创建文件描述符时，这个问题变得更加严重，因为应用程序甚至可能不知道fd。为避免此问题，在创建dma-buf fd时，用户空间必须有一种方法可以请求设置O_CLOEXEC标志。因此，由导出驱动程序提供的用于创建dmabuf fd的任何API都必须提供一种方法，让用户空间控制传递给dma_buf_fd()的O_CLOEXEC标志设置。

• 支持对DMA缓冲区内容的内存映射。关于CPU访问DMA Buffer对象的详细信息，请参阅下面的讨论。

• DMA缓冲区FD也是可轮询的，有关详细信息，请参阅下面的隐式栅栏轮询支持。

Basic Operation and Device DMA Access

对于设备DMA访问一个共享的DMA缓冲区，通常的操作序列是相当简单的:

1. The exporter defines his exporter instance using DEFINE_DMA_BUF_EXPORT_INFO() and calls dma_buf_export() to wrap a private buffer object into a dma_buf. It then exports that dma_buf to userspace as a file descriptor by calling dma_buf_fd().

   1. 导出器使用DEFINE_DMA_BUF_EXPORT_INFO()定义自己的导出器实例，并调用dma_buf_export()将私有缓冲区对象包装到dma_buf中。然后通过调用dma_buf_fd()将dma_buf作为文件描述符导出到用户空间。

2. Userspace passes this file-descriptors to all drivers it wants this buffer to share with: First the filedescriptor is converted to a dma_buf using dma_buf_get(). Then the buffer is attached to the device using dma_buf_attach().Up to this stage the exporter is still free to migrate or reallocate the backing storage.

   1. 用户空间将这个文件描述符传递给想要与此缓冲区共享的所有驱动程序:首先，使用dma_buf_get()将文件描述符转换为dma_buf。然后使用dma_buf_attach()将缓冲区附加到设备上。到目前为止，出口商仍然可以自由地迁移或重新分配后备存储器。

3. Once the buffer is attached to all devices userspace can initiate DMA access to the shared buffer. In the kernel this is done by calling dma_buf_map_attachment() and dma_buf_unmap_attachment().

   1. 一旦缓冲区连接到所有设备上，用户空间就可以发起对共享缓冲区的DMA访问。在内核中，这是通过调用dma_buf_map_attachment()和dma_buf_unmap_attachment()来实现的。

4. Once a driver is done with a shared buffer it needs to call dma_buf_detach() (after cleaning up any mappings) and then release the reference acquired with dma_buf_get() by calling dma_buf_put().

   1. 一旦驱动程序使用共享缓冲区完成，它需要调用dma_buf_detach()(在清除所有映射之后)，然后通过调用dma_buf_put()释放dma_buf_get()获得的引用。

对于详细的语义，导出器将实现参见dma_buf_ops。

CPU Access to DMA Buffer Objects

支持CPU访问dma缓冲区对象有多种原因：

• 内核中的后备操作，例如，当设备通过USB连接时，内核需要先将数据随机排序，然后再发送出去。缓存一致性是通过调用dma_buf_begin_cpu_access()和dma_buf_end_cpu_access()访问来处理的。

  由于大多数内核内部dma-buf访问都需要整个缓冲区，因此引入了vmap接口。请注意，在非常老的32位体系结构上，vmalloc空间可能会受到限制，并导致vmap调用失败。

  接口：

  void *dma_buf_vmap(struct dma_buf *dmabuf)
  void dma_buf_vunmap(struct dma_buf *dmabuf, void *vaddr)

  如果导出器中不支持vmap或vmalloc空间用尽，则vmap调用可能会失败。请注意，dma-buf层会保留所有vmap访问的引用计数，并且仅当不存在vmapping时才调用导出器的vmap函数，并且仅取消映射一次。通过使用互斥锁dma_buf.lock，可以防止并发vmap / vunmap调用。

• 为了使导入器端与现有的用户空间接口完全兼容，该接口可能已经支持mmap'ing缓冲区。这在许多处理管道中都是需要的（例如，将软件渲染的图像馈送到硬件管道，缩略图创建，快照等）。同样，Android的ION框架已经支持此功能，并且对于DMA缓冲区文件描述符来取代ION缓冲区mmap支持是必要的。没有特殊的接口，用户空间只需在dma-buf fd上调用mmap。但是像CPU访问一样，需要阻止实际访问，这由ioctl（DMA_BUF _IOCTL_SYNC）处理。请注意，DMA_BUF_IOCTL_SYNC可能会因-EAGAIN或-EINTR失败，在这种情况下必须重新启动。某些系统可能需要某种缓存一致性管理，例如，同时通过dma-buf访问CPU和GPU域时。为避免此问题，有开始/结束一致性标记，它们直接转发到现有的dma-buf设备驱动程序vfunc挂钩。用户空间可以通过DMA_BUF _IOCTL_SYNC ioctl使用这些标记。该序列将如下使用：

  • mmap dma-buf fd

  • for each drawing/upload cycle in CPU 1. SYNC_START ioctl, 2. read/write to mmap area 3. SYNC_END ioctl. This can be repeated as often as you want (with the new data being consumed by say the GPU or the scanout device)

  • munmap once you don’t need the buffer any more

  为了确保正确性和最佳性能，在访问映射地址时，始终需要分别在之前和之后使用SYNC_START和SYNC_END。用户空间不能依赖于一致的访问，即使在某些系统中它可以在不调用这些ioctl的情况下正常工作。 

• 355 static long dma_buf_ioctl(struct file *file,
  356 			  unsigned int cmd, unsigned long arg)
  357 {
  358 	struct dma_buf *dmabuf;
  359 	struct dma_buf_sync sync;
  360 	enum dma_data_direction direction;
  361 	int ret;
  362 
  363 	dmabuf = file->private_data;
  364 
  365 	switch (cmd) {
  366 	case DMA_BUF_IOCTL_SYNC:
  367 		if (copy_from_user(&sync, (void __user *) arg, sizeof(sync)))
  368 			return -EFAULT;
  369 
  370 		if (sync.flags & ~DMA_BUF_SYNC_VALID_FLAGS_MASK)
  371 			return -EINVAL;
  372 
  373 		switch (sync.flags & DMA_BUF_SYNC_RW) {
  374 		case DMA_BUF_SYNC_READ:
  375 			direction = DMA_FROM_DEVICE;
  376 			break;
  377 		case DMA_BUF_SYNC_WRITE:
  378 			direction = DMA_TO_DEVICE;
  379 			break;
  380 		case DMA_BUF_SYNC_RW:
  381 			direction = DMA_BIDIRECTIONAL;
  382 			break;
  383 		default:
  384 			return -EINVAL;
  385 		}
  386 
  387 		if (sync.flags & DMA_BUF_SYNC_END)
  388 			ret = dma_buf_end_cpu_access(dmabuf, direction);
  389 		else
  390 			ret = dma_buf_begin_cpu_access(dmabuf, direction);
  391 
  392 		return ret;
  393 
  394 	case DMA_BUF_SET_NAME:
  395 		return dma_buf_set_name(dmabuf, (const char __user *)arg);
  396 
  397 	default:
  398 		return -ENOTTY;
  399 	}
  400 }

  根据实现可以看到，最终还是dma_buf_begin_cpu_access()和dma_buf_end_cpu_access()

• 并且作为用户空间处理管道中的CPU后备。类似于内核cpu访问的动机，同样重要的是，给定导入子系统的用户空间代码可以对导入的dma-buf缓冲区对象使用与本机缓冲区对象相同的接口。这对于drm尤其重要，因为drm中当代OpenGL，X和其他驱动程序的用户空间部分很大，因此需要对其进行重新加工以使用另一种方法来映射具有相当侵入性的缓冲区。当前dma-buf接口中的假设是仅需要重定向初始mmap。对一些现有子系统的调查显示，没有驱动程序似乎做任何邪恶的事情，例如与设备上出色的异步处理同步或在故障时分配特殊资源。因此，希望这已经足够好了，因为添加接口来拦截页面错误并允许pte击落会大大增加复杂性。

  接口：

  int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *,
                 unsigned long);

  如果导入子系统只是提供了一个特殊用途的mmap调用来在用户空间中建立映射，则使用dma_buf调用do_mmap。对于dma-buf对象，file将同样实现这一点。

   

  Implicit Fence Poll Support

  为了支持跨设备和跨驱动程序的缓冲区访问同步，可以将隐式fence(在内核内部用结构体dma_fence表示)附加到dma_buf上。dma_resv结构中提供了它和一些相关的东西。

  用户空间可以使用poll()和相关的系统调用来查询这些隐式跟踪的fence的状态:

   

  • 检查EPOLLIN，即读访问，可以用来查询最近的写或独占的fence状态。
  • 检查EPOLLOUT，即写访问，可以用来查询所有附加的、共享的和独占的fence的状态。

  注意，这只表示完成了各自的fences，即DMA传输完成。在开始CPU访问之前，缓存刷新和任何其他必要的准备工作仍然需要进行。

   

   

  Kernel Functions and Structures Reference

  https://www.kernel.org/doc/html/latest/driver-api/dma-buf.html?highlight=dma_buf#kernel-functions-and-structures-reference

  DMA Fences

  DMA fence由结构体dma_fence表示，是用于DMA操作的内核内部同步原语，如GPU渲染、视频编码/解码或在屏幕上显示缓冲区。

  fence使用dma_fence_init()初始化，并使用dma_fence_signal()完成。fence与上下文相关联，通过dma_fence_context_alloc()分配，同一个上下文上的所有fence都是完全排序的。
  因为fences的目的是为了促进跨设备和跨应用的同步，所以可以通过多种方式来使用它:

   

  • Individual fences can be exposed as a sync_file, accessed as a file descriptor from userspace, created by calling sync_file_create(). This is called explicit fencing, since userspace passes around explicit synchronization points.---单独的fence可以作为sync_file公开，通过调用sync_file_create()创建，并从用户空间中作为文件描述符访问。这被称为显式隔离，因为用户空间传递显式同步点。
  • Some subsystems also have their own explicit fencing primitives, like drm_syncobj. Compared to sync_file, a drm_syncobj allows the underlying fence to be updated.---一些子系统也有自己的显式fencing原语，如drm_syncobj。与sync_file相比，drm_syncobj允许更新底层fence。
  • Then there’s also implicit fencing, where the synchronization points are implicitly passed around as part of shared dma_buf instances. Such implicit fences are stored in struct dma_resv through the dma_buf.resv pointer.---还有一种隐式fence，同步点作为共享dma_buf实例的一部分隐式传递。这样的隐式fence通过dma_buf存储在结构体dma_resv中的dma_buf.resv pointer.。

  DMA Fence Cross-Driver Contract

  由于dma_fence提供了一个交叉驱动协议，所有的驱动必须遵循相同的规则:

   

  • Fences must complete in a reasonable time. Fences which represent kernels and shaders submitted by userspace, which could run forever, must be backed up by timeout and gpu hang recovery code. Minimally that code must prevent further command submission and force complete all in-flight fences, e.g. when the driver or hardware do not support gpu reset, or if the gpu reset failed for some reason. Ideally the driver supports gpu recovery which only affects the offending userspace context, and no other userspace submissions.
    • ---fence必须在合理的时间内完成。fence代表用户空间内核和着色器的提交，可以永远运行，fence必须通过超时和gpu挂起的恢复代码进行备份。最低限度，该代码必须防止进一步的命令提交，并强制完成所有飞行[运行]中的fence，例如当驱动程序或硬件不支持gpu重置，或gpu重置因某些原因失败时。理想情况下，驱动程序支持gpu恢复，这只影响违规的用户空间上下文，而没有其他用户空间提交。
  • Drivers may have different ideas of what completion within a reasonable time means. Some hang recovery code uses a fixed timeout, others a mix between observing forward progress and increasingly strict timeouts. Drivers should not try to second guess timeout handling of fences from other drivers.
    • 驱动可能对”在合理时间内完成意味着什么“有不同的想法。一些挂起恢复代码使用固定的超时，另一些则在观察前进的进程和越来越严格的超时之间混合。驱动不应该试图从其他驱动猜测超时处理fence。
  • To ensure there’s no deadlocks of dma_fence_wait() against other locks drivers should annotate all code required to reach dma_fence_signal(), which completes the fences, with dma_fence_begin_signalling() and dma_fence_end_signalling().
    • 为了确保dma_fence_wait()对其他锁没有死锁，驱动程序应该注释到达dma_fence_signal()所需的所有代码，用dma_fence_begin_signalling()和dma_fence_end_signalling()完成fence。
  • Drivers are allowed to call dma_fence_wait() while holding dma_resv_lock(). This means any code required for fence completion cannot acquire a dma_resv lock. Note that this also pulls in the entire established locking hierarchy around dma_resv_lock() and dma_resv_unlock().
    • 允许驱动程序在持有dma_resv_lock()的同时调用dma_fence_wait()。这意味着fence完成所需的任何代码都不能获得dma_resv lock。注意，这还会引入围绕dma_resv_lock()和dma_resv_unlock()建立的整个锁定层次结构。
  • Drivers are allowed to call dma_fence_wait() from their shrinker callbacks. This means any code required for fence completion cannot allocate memory with GFP_KERNEL.
    • 允许驱动程序从他们的shrinker回调函数中调用dma_fence_wait()。这意味着任何fence完成所需的代码都不能使用GFP_KERNEL分配内存。
  • Drivers are allowed to call dma_fence_wait() from their mmu_notifier respectively mmu_interval_notifier callbacks. This means any code required for fence completeion cannot allocate memory with GFP_NOFS or GFP_NOIO. Only GFP_ATOMIC is permissible, which might fail.
    • 驱动程序可以分别从它们的mmu_notifier回调函数， mmu_interval_notifier回调函数中调用dma_fence_wait()。这意味着任何fence完成所需的代码都不能使用GFP_NOFS或GFP_NOIO分配内存。只允许GFP_ATOMIC，这可能会失败。

  注意，只有GPU驱动程序有合理的理由同时需要mmu_interval_notifier和shrinker回调函数，因为必须使用dma_fence来跟踪异步计算工作。在这种情况下，驱动程序/gpu之外的任何驱动程序都不应该调用dma_fence_wait()。

  DMA Fence Signalling Annotations

  通过代码审查和测试来证明所有围绕dma_fence的内核代码的正确性是很棘手的，原因如下:

   

  • It is a cross-driver contract, and therefore all drivers must follow the same rules for lock nesting order, calling contexts for various functions and anything else significant for in-kernel interfaces. But it is also impossible to test all drivers in a single machine, hence brute-force N vs. N testing of all combinations is impossible. Even just limiting to the possible combinations is infeasible.
  • There is an enormous amount of driver code involved. For render drivers there’s the tail of command submission, after fences are published, scheduler code, interrupt and workers to process job completion, and timeout, gpu reset and gpu hang recovery code. Plus for integration with core mm with have mmu_notifier, respectively mmu_interval_notifier, and shrinker. For modesetting drivers there’s the commit tail functions between when fences for an atomic modeset are published, and when the corresponding vblank completes, including any interrupt processing and related workers. Auditing all that code, across all drivers, is not feasible.
  • Due to how many other subsystems are involved and the locking hierarchies this pulls in there is extremely thin wiggle-room for driver-specific differences. dma_fence interacts with almost all of the core memory handling through page fault handlers via dma_resv, dma_resv_lock() and dma_resv_unlock(). On the other side it also interacts through all allocation sites through mmu_notifier and shrinker.

  此外，lockdep不处理交叉发布依赖关系，这意味着dma_fence_wait()和dma_fence_signal()之间的任何死锁都不能通过一些快速测试在运行时捕获。最简单的例子是一个线程在持有锁时等待dma_fence:

  lock(A);
  dma_fence_wait(B);
  unlock(A);

  当另一个线程试图获取相同的锁时，这会阻止它向fence发送前一个线程正在等待的信号:

  lock(A);
  unlock(A);
  dma_fence_signal(B);

  通过手动注释所有与发送dma_fence相关的代码，我们可以告诉lockdep这些依赖关系，这也有助于解决验证问题，因为现在lockdep可以为我们检查所有的规则:

  cookie = dma_fence_begin_signalling();
  lock(A);
  unlock(A);
  dma_fence_signal(B);
  dma_fence_end_signalling(cookie);

  为了使用dma_fence_begin_signalling()和dma_fence_end_signalling()来注释关键部分，需要遵循以下规则:

   

  • All code necessary to complete a dma_fence must be annotated, from the point where a fence is accessible to other threads, to the point where dma_fence_signal() is called. Un-annotated code can contain deadlock issues, and due to the very strict rules and many corner cases it is infeasible to catch these just with review or normal stress testing.
  • struct dma_resv deserves a special note, since the readers are only protected by rcu. This means the signalling critical section starts as soon as the new fences are installed, even before dma_resv_unlock() is called.
  • The only exception are fast paths and opportunistic signalling code, which calls dma_fence_signal() purely as an optimization, but is not required to guarantee completion of a dma_fence. The usual example is a wait IOCTL which calls dma_fence_signal(), while the mandatory completion path goes through a hardware interrupt and possible job completion worker.
  • To aid composability of code, the annotations can be freely nested, as long as the overall locking hierarchy is consistent. The annotations also work both in interrupt and process context. Due to implementation details this requires that callers pass an opaque cookie from dma_fence_begin_signalling() to dma_fence_end_signalling().
  • Validation against the cross driver contract is implemented by priming lockdep with the relevant hierarchy at boot-up. This means even just testing with a single device is enough to validate a driver, at least as far as deadlocks with dma_fence_wait() against dma_fence_signal() are concerned.

   

  DMA Fences Functions Reference

  https://www.kernel.org/doc/html/latest/driver-api/dma-buf.html?highlight=dma_buf#dma-fences-functions-reference

  Indefinite DMA Fences

  在不同的时候，结构体dma_fence被提议无限期地等待dma_fence_wait()完成。例子包括:

   

  • Future fences, used in HWC1 to signal when a buffer isn’t used by the display any longer, and created with the screen update that makes the buffer visible. The time this fence completes is entirely under userspace’s control.
  • Proxy fences, proposed to handle &drm_syncobj for which the fence has not yet been set. Used to asynchronously delay command submission.
  • Userspace fences or gpu futexes, fine-grained locking within a command buffer that userspace uses for synchronization across engines or with the CPU, which are then imported as a DMA fence for integration into existing winsys protocols.
  • Long-running compute command buffers, while still using traditional end of batch DMA fences for memory management instead of context preemption DMA fences which get reattached when the compute job is rescheduled.

  所有这些方案的共同之处在于，用户空间控制这些fence和控件的依赖性。将不确定的fence与正常的内核DMAfence混合使用是不起作用的，即使包含了一个回退超时来防止恶意用户空间:

   

  • Only the kernel knows about all DMA fence dependencies, userspace is not aware of dependencies injected due to memory management or scheduler decisions.
  • Only userspace knows about all dependencies in indefinite fences and when exactly they will complete, the kernel has no visibility.

  此外，内核必须能够支持用户空间命令提交以满足内存管理需要，这意味着我们必须支持依赖于DMA fence的indefinite  fence。如果内核也支持像DMA fence这样的不确定fence，就像上面的任何提议一样，那么就有可能出现死锁。

  

  这意味着内核可能会通过用户空间不知道的内存管理依赖项意外地创建死锁，它随机地挂起工作负载，直到超时到来。从用户空间的角度来看，工作负载不包含死锁。在这样一个混合的防御体系结构中，没有一个单一的实体知道所有的依赖关系。因此，从内核中阻止这种死锁是不可能的。

  避免依赖循环的唯一解决方案是不允许在内核中设置不确定的fence。这意味着:

   

  • No future fences, proxy fences or userspace fences imported as DMA fences, with or without a timeout.
  • No DMA fences that signal end of batchbuffer for command submission where userspace is allowed to use userspace fencing or long running compute workloads. This also means no implicit fencing for shared buffers in these cases.