[PATCH] drm/xe: Add kernel-doc to some xe_lrc interfaces

[Michal Wajdeczko]

On 31.05.2024 07:50, Matthew Brost wrote:
> On Thu, May 30, 2024 at 11:11:00AM -0700, Niranjana Vishwanathapura wrote:
>> Add kernel-doc to xe_lrc_create/destroy and xe_lrc_get/put
>> interfaces.
>>
>> Fixes: 264eecdba211 ("drm/xe: Decouple xe_exec_queue and xe_lrc")
> 
> I missed kernel doc in initial review too.
> 
> I don't think you need a fixes tag though.
> 
>> Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura at intel.com>
>> ---
>>  drivers/gpu/drm/xe/xe_lrc.c | 18 ++++++++++++++++++
>>  drivers/gpu/drm/xe/xe_lrc.h | 13 +++++++++++++
>>  2 files changed, 31 insertions(+)
>>
>> diff --git a/drivers/gpu/drm/xe/xe_lrc.c b/drivers/gpu/drm/xe/xe_lrc.c
>> index 26922e1bac82..215a1c27665d 100644
>> --- a/drivers/gpu/drm/xe/xe_lrc.c
>> +++ b/drivers/gpu/drm/xe/xe_lrc.c
>> @@ -945,6 +945,17 @@ static int xe_lrc_init(struct xe_lrc *lrc, struct xe_hw_engine *hwe,
>>  	return err;
>>  }
>>  
>> +/**
>> + * xe_lrc_create - Create a LRC
>> + * @hwe: Hardware Engine
>> + * @vm: The VM (address space)
>> + * @ring_size: LRC ring size
>> + *
>> + * Allocate and initialize the Logical Ring Context (LRC).
>> + *
>> + * Return pointer to created LRC upon success. Return -ve error code
> 
> -ve? Typo?

I guess it supposed to be a shortcut for "negative" but it is still
wrong as it should rather say "Return error pointer on failure" as
function is not returning an 'int'

> 
> With typo fixed and dropping fixes tag:
> Reviewed-by: Matthew Brost <matthew.brost at intel.com>
> 
>> + * upon failure.
>> + */
>>  struct xe_lrc *xe_lrc_create(struct xe_hw_engine *hwe, struct xe_vm *vm,
>>  			     u32 ring_size)
>>  {
>> @@ -964,6 +975,13 @@ struct xe_lrc *xe_lrc_create(struct xe_hw_engine *hwe, struct xe_vm *vm,
>>  	return lrc;
>>  }
>>  
>> +/**
>> + * xe_lrc_destroy - Destroy the LRC
>> + * @ref: reference to LRC
>> + *
>> + * Called when ref == 0, release resources held by the Logical Ring Context
>> + * (LRC) and free the LRC memory.
>> + */
>>  void xe_lrc_destroy(struct kref *ref)
>>  {
>>  	struct xe_lrc *lrc = container_of(ref, struct xe_lrc, refcount);
>> diff --git a/drivers/gpu/drm/xe/xe_lrc.h b/drivers/gpu/drm/xe/xe_lrc.h
>> index ebe0e362e434..882c3437ba5c 100644
>> --- a/drivers/gpu/drm/xe/xe_lrc.h
>> +++ b/drivers/gpu/drm/xe/xe_lrc.h
>> @@ -26,12 +26,25 @@ struct xe_lrc *xe_lrc_create(struct xe_hw_engine *hwe, struct xe_vm *vm,
>>  			     u32 ring_size);
>>  void xe_lrc_destroy(struct kref *ref);
>>  
>> +/**
>> + * xe_lrc_get - Get reference to the LRC
>> + * @lrc: Logical Ring Context
>> + *
>> + * Increment reference count of @lrc
>> + */
>>  static inline struct xe_lrc *xe_lrc_get(struct xe_lrc *lrc)
>>  {
>>  	kref_get(&lrc->refcount);
>>  	return lrc;
>>  }
>>  
>> +/**
>> + * xe_lrc_put - Put reference of the LRC
>> + * @lrc: Logical Ring Context
>> + *
>> + * Decrement reference count of @lrc, call xe_lrc_destroy when
>> + * reference count reaches 0.
>> + */
>>  static inline void xe_lrc_put(struct xe_lrc *lrc)
>>  {
>>  	kref_put(&lrc->refcount, xe_lrc_destroy);
>> -- 
>> 2.43.0
>>