include/linux/dma-resv.h

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

File Facts

System
Linux kernel
Corpus path
include/linux/dma-resv.h
Extension
.h
Size
17346 bytes
Lines
488
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_resv {
	/**
	 * @lock:
	 *
	 * Update side lock. Don't use directly, instead use the wrapper
	 * functions like dma_resv_lock() and dma_resv_unlock().
	 *
	 * Drivers which use the reservation object to manage memory dynamically
	 * also use this lock to protect buffer object state like placement,
	 * allocation policies or throughout command submission.
	 */
	struct ww_mutex lock;

	/**
	 * @fences:
	 *
	 * Array of fences which where added to the dma_resv object
	 *
	 * A new fence is added by calling dma_resv_add_fence(). Since this
	 * often needs to be done past the point of no return in command
	 * submission it cannot fail, and therefore sufficient slots need to be
	 * reserved by calling dma_resv_reserve_fences().
	 */
	struct dma_resv_list __rcu *fences;
};

/**
 * struct dma_resv_iter - current position into the dma_resv fences
 *
 * Don't touch this directly in the driver, use the accessor function instead.
 *
 * IMPORTANT
 *
 * When using the lockless iterators like dma_resv_iter_next_unlocked() or
 * dma_resv_for_each_fence_unlocked() beware that the iterator can be restarted.
 * Code which accumulates statistics or similar needs to check for this with
 * dma_resv_iter_is_restarted().
 */
struct dma_resv_iter {
	/** @obj: The dma_resv object we iterate over */
	struct dma_resv *obj;

	/** @usage: Return fences with this usage or lower. */
	enum dma_resv_usage usage;

	/** @fence: the currently handled fence */
	struct dma_fence *fence;

	/** @fence_usage: the usage of the current fence */
	enum dma_resv_usage fence_usage;

	/** @index: index into the shared fences */
	unsigned int index;

	/** @fences: the shared fences; private, *MUST* not dereference  */
	struct dma_resv_list *fences;

	/** @num_fences: number of fences */
	unsigned int num_fences;

	/** @is_restarted: true if this is the first returned fence */
	bool is_restarted;
};

struct dma_fence *dma_resv_iter_first_unlocked(struct dma_resv_iter *cursor);
struct dma_fence *dma_resv_iter_next_unlocked(struct dma_resv_iter *cursor);
struct dma_fence *dma_resv_iter_first(struct dma_resv_iter *cursor);
struct dma_fence *dma_resv_iter_next(struct dma_resv_iter *cursor);

/**
 * dma_resv_iter_begin - initialize a dma_resv_iter object
 * @cursor: The dma_resv_iter object to initialize
 * @obj: The dma_resv object which we want to iterate over
 * @usage: controls which fences to include, see enum dma_resv_usage.
 */
static inline void dma_resv_iter_begin(struct dma_resv_iter *cursor,
				       struct dma_resv *obj,
				       enum dma_resv_usage usage)
{
	cursor->obj = obj;
	cursor->usage = usage;
	cursor->fence = NULL;
}

/**
 * dma_resv_iter_end - cleanup a dma_resv_iter object
 * @cursor: the dma_resv_iter object which should be cleaned up
 *
 * Make sure that the reference to the fence in the cursor is properly
 * dropped.

Annotation

Implementation Notes