[PATCH] drm/i915/uapi: Document DRM_I915_QUERY_HWCONFIG_BLOB

[PATCH] drm/i915/uapi: Document DRM_I915_QUERY_HWCONFIG_BLOB

[Tvrtko Ursulin]

From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>

UAPI with absolutely no documentation should not have been added -
clarify blob format and content will be described externally.

Fixes: 78e1fb3112c0 ("drm/i915/uapi: Add query for hwconfig blob")
Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
Co-developed-by: Jordan Justen <jordan.l.justen@intel.com>
Cc: Jon Bloomfield <jon.bloomfield@intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: John Harrison <john.c.harrison@intel.com>
Cc: Jon Ewins <jon.ewins@intel.com>
Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
---
 include/uapi/drm/i915_drm.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
index 071ffd9d51f1..8d0719bee8fc 100644
--- a/include/uapi/drm/i915_drm.h
+++ b/include/uapi/drm/i915_drm.h
@@ -2683,6 +2683,9 @@ struct drm_i915_perf_oa_config {
  *
  * The behaviour is determined by the @query_id. Note that exactly what
  * @data_ptr is also depends on the specific @query_id.
+ *
+ * For specific queries see:
+ *  * `GuC HWCONFIG blob uAPI`_
  */
 struct drm_i915_query_item {
 	/** @query_id: The id for this query */
@@ -3135,6 +3138,16 @@ struct drm_i915_query_memory_regions {
 	struct drm_i915_memory_region_info regions[];
 };
 
+/**
+ * DOC: GuC HWCONFIG blob uAPI
+ *
+ * The GuC produces a blob with information about the current device.
+ * i915 reads this blob from GuC and makes it available via this uAPI.
+ *
+ * The format and meading of the blob content are documented in the
+ * Programmer's Reference Manual.
+ */
+
 /**
  * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added
  * extension support using struct i915_user_extension.
-- 
2.32.0

Re: [PATCH] drm/i915/uapi: Document DRM_I915_QUERY_HWCONFIG_BLOB

[Daniel Vetter]

On Fri, Mar 25, 2022 at 09:49:16AM +0000, Tvrtko Ursulin wrote:
> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
> 
> UAPI with absolutely no documentation should not have been added -
> clarify blob format and content will be described externally.
> 
> Fixes: 78e1fb3112c0 ("drm/i915/uapi: Add query for hwconfig blob")
> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
> Co-developed-by: Jordan Justen <jordan.l.justen@intel.com>
> Cc: Jon Bloomfield <jon.bloomfield@intel.com>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: John Harrison <john.c.harrison@intel.com>
> Cc: Jon Ewins <jon.ewins@intel.com>
> Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
> Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
>  include/uapi/drm/i915_drm.h | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
> index 071ffd9d51f1..8d0719bee8fc 100644
> --- a/include/uapi/drm/i915_drm.h
> +++ b/include/uapi/drm/i915_drm.h
> @@ -2683,6 +2683,9 @@ struct drm_i915_perf_oa_config {
>   *
>   * The behaviour is determined by the @query_id. Note that exactly what
>   * @data_ptr is also depends on the specific @query_id.
> + *
> + * For specific queries see:
> + *  * `GuC HWCONFIG blob uAPI`_

I'd put this into the @query_id section, and then make it an item list
with the #define as the label, so that it becomes tidy and can neatly
iterate them all.

Anyway we can bikeshed this all more in a follow-up.

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

>   */
>  struct drm_i915_query_item {
>  	/** @query_id: The id for this query */
> @@ -3135,6 +3138,16 @@ struct drm_i915_query_memory_regions {
>  	struct drm_i915_memory_region_info regions[];
>  };
>  
> +/**
> + * DOC: GuC HWCONFIG blob uAPI
> + *
> + * The GuC produces a blob with information about the current device.
> + * i915 reads this blob from GuC and makes it available via this uAPI.
> + *
> + * The format and meading of the blob content are documented in the
> + * Programmer's Reference Manual.
> + */
> +
>  /**
>   * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added
>   * extension support using struct i915_user_extension.
> -- 
> 2.32.0
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH] drm/i915/uapi: Document DRM_I915_QUERY_HWCONFIG_BLOB

[Tvrtko Ursulin]

On 25/03/2022 09:53, Daniel Vetter wrote:
> On Fri, Mar 25, 2022 at 09:49:16AM +0000, Tvrtko Ursulin wrote:
>> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>>
>> UAPI with absolutely no documentation should not have been added -
>> clarify blob format and content will be described externally.
>>
>> Fixes: 78e1fb3112c0 ("drm/i915/uapi: Add query for hwconfig blob")
>> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>> Co-developed-by: Jordan Justen <jordan.l.justen@intel.com>
>> Cc: Jon Bloomfield <jon.bloomfield@intel.com>
>> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
>> Cc: John Harrison <john.c.harrison@intel.com>
>> Cc: Jon Ewins <jon.ewins@intel.com>
>> Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
>> Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
>> ---
>>   include/uapi/drm/i915_drm.h | 13 +++++++++++++
>>   1 file changed, 13 insertions(+)
>>
>> diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
>> index 071ffd9d51f1..8d0719bee8fc 100644
>> --- a/include/uapi/drm/i915_drm.h
>> +++ b/include/uapi/drm/i915_drm.h
>> @@ -2683,6 +2683,9 @@ struct drm_i915_perf_oa_config {
>>    *
>>    * The behaviour is determined by the @query_id. Note that exactly what
>>    * @data_ptr is also depends on the specific @query_id.
>> + *
>> + * For specific queries see:
>> + *  * `GuC HWCONFIG blob uAPI`_
> 
> I'd put this into the @query_id section, and then make it an item list
> with the #define as the label, so that it becomes tidy and can neatly
> iterate them all.
> 
> Anyway we can bikeshed this all more in a follow-up.
> 
> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Thanks, yes I wanted to do the minimal thing to close the gap.
>>    */
>>   struct drm_i915_query_item {
>>   	/** @query_id: The id for this query */
>> @@ -3135,6 +3138,16 @@ struct drm_i915_query_memory_regions {
>>   	struct drm_i915_memory_region_info regions[];
>>   };
>>   
>> +/**
>> + * DOC: GuC HWCONFIG blob uAPI
>> + *
>> + * The GuC produces a blob with information about the current device.
>> + * i915 reads this blob from GuC and makes it available via this uAPI.
>> + *
>> + * The format and meading of the blob content are documented in the

Meading? I will fix that up while merging.

Regards,

Tvrtko

>> + * Programmer's Reference Manual.
>> + */
>> +
>>   /**
>>    * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added
>>    * extension support using struct i915_user_extension.
>> -- 
>> 2.32.0
>>
>