Re: [PATCH 2/2] drm/xe/guc: Add kernel-doc for xe_guc_ct_send_recv()

[Matthew Brost <matthew.brost@intel.com>]

On Sat, Jan 13, 2024 at 02:01:05PM +0100, Michal Wajdeczko wrote:
> 
> 
> On 13.01.2024 00:12, Matthew Brost wrote:
> > On Fri, Jan 12, 2024 at 11:25:54AM +0100, Michal Wajdeczko wrote:
> >> The communication with the GuC firmware is crucial for the driver
> >> but unfortunately it has limited documentation.  Add initial
> > 
> > The first sentence doesn't seem necessary.
> 
> can drop while pushing
> 

With that:
Reviewed-by: Matthew Brost <matthew.brost@intel.com>

> > 
> >> documentation for recently updated xe_guc_ct_send_recv().
> >>
> >> Signed-off-by: Michal Wajdeczko <michal.wajdeczko@intel.com>
> >> Cc: Matthew Brost <matthew.brost@intel.com>
> >> ---
> >>  drivers/gpu/drm/xe/xe_guc_ct.c | 18 ++++++++++++++++++
> >>  1 file changed, 18 insertions(+)
> >>
> >> diff --git a/drivers/gpu/drm/xe/xe_guc_ct.c b/drivers/gpu/drm/xe/xe_guc_ct.c
> >> index 4ae1a0cd9537..ee5d99456aeb 100644
> >> --- a/drivers/gpu/drm/xe/xe_guc_ct.c
> >> +++ b/drivers/gpu/drm/xe/xe_guc_ct.c
> >> @@ -785,6 +785,24 @@ static int guc_ct_send_recv(struct xe_guc_ct *ct, const u32 *action, u32 len,
> >>  	return ret > 0 ? response_buffer ? g2h_fence.response_len : g2h_fence.response_data : ret;
> >>  }
> >>  
> >> +/**
> >> + * xe_guc_ct_send_recv - Send and receive HXG to the GuC
> >> + * @ct: the &xe_guc_ct
> >> + * @action: the dword array with `HXG Request`_ message (can't be NULL)
> > 
> > What's the deal with the _ trailing everwhere? Is this kernel doc link thing?
> 
> yes, see [1]
> 
> [1]
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-references
> 
> 
> > 
> > Matt
> > 
> >> + * @len: length of the `HXG Request`_ message (in dwords, can't be 0)
> >> + * @response_buffer: placeholder for the `HXG Response`_ message (can be NULL)
> >> + *
> >> + * Send a `HXG Request`_ message to the GuC over CT communication channel and
> >> + * blocks until GuC replies with a `HXG Response`_ message.
> >> + *
> >> + * For non-blocking communication with GuC use xe_guc_ct_send().
> >> + *
> >> + * Note: The size of &response_buffer must be at least GUC_CTB_MAX_DWORDS_.
> >> + *
> >> + * Return: response length (in dwords) if &response_buffer was not NULL, or
> >> + *         DATA0 from `HXG Response`_ if &response_buffer was NULL, or
> >> + *         a negative error code on failure.
> >> + */
> >>  int xe_guc_ct_send_recv(struct xe_guc_ct *ct, const u32 *action, u32 len,
> >>  			u32 *response_buffer)
> >>  {
> >> -- 
> >> 2.25.1
> >>