drivers/gpu/drm/i915/i915_active.h

Source file repositories/reference/linux-study-clean/drivers/gpu/drm/i915/i915_active.h

File Facts

System
Linux kernel
Corpus path
drivers/gpu/drm/i915/i915_active.h
Extension
.h
Size
8432 bytes
Lines
238
Domain
Driver Families
Bucket
drivers/gpu
Inferred role
Driver Families: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repeatable hardware-adapter layer. Deep compatibility for every driver is out of scope; this atlas records patterns, probe lifecycles, bus glue, IRQ/DMA usage, and links back to core abstractions.

Dependency Surface

Detected Declarations

Annotated Snippet

#ifndef _I915_ACTIVE_H_
#define _I915_ACTIVE_H_

#include <linux/lockdep.h>

#include "i915_active_types.h"
#include "i915_request.h"

struct i915_request;
struct intel_engine_cs;
struct intel_timeline;

/*
 * We treat requests as fences. This is not be to confused with our
 * "fence registers" but pipeline synchronisation objects ala GL_ARB_sync.
 * We use the fences to synchronize access from the CPU with activity on the
 * GPU, for example, we should not rewrite an object's PTE whilst the GPU
 * is reading them. We also track fences at a higher level to provide
 * implicit synchronisation around GEM objects, e.g. set-domain will wait
 * for outstanding GPU rendering before marking the object ready for CPU
 * access, or a pageflip will wait until the GPU is complete before showing
 * the frame on the scanout.
 *
 * In order to use a fence, the object must track the fence it needs to
 * serialise with. For example, GEM objects want to track both read and
 * write access so that we can perform concurrent read operations between
 * the CPU and GPU engines, as well as waiting for all rendering to
 * complete, or waiting for the last GPU user of a "fence register". The
 * object then embeds a #i915_active_fence to track the most recent (in
 * retirement order) request relevant for the desired mode of access.
 * The #i915_active_fence is updated with i915_active_fence_set() to
 * track the most recent fence request, typically this is done as part of
 * i915_vma_move_to_active().
 *
 * When the #i915_active_fence completes (is retired), it will
 * signal its completion to the owner through a callback as well as mark
 * itself as idle (i915_active_fence.request == NULL). The owner
 * can then perform any action, such as delayed freeing of an active
 * resource including itself.
 */

void i915_active_noop(struct dma_fence *fence, struct dma_fence_cb *cb);

/**
 * __i915_active_fence_init - prepares the activity tracker for use
 * @active: the active tracker
 * @fence: initial fence to track, can be NULL
 * @fn: a callback when then the tracker is retired (becomes idle),
 *         can be NULL
 *
 * i915_active_fence_init() prepares the embedded @active struct for use as
 * an activity tracker, that is for tracking the last known active fence
 * associated with it. When the last fence becomes idle, when it is retired
 * after completion, the optional callback @func is invoked.
 */
static inline void
__i915_active_fence_init(struct i915_active_fence *active,
			 void *fence,
			 dma_fence_func_t fn)
{
	RCU_INIT_POINTER(active->fence, fence);
	active->cb.func = fn ?: i915_active_noop;
}

#define INIT_ACTIVE_FENCE(A) \
	__i915_active_fence_init((A), NULL, NULL)

struct dma_fence *
__i915_active_fence_set(struct i915_active_fence *active,
			struct dma_fence *fence);

/**
 * i915_active_fence_set - updates the tracker to watch the current fence
 * @active: the active tracker
 * @rq: the request to watch
 *
 * i915_active_fence_set() watches the given @rq for completion. While
 * that @rq is busy, the @active reports busy. When that @rq is signaled
 * (or else retired) the @active tracker is updated to report idle.
 */
int __must_check
i915_active_fence_set(struct i915_active_fence *active,
		      struct i915_request *rq);
/**
 * i915_active_fence_get - return a reference to the active fence
 * @active: the active tracker
 *
 * i915_active_fence_get() returns a reference to the active fence,
 * or NULL if the active tracker is idle. The reference is obtained under RCU,
 * so no locking is required by the caller.

Annotation

Implementation Notes