include/linux/dma-buf.h

Source file repositories/reference/linux-study-clean/include/linux/dma-buf.h

File Facts

System
Linux kernel
Corpus path
include/linux/dma-buf.h
Extension
.h
Size
20671 bytes
Lines
599
Domain
Core OS
Bucket
Core Kernel Interface
Inferred role
Core OS: implementation source
Status
source implementation candidate

Why This File Exists

Core operating-system implementation surface: boot, tasks, memory, VFS, syscall-facing interfaces, synchronization, credentials, and isolation.

Dependency Surface

Detected Declarations

Annotated Snippet

struct dma_buf_ops {
	/**
	 * @attach:
	 *
	 * This is called from dma_buf_attach() to make sure that a given
	 * &dma_buf_attachment.dev can access the provided &dma_buf. Exporters
	 * which support buffer objects in special locations like VRAM or
	 * device-specific carveout areas should check whether the buffer could
	 * be move to system memory (or directly accessed by the provided
	 * device), and otherwise need to fail the attach operation.
	 *
	 * The exporter should also in general check whether the current
	 * allocation fulfills the DMA constraints of the new device. If this
	 * is not the case, and the allocation cannot be moved, it should also
	 * fail the attach operation.
	 *
	 * Any exporter-private housekeeping data can be stored in the
	 * &dma_buf_attachment.priv pointer.
	 *
	 * This callback is optional.
	 *
	 * Returns:
	 *
	 * 0 on success, negative error code on failure. It might return -EBUSY
	 * to signal that backing storage is already allocated and incompatible
	 * with the requirements of requesting device.
	 */
	int (*attach)(struct dma_buf *, struct dma_buf_attachment *);

	/**
	 * @detach:
	 *
	 * This is called by dma_buf_detach() to release a &dma_buf_attachment.
	 * Provided so that exporters can clean up any housekeeping for an
	 * &dma_buf_attachment.
	 *
	 * This callback is optional.
	 */
	void (*detach)(struct dma_buf *, struct dma_buf_attachment *);

	/**
	 * @pin:
	 *
	 * This is called by dma_buf_pin() and lets the exporter know that the
	 * DMA-buf can't be moved any more. Ideally, the exporter should
	 * pin the buffer so that it is generally accessible by all
	 * devices.
	 *
	 * This is called with the &dmabuf.resv object locked and is mutual
	 * exclusive with @cache_sgt_mapping.
	 *
	 * This is called automatically for non-dynamic importers from
	 * dma_buf_attach().
	 *
	 * Note that similar to non-dynamic exporters in their @map_dma_buf
	 * callback the driver must guarantee that the memory is available for
	 * use and cleared of any old data by the time this function returns.
	 * Drivers which pipeline their buffer moves internally must wait for
	 * all moves and clears to complete.
	 *
	 * Returns:
	 *
	 * 0 on success, negative error code on failure.
	 */
	int (*pin)(struct dma_buf_attachment *attach);

	/**
	 * @unpin:
	 *
	 * This is called by dma_buf_unpin() and lets the exporter know that the
	 * DMA-buf can be moved again.
	 *
	 * This is called with the dmabuf->resv object locked and is mutual
	 * exclusive with @cache_sgt_mapping.
	 *
	 * This callback is optional.
	 */
	void (*unpin)(struct dma_buf_attachment *attach);

	/**
	 * @map_dma_buf:
	 *
	 * This is called by dma_buf_map_attachment() and is used to map a
	 * shared &dma_buf into device address space, and it is mandatory. It
	 * can only be called if @attach has been called successfully.
	 *
	 * This call may sleep, e.g. when the backing storage first needs to be
	 * allocated, or moved to a location suitable for all currently attached
	 * devices.
	 *

Annotation

Implementation Notes