[Intel-xe] [PATCH 06/22] drm/xe: Kernel doc GT TLB invalidations

[Matt Roper]

On Fri, Feb 03, 2023 at 03:23:53PM -0500, Rodrigo Vivi wrote:
> From: Matthew Brost <matthew.brost at intel.com>
> 
> Document all exported functions.
> 
> Signed-off-by: Matthew Brost <matthew.brost at intel.com>
> Cc: Niranjana Vishwanathapura <niranjana.vishwanathapura at intel.com>
> Signed-off-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
> ---
>  drivers/gpu/drm/xe/xe_gt_tlb_invalidation.c | 52 ++++++++++++++++++++-
>  1 file changed, 51 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/xe/xe_gt_tlb_invalidation.c b/drivers/gpu/drm/xe/xe_gt_tlb_invalidation.c
> index 23094d364583..1cb4d3a6bc57 100644
> --- a/drivers/gpu/drm/xe/xe_gt_tlb_invalidation.c
> +++ b/drivers/gpu/drm/xe/xe_gt_tlb_invalidation.c
> @@ -14,6 +14,15 @@ guc_to_gt(struct xe_guc *guc)
>  	return container_of(guc, struct xe_gt, uc.guc);
>  }
>  
> +/**
> + * xe_gt_tlb_invalidation_init - Initialize GT TLB invalidation state
> + * @gt: graphics tile
> + *
> + * Initialize GT TLB invalidation state, purely software initialization, should
> + * be called once during driver load.
> + *
> + * Return: 0 on success, negative error code on error.
> + */
>  int xe_gt_tlb_invalidation_init(struct xe_gt *gt)
>  {
>  	gt->tlb_invalidation.seqno = 1;
> @@ -24,7 +33,13 @@ int xe_gt_tlb_invalidation_init(struct xe_gt *gt)
>  	return 0;
>  }
>  
> -void xe_gt_tlb_invalidation_reset(struct xe_gt *gt)
> +/**
> + * xe_gt_tlb_invalidation_reset - Initialize GT TLB invalidation reset

The description here is confusing.  We're not really "initializing"
anything here.

> + * @gt: graphics tile
> + *
> + * Signal any pending invalidation fences, should be called during a GT reset

Is it confirmed that a GDRST-initiated reset implicitly invalidates all
the engine TLBs (and thus just signalling all the fences is sufficient)?
Or does the GuC take care of this itself while it is being
(re)initialized?  I know there are a lot of parts of the GT that don't
actually get reset when requesting GRDOM_FULL, but it's never been very
well documented exactly what those are.


Matt

> + */
> + void xe_gt_tlb_invalidation_reset(struct xe_gt *gt)
>  {
>  	struct xe_gt_tlb_invalidation_fence *fence, *next;
>  
> @@ -82,6 +97,19 @@ static int send_tlb_invalidation(struct xe_guc *guc,
>  	return ret;
>  }
>  
> +/**
> + * xe_gt_tlb_invalidation - Issue a TLB invalidation on this GT
> + * @gt: graphics tile
> + * @fence: invalidation fence which will be signal on TLB invalidation
> + * completion, can be NULL
> + *
> + * Issue a full TLB invalidation on the GT. Completion of TLB is asynchronous
> + * and caller can either use the invalidation fence or seqno +
> + * xe_gt_tlb_invalidation_wait to wait for completion.
> + *
> + * Return: Seqno which can be passed to xe_gt_tlb_invalidation_wait on success,
> + * negative error code on error.
> + */
>  int xe_gt_tlb_invalidation(struct xe_gt *gt,
>  			   struct xe_gt_tlb_invalidation_fence *fence)
>  {
> @@ -100,6 +128,16 @@ static bool tlb_invalidation_seqno_past(struct xe_gt *gt, int seqno)
>  	return false;
>  }
>  
> +/**
> + * xe_gt_tlb_invalidation_wait - Wait for TLB to complete
> + * @gt: graphics tile
> + * @seqno: seqno to wait which was returned from xe_gt_tlb_invalidation
> + *
> + * Wait for 200ms for a TLB invalidation to complete, in practice we always
> + * should receive the TLB invalidation within 200ms.
> + *
> + * Return: 0 on success, -ETIME on TLB invalidation timeout
> + */
>  int xe_gt_tlb_invalidation_wait(struct xe_gt *gt, int seqno)
>  {
>  	struct xe_device *xe = gt_to_xe(gt);
> @@ -122,6 +160,18 @@ int xe_gt_tlb_invalidation_wait(struct xe_gt *gt, int seqno)
>  	return 0;
>  }
>  
> +/**
> + * xe_guc_tlb_invalidation_done_handler - TLB invalidation done handler
> + * @guc: guc
> + * @msg: message indicating TLB invalidation done
> + * @len: length of message
> + *
> + * Parse seqno of TLB invalidation, wake any waiters for seqno, and signal any
> + * invalidation fences for seqno. Algorithm for this depends on seqno being
> + * received in-order and asserts this assumption.
> + *
> + * Return: 0 on success, -EPROTO for malformed messages.
> + */
>  int xe_guc_tlb_invalidation_done_handler(struct xe_guc *guc, u32 *msg, u32 len)
>  {
>  	struct xe_gt *gt = guc_to_gt(guc);
> -- 
> 2.39.1
> 

-- 
Matt Roper
Graphics Software Engineer
Linux GPU Platform Enablement
Intel Corporation