Commit d66b7ec2 authored by Alex Deucher's avatar Alex Deucher Committed by Christian König

drm/radeon: document radeon_fence.c (v2)

Adds documentation to most of the functions in
radeon_fence.c

v2: address Christian's comments:
- split common concept description into it's own comment
- fix description of intr parameter
- Improve description of -EDEADLK error
Signed-off-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Reviewed-by: default avatarChristian König <christian.koenig@amd.com>
parent abf1dc67
...@@ -40,6 +40,26 @@ ...@@ -40,6 +40,26 @@
#include "radeon.h" #include "radeon.h"
#include "radeon_trace.h" #include "radeon_trace.h"
/*
* Fences
* Fences mark an event in the GPUs pipeline and are used
* for GPU/CPU synchronization. When the fence is written,
* it is expected that all buffers associated with that fence
* are no longer in use by the associated ring on the GPU and
* that the the relevant GPU caches have been flushed. Whether
* we use a scratch register or memory location depends on the asic
* and whether writeback is enabled.
*/
/**
* radeon_fence_write - write a fence value
*
* @rdev: radeon_device pointer
* @seq: sequence number to write
* @ring: ring index the fence is associated with
*
* Writes a fence value to memory or a scratch register (all asics).
*/
static void radeon_fence_write(struct radeon_device *rdev, u32 seq, int ring) static void radeon_fence_write(struct radeon_device *rdev, u32 seq, int ring)
{ {
struct radeon_fence_driver *drv = &rdev->fence_drv[ring]; struct radeon_fence_driver *drv = &rdev->fence_drv[ring];
...@@ -50,6 +70,15 @@ static void radeon_fence_write(struct radeon_device *rdev, u32 seq, int ring) ...@@ -50,6 +70,15 @@ static void radeon_fence_write(struct radeon_device *rdev, u32 seq, int ring)
} }
} }
/**
* radeon_fence_read - read a fence value
*
* @rdev: radeon_device pointer
* @ring: ring index the fence is associated with
*
* Reads a fence value from memory or a scratch register (all asics).
* Returns the value of the fence read from memory or register.
*/
static u32 radeon_fence_read(struct radeon_device *rdev, int ring) static u32 radeon_fence_read(struct radeon_device *rdev, int ring)
{ {
struct radeon_fence_driver *drv = &rdev->fence_drv[ring]; struct radeon_fence_driver *drv = &rdev->fence_drv[ring];
...@@ -63,6 +92,16 @@ static u32 radeon_fence_read(struct radeon_device *rdev, int ring) ...@@ -63,6 +92,16 @@ static u32 radeon_fence_read(struct radeon_device *rdev, int ring)
return seq; return seq;
} }
/**
* radeon_fence_emit - emit a fence on the requested ring
*
* @rdev: radeon_device pointer
* @fence: radeon fence object
* @ring: ring index the fence is associated with
*
* Emits a fence command on the requested ring (all asics).
* Returns 0 on success, -ENOMEM on failure.
*/
int radeon_fence_emit(struct radeon_device *rdev, int radeon_fence_emit(struct radeon_device *rdev,
struct radeon_fence **fence, struct radeon_fence **fence,
int ring) int ring)
...@@ -81,6 +120,15 @@ int radeon_fence_emit(struct radeon_device *rdev, ...@@ -81,6 +120,15 @@ int radeon_fence_emit(struct radeon_device *rdev,
return 0; return 0;
} }
/**
* radeon_fence_process - process a fence
*
* @rdev: radeon_device pointer
* @ring: ring index the fence is associated with
*
* Checks the current fence value and wakes the fence queue
* if the sequence number has increased (all asics).
*/
void radeon_fence_process(struct radeon_device *rdev, int ring) void radeon_fence_process(struct radeon_device *rdev, int ring)
{ {
uint64_t seq, last_seq; uint64_t seq, last_seq;
...@@ -141,6 +189,13 @@ void radeon_fence_process(struct radeon_device *rdev, int ring) ...@@ -141,6 +189,13 @@ void radeon_fence_process(struct radeon_device *rdev, int ring)
} }
} }
/**
* radeon_fence_destroy - destroy a fence
*
* @kref: fence kref
*
* Frees the fence object (all asics).
*/
static void radeon_fence_destroy(struct kref *kref) static void radeon_fence_destroy(struct kref *kref)
{ {
struct radeon_fence *fence; struct radeon_fence *fence;
...@@ -149,6 +204,20 @@ static void radeon_fence_destroy(struct kref *kref) ...@@ -149,6 +204,20 @@ static void radeon_fence_destroy(struct kref *kref)
kfree(fence); kfree(fence);
} }
/**
* radeon_fence_seq_signaled - check if a fence sequeuce number has signaled
*
* @rdev: radeon device pointer
* @seq: sequence number
* @ring: ring index the fence is associated with
*
* Check if the last singled fence sequnce number is >= the requested
* sequence number (all asics).
* Returns true if the fence has signaled (current fence value
* is >= requested value) or false if it has not (current fence
* value is < the requested value. Helper function for
* radeon_fence_signaled().
*/
static bool radeon_fence_seq_signaled(struct radeon_device *rdev, static bool radeon_fence_seq_signaled(struct radeon_device *rdev,
u64 seq, unsigned ring) u64 seq, unsigned ring)
{ {
...@@ -163,6 +232,14 @@ static bool radeon_fence_seq_signaled(struct radeon_device *rdev, ...@@ -163,6 +232,14 @@ static bool radeon_fence_seq_signaled(struct radeon_device *rdev,
return false; return false;
} }
/**
* radeon_fence_signaled - check if a fence has signaled
*
* @fence: radeon fence object
*
* Check if the requested fence has signaled (all asics).
* Returns true if the fence has signaled or false if it has not.
*/
bool radeon_fence_signaled(struct radeon_fence *fence) bool radeon_fence_signaled(struct radeon_fence *fence)
{ {
if (!fence) { if (!fence) {
...@@ -178,6 +255,24 @@ bool radeon_fence_signaled(struct radeon_fence *fence) ...@@ -178,6 +255,24 @@ bool radeon_fence_signaled(struct radeon_fence *fence)
return false; return false;
} }
/**
* radeon_fence_wait_seq - wait for a specific sequence number
*
* @rdev: radeon device pointer
* @target_seq: sequence number we want to wait for
* @ring: ring index the fence is associated with
* @intr: use interruptable sleep
* @lock_ring: whether the ring should be locked or not
*
* Wait for the requested sequence number to be written (all asics).
* @intr selects whether to use interruptable (true) or non-interruptable
* (false) sleep when waiting for the sequence number. Helper function
* for radeon_fence_wait(), et al.
* Returns 0 if the sequence number has passed, error for all other cases.
* -EDEADLK is returned when a GPU lockup has been detected and the ring is
* marked as not ready so no further jobs get scheduled until a successful
* reset.
*/
static int radeon_fence_wait_seq(struct radeon_device *rdev, u64 target_seq, static int radeon_fence_wait_seq(struct radeon_device *rdev, u64 target_seq,
unsigned ring, bool intr, bool lock_ring) unsigned ring, bool intr, bool lock_ring)
{ {
...@@ -273,6 +368,17 @@ static int radeon_fence_wait_seq(struct radeon_device *rdev, u64 target_seq, ...@@ -273,6 +368,17 @@ static int radeon_fence_wait_seq(struct radeon_device *rdev, u64 target_seq,
return 0; return 0;
} }
/**
* radeon_fence_wait - wait for a fence to signal
*
* @fence: radeon fence object
* @intr: use interruptable sleep
*
* Wait for the requested fence to signal (all asics).
* @intr selects whether to use interruptable (true) or non-interruptable
* (false) sleep when waiting for the fence.
* Returns 0 if the fence has passed, error for all other cases.
*/
int radeon_fence_wait(struct radeon_fence *fence, bool intr) int radeon_fence_wait(struct radeon_fence *fence, bool intr)
{ {
int r; int r;
...@@ -303,6 +409,20 @@ bool radeon_fence_any_seq_signaled(struct radeon_device *rdev, u64 *seq) ...@@ -303,6 +409,20 @@ bool radeon_fence_any_seq_signaled(struct radeon_device *rdev, u64 *seq)
return false; return false;
} }
/**
* radeon_fence_wait_any_seq - wait for a sequence number on any ring
*
* @rdev: radeon device pointer
* @target_seq: sequence number(s) we want to wait for
* @intr: use interruptable sleep
*
* Wait for the requested sequence number(s) to be written by any ring
* (all asics). Sequnce number array is indexed by ring id.
* @intr selects whether to use interruptable (true) or non-interruptable
* (false) sleep when waiting for the sequence number. Helper function
* for radeon_fence_wait_any(), et al.
* Returns 0 if the sequence number has passed, error for all other cases.
*/
static int radeon_fence_wait_any_seq(struct radeon_device *rdev, static int radeon_fence_wait_any_seq(struct radeon_device *rdev,
u64 *target_seq, bool intr) u64 *target_seq, bool intr)
{ {
...@@ -412,6 +532,19 @@ static int radeon_fence_wait_any_seq(struct radeon_device *rdev, ...@@ -412,6 +532,19 @@ static int radeon_fence_wait_any_seq(struct radeon_device *rdev,
return 0; return 0;
} }
/**
* radeon_fence_wait_any - wait for a fence to signal on any ring
*
* @rdev: radeon device pointer
* @fences: radeon fence object(s)
* @intr: use interruptable sleep
*
* Wait for any requested fence to signal (all asics). Fence
* array is indexed by ring id. @intr selects whether to use
* interruptable (true) or non-interruptable (false) sleep when
* waiting for the fences. Used by the suballocator.
* Returns 0 if any fence has passed, error for all other cases.
*/
int radeon_fence_wait_any(struct radeon_device *rdev, int radeon_fence_wait_any(struct radeon_device *rdev,
struct radeon_fence **fences, struct radeon_fence **fences,
bool intr) bool intr)
...@@ -442,7 +575,16 @@ int radeon_fence_wait_any(struct radeon_device *rdev, ...@@ -442,7 +575,16 @@ int radeon_fence_wait_any(struct radeon_device *rdev,
return 0; return 0;
} }
/* caller must hold ring lock */ /**
* radeon_fence_wait_next_locked - wait for the next fence to signal
*
* @rdev: radeon device pointer
* @ring: ring index the fence is associated with
*
* Wait for the next fence on the requested ring to signal (all asics).
* Returns 0 if the next fence has passed, error for all other cases.
* Caller must hold ring lock.
*/
int radeon_fence_wait_next_locked(struct radeon_device *rdev, int ring) int radeon_fence_wait_next_locked(struct radeon_device *rdev, int ring)
{ {
uint64_t seq; uint64_t seq;
...@@ -456,7 +598,16 @@ int radeon_fence_wait_next_locked(struct radeon_device *rdev, int ring) ...@@ -456,7 +598,16 @@ int radeon_fence_wait_next_locked(struct radeon_device *rdev, int ring)
return radeon_fence_wait_seq(rdev, seq, ring, false, false); return radeon_fence_wait_seq(rdev, seq, ring, false, false);
} }
/* caller must hold ring lock */ /**
* radeon_fence_wait_empty_locked - wait for all fences to signal
*
* @rdev: radeon device pointer
* @ring: ring index the fence is associated with
*
* Wait for all fences on the requested ring to signal (all asics).
* Returns 0 if the fences have passed, error for all other cases.
* Caller must hold ring lock.
*/
void radeon_fence_wait_empty_locked(struct radeon_device *rdev, int ring) void radeon_fence_wait_empty_locked(struct radeon_device *rdev, int ring)
{ {
uint64_t seq = rdev->fence_drv[ring].sync_seq[ring]; uint64_t seq = rdev->fence_drv[ring].sync_seq[ring];
...@@ -479,12 +630,27 @@ void radeon_fence_wait_empty_locked(struct radeon_device *rdev, int ring) ...@@ -479,12 +630,27 @@ void radeon_fence_wait_empty_locked(struct radeon_device *rdev, int ring)
} }
} }
/**
* radeon_fence_ref - take a ref on a fence
*
* @fence: radeon fence object
*
* Take a reference on a fence (all asics).
* Returns the fence.
*/
struct radeon_fence *radeon_fence_ref(struct radeon_fence *fence) struct radeon_fence *radeon_fence_ref(struct radeon_fence *fence)
{ {
kref_get(&fence->kref); kref_get(&fence->kref);
return fence; return fence;
} }
/**
* radeon_fence_unref - remove a ref on a fence
*
* @fence: radeon fence object
*
* Remove a reference on a fence (all asics).
*/
void radeon_fence_unref(struct radeon_fence **fence) void radeon_fence_unref(struct radeon_fence **fence)
{ {
struct radeon_fence *tmp = *fence; struct radeon_fence *tmp = *fence;
...@@ -495,6 +661,16 @@ void radeon_fence_unref(struct radeon_fence **fence) ...@@ -495,6 +661,16 @@ void radeon_fence_unref(struct radeon_fence **fence)
} }
} }
/**
* radeon_fence_count_emitted - get the count of emitted fences
*
* @rdev: radeon device pointer
* @ring: ring index the fence is associated with
*
* Get the number of fences emitted on the requested ring (all asics).
* Returns the number of emitted fences on the ring. Used by the
* dynpm code to ring track activity.
*/
unsigned radeon_fence_count_emitted(struct radeon_device *rdev, int ring) unsigned radeon_fence_count_emitted(struct radeon_device *rdev, int ring)
{ {
uint64_t emitted; uint64_t emitted;
...@@ -512,6 +688,17 @@ unsigned radeon_fence_count_emitted(struct radeon_device *rdev, int ring) ...@@ -512,6 +688,17 @@ unsigned radeon_fence_count_emitted(struct radeon_device *rdev, int ring)
return (unsigned)emitted; return (unsigned)emitted;
} }
/**
* radeon_fence_need_sync - do we need a semaphore
*
* @fence: radeon fence object
* @dst_ring: which ring to check against
*
* Check if the fence needs to be synced against another ring
* (all asics). If so, we need to emit a semaphore.
* Returns true if we need to sync with another ring, false if
* not.
*/
bool radeon_fence_need_sync(struct radeon_fence *fence, int dst_ring) bool radeon_fence_need_sync(struct radeon_fence *fence, int dst_ring)
{ {
struct radeon_fence_driver *fdrv; struct radeon_fence_driver *fdrv;
...@@ -533,6 +720,15 @@ bool radeon_fence_need_sync(struct radeon_fence *fence, int dst_ring) ...@@ -533,6 +720,15 @@ bool radeon_fence_need_sync(struct radeon_fence *fence, int dst_ring)
return true; return true;
} }
/**
* radeon_fence_note_sync - record the sync point
*
* @fence: radeon fence object
* @dst_ring: which ring to check against
*
* Note the sequence number at which point the fence will
* be synced with the requested ring (all asics).
*/
void radeon_fence_note_sync(struct radeon_fence *fence, int dst_ring) void radeon_fence_note_sync(struct radeon_fence *fence, int dst_ring)
{ {
struct radeon_fence_driver *dst, *src; struct radeon_fence_driver *dst, *src;
...@@ -557,6 +753,18 @@ void radeon_fence_note_sync(struct radeon_fence *fence, int dst_ring) ...@@ -557,6 +753,18 @@ void radeon_fence_note_sync(struct radeon_fence *fence, int dst_ring)
} }
} }
/**
* radeon_fence_driver_start_ring - make the fence driver
* ready for use on the requested ring.
*
* @rdev: radeon device pointer
* @ring: ring index to start the fence driver on
*
* Make the fence driver ready for processing (all asics).
* Not all asics have all rings, so each asic will only
* start the fence driver on the rings it has.
* Returns 0 for success, errors for failure.
*/
int radeon_fence_driver_start_ring(struct radeon_device *rdev, int ring) int radeon_fence_driver_start_ring(struct radeon_device *rdev, int ring)
{ {
uint64_t index; uint64_t index;
...@@ -585,6 +793,16 @@ int radeon_fence_driver_start_ring(struct radeon_device *rdev, int ring) ...@@ -585,6 +793,16 @@ int radeon_fence_driver_start_ring(struct radeon_device *rdev, int ring)
return 0; return 0;
} }
/**
* radeon_fence_driver_init_ring - init the fence driver
* for the requested ring.
*
* @rdev: radeon device pointer
* @ring: ring index to start the fence driver on
*
* Init the fence driver for the requested ring (all asics).
* Helper function for radeon_fence_driver_init().
*/
static void radeon_fence_driver_init_ring(struct radeon_device *rdev, int ring) static void radeon_fence_driver_init_ring(struct radeon_device *rdev, int ring)
{ {
int i; int i;
...@@ -599,6 +817,18 @@ static void radeon_fence_driver_init_ring(struct radeon_device *rdev, int ring) ...@@ -599,6 +817,18 @@ static void radeon_fence_driver_init_ring(struct radeon_device *rdev, int ring)
rdev->fence_drv[ring].initialized = false; rdev->fence_drv[ring].initialized = false;
} }
/**
* radeon_fence_driver_init - init the fence driver
* for all possible rings.
*
* @rdev: radeon device pointer
*
* Init the fence driver for all possible rings (all asics).
* Not all asics have all rings, so each asic will only
* start the fence driver on the rings it has using
* radeon_fence_driver_start_ring().
* Returns 0 for success.
*/
int radeon_fence_driver_init(struct radeon_device *rdev) int radeon_fence_driver_init(struct radeon_device *rdev)
{ {
int ring; int ring;
...@@ -613,6 +843,14 @@ int radeon_fence_driver_init(struct radeon_device *rdev) ...@@ -613,6 +843,14 @@ int radeon_fence_driver_init(struct radeon_device *rdev)
return 0; return 0;
} }
/**
* radeon_fence_driver_fini - tear down the fence driver
* for all possible rings.
*
* @rdev: radeon device pointer
*
* Tear down the fence driver for all possible rings (all asics).
*/
void radeon_fence_driver_fini(struct radeon_device *rdev) void radeon_fence_driver_fini(struct radeon_device *rdev)
{ {
int ring; int ring;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment