dma-resv.h File Reference

#include <linux/ww_mutex.h>
#include <linux/dma-fence.h>
#include <linux/slab.h>
#include <linux/seqlock.h>
#include <linux/rcupdate.h>

Include dependency graph for dma-resv.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	dma_resv
struct	dma_resv_iter

Macros
#define	dma_resv_for_each_fence_unlocked(cursor, fence)
#define	dma_resv_for_each_fence(cursor, obj, usage, fence)
#define	dma_resv_held(obj)   lockdep_is_held(&(obj)->lock.base)
#define	dma_resv_assert_held(obj)   lockdep_assert_held(&(obj)->lock.base)

Enumerations
enum	dma_resv_usage { DMA_RESV_USAGE_KERNEL , DMA_RESV_USAGE_WRITE , DMA_RESV_USAGE_READ , DMA_RESV_USAGE_BOOKKEEP }

Functions
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)
void	dma_resv_init (struct dma_resv *obj)
void	dma_resv_fini (struct dma_resv *obj)
int	dma_resv_reserve_fences (struct dma_resv *obj, unsigned int num_fences)
void	dma_resv_add_fence (struct dma_resv *obj, struct dma_fence *fence, enum dma_resv_usage usage)
void	dma_resv_replace_fences (struct dma_resv *obj, uint64_t context, struct dma_fence *fence, enum dma_resv_usage usage)
int	dma_resv_get_fences (struct dma_resv *obj, enum dma_resv_usage usage, unsigned int *num_fences, struct dma_fence ***fences)
int	dma_resv_get_singleton (struct dma_resv *obj, enum dma_resv_usage usage, struct dma_fence **fence)
int	dma_resv_copy_fences (struct dma_resv *dst, struct dma_resv *src)
long	dma_resv_wait_timeout (struct dma_resv *obj, enum dma_resv_usage usage, bool intr, unsigned long timeout)
void	dma_resv_set_deadline (struct dma_resv *obj, enum dma_resv_usage usage, ktime_t deadline)
bool	dma_resv_test_signaled (struct dma_resv *obj, enum dma_resv_usage usage)
void	dma_resv_describe (struct dma_resv *obj, struct seq_file *seq)

Variables
struct ww_class	reservation_ww_class

Macro Definition Documentation

dma_resv_assert_held

#define dma_resv_assert_held

(

obj

)

lockdep_assert_held(&(obj)->lock.base)

dma_resv_for_each_fence

#define dma_resv_for_each_fence	(		cursor,
			obj,
			usage,
			fence
	)

Value:

    for (dma_resv_iter_begin(cursor, obj, usage),   \
         fence = dma_resv_iter_first(cursor); fence;    \
         fence = dma_resv_iter_next(cursor))

dma_resv_for_each_fence - fence iterator @cursor: a struct dma_resv_iter pointer @obj: a dma_resv object pointer @usage: controls which fences to return @fence: the current fence

Iterate over the fences in a struct dma_resv object while holding the &dma_resv.lock. @all_fences controls if the shared fences are returned as well. The cursor initialisation is part of the iterator and the fence stays valid as long as the lock is held and so no extra reference to the fence is taken.

dma_resv_for_each_fence_unlocked

#define dma_resv_for_each_fence_unlocked	(		cursor,
			fence
	)

Value:

    for (fence = dma_resv_iter_first_unlocked(cursor);      \
         fence; fence = dma_resv_iter_next_unlocked(cursor))

dma_resv_for_each_fence_unlocked - unlocked fence iterator @cursor: a struct dma_resv_iter pointer @fence: the current fence

Iterate over the fences in a struct dma_resv object without holding the &dma_resv.lock and using RCU instead. The cursor needs to be initialized with dma_resv_iter_begin() and cleaned up with dma_resv_iter_end(). Inside the iterator a reference to the dma_fence is held and the RCU lock dropped.

Beware that the iterator can be restarted when the struct dma_resv for @cursor is modified. Code which accumulates statistics or similar needs to check for this with dma_resv_iter_is_restarted(). For this reason prefer the lock iterator dma_resv_for_each_fence() whenever possible.

dma_resv_held

#define dma_resv_held

(

obj

)

lockdep_is_held(&(obj)->lock.base)

Enumeration Type Documentation

dma_resv_usage

enum dma_resv_usage

enum dma_resv_usage - how the fences from a dma_resv obj are used

This enum describes the different use cases for a dma_resv object and controls which fences are returned when queried.

An important fact is that there is the order KERNEL<WRITE<READ<BOOKKEEP and when the dma_resv object is asked for fences for one use case the fences for the lower use case are returned as well.

For example when asking for WRITE fences then the KERNEL fences are returned as well. Similar when asked for READ fences then both WRITE and KERNEL fences are returned as well.

Already used fences can be promoted in the sense that a fence with DMA_RESV_USAGE_BOOKKEEP could become DMA_RESV_USAGE_READ by adding it again with this usage. But fences can never be degraded in the sense that a fence with DMA_RESV_USAGE_WRITE could become DMA_RESV_USAGE_READ.

Enumerator
DMA_RESV_USAGE_KERNEL	@DMA_RESV_USAGE_KERNEL: For in kernel memory management only. This should only be used for things like copying or clearing memory with a DMA hardware engine for the purpose of kernel memory management. Drivers always must wait for those fences before accessing the resource protected by the dma_resv object. The only exception for that is when the resource is known to be locked down in place by pinning it previously.
DMA_RESV_USAGE_WRITE	@DMA_RESV_USAGE_WRITE: Implicit write synchronization. This should only be used for userspace command submissions which add an implicit write dependency.
DMA_RESV_USAGE_READ	@DMA_RESV_USAGE_READ: Implicit read synchronization. This should only be used for userspace command submissions which add an implicit read dependency.
DMA_RESV_USAGE_BOOKKEEP	@DMA_RESV_USAGE_BOOKKEEP: No implicit sync. This should be used by submissions which don't want to participate in any implicit synchronization. The most common cases are preemption fences, page table updates, TLB flushes as well as explicitly synced user submissions. Explicitly synced user submissions can be promoted to DMA_RESV_USAGE_READ or DMA_RESV_USAGE_WRITE as needed using dma_buf_import_sync_file() when implicit synchronization should become necessary after initial adding of the fence.

Function Documentation

dma_resv_add_fence()

void dma_resv_add_fence	(	struct dma_resv *	obj,
		struct dma_fence *	fence,
		enum dma_resv_usage	usage
	)

dma_resv_copy_fences()

int dma_resv_copy_fences	(	struct dma_resv *	dst,
		struct dma_resv *	src
	)

dma_resv_describe()

void dma_resv_describe	(	struct dma_resv *	obj,
		struct seq_file *	seq
	)

dma_resv_fini()

void dma_resv_fini

(

struct dma_resv *

obj

)

dma_resv_get_fences()

int dma_resv_get_fences	(	struct dma_resv *	obj,
		enum dma_resv_usage	usage,
		unsigned int *	num_fences,
		struct dma_fence ***	fences
	)

dma_resv_get_singleton()

int dma_resv_get_singleton	(	struct dma_resv *	obj,
		enum dma_resv_usage	usage,
		struct dma_fence **	fence
	)

dma_resv_init()

void dma_resv_init

(

struct dma_resv *

obj

)

dma_resv_iter_first()

struct dma_fence * dma_resv_iter_first

(

struct dma_resv_iter *

cursor

)

dma_resv_iter_first_unlocked()

struct dma_fence * dma_resv_iter_first_unlocked

(

struct dma_resv_iter *

cursor

)

dma_resv_iter_next()

struct dma_fence * dma_resv_iter_next

(

struct dma_resv_iter *

cursor

)

dma_resv_iter_next_unlocked()

struct dma_fence * dma_resv_iter_next_unlocked

(

struct dma_resv_iter *

cursor

)

dma_resv_replace_fences()

void dma_resv_replace_fences	(	struct dma_resv *	obj,
		uint64_t	context,
		struct dma_fence *	fence,
		enum dma_resv_usage	usage
	)

dma_resv_reserve_fences()

int dma_resv_reserve_fences	(	struct dma_resv *	obj,
		unsigned int	num_fences
	)

dma_resv_set_deadline()

void dma_resv_set_deadline	(	struct dma_resv *	obj,
		enum dma_resv_usage	usage,
		ktime_t	deadline
	)

dma_resv_test_signaled()

bool dma_resv_test_signaled	(	struct dma_resv *	obj,
		enum dma_resv_usage	usage
	)

dma_resv_wait_timeout()

long dma_resv_wait_timeout	(	struct dma_resv *	obj,
		enum dma_resv_usage	usage,
		bool	intr,
		unsigned long	timeout
	)

Variable Documentation

reservation_ww_class

struct ww_class reservation_ww_class

extern