mirror of
https://github.com/torvalds/linux.git
synced 2026-07-27 17:47:41 +02:00
drm/xe/uapi: Fix kernel-doc cross-reference syntax in xe_drm.h
Fix incorrect kernel-doc cross-reference markup syntax throughout xe_drm.h: - @struct_name -> &struct name for cross-references to other structs (19 occurrences) - struct @name -> &struct name where struct keyword was mixed with @ syntax (8 occurrences) - enum @name -> &enum name for cross-references to other enums (5 occurrences) - &CONSTANT / @CONSTANT -> %CONSTANT for defines and enum values (15 occurrences) - @field references to members of other structs -> plain text, since @ only applies to the current struct's members (9 occurrences) Per kernel-doc conventions (Documentation/doc-guide/kernel-doc.rst): - '&struct name' creates hyperlinks to struct definitions - '&enum name' creates hyperlinks to enum definitions - '%NAME' references constants and defines - '@name' is only for parameters/members of the current context Assisted-by: GitHub Copilot:claude-opus-4.6 Suggested-by: Xin Wang <x.wang@intel.com> Reviewed-by: Xin Wang <x.wang@intel.com> Link: https://patch.msgid.link/20260407030046.3394004-5-shuicheng.lin@intel.com Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
This commit is contained in:
Shuicheng Lin
parent
ea842c2358
commit
4bd87e7c4d
|
|
@ -229,9 +229,9 @@ struct drm_xe_ext_set_property {
|
|||
/**
|
||||
* struct drm_xe_engine_class_instance - instance of an engine class
|
||||
*
|
||||
* It is returned as part of the @drm_xe_engine, but it also is used as
|
||||
* the input of engine selection for both @drm_xe_exec_queue_create and
|
||||
* @drm_xe_query_engine_cycles
|
||||
* It is returned as part of the &struct drm_xe_engine, but it also is used as
|
||||
* the input of engine selection for both &struct drm_xe_exec_queue_create and
|
||||
* &struct drm_xe_query_engine_cycles
|
||||
*
|
||||
* The @engine_class can be:
|
||||
* - %DRM_XE_ENGINE_CLASS_RENDER
|
||||
|
|
@ -264,7 +264,7 @@ struct drm_xe_engine_class_instance {
|
|||
* struct drm_xe_engine - describe hardware engine
|
||||
*/
|
||||
struct drm_xe_engine {
|
||||
/** @instance: The @drm_xe_engine_class_instance */
|
||||
/** @instance: The &struct drm_xe_engine_class_instance */
|
||||
struct drm_xe_engine_class_instance instance;
|
||||
|
||||
/** @reserved: Reserved */
|
||||
|
|
@ -274,9 +274,9 @@ struct drm_xe_engine {
|
|||
/**
|
||||
* struct drm_xe_query_engines - describe engines
|
||||
*
|
||||
* If a query is made with a struct @drm_xe_device_query where .query
|
||||
* If a query is made with a &struct drm_xe_device_query where .query
|
||||
* is equal to %DRM_XE_DEVICE_QUERY_ENGINES, then the reply uses an array of
|
||||
* struct @drm_xe_query_engines in .data.
|
||||
* &struct drm_xe_query_engines in .data.
|
||||
*/
|
||||
struct drm_xe_query_engines {
|
||||
/** @num_engines: number of engines returned in @engines */
|
||||
|
|
@ -825,7 +825,7 @@ struct drm_xe_device_query {
|
|||
*
|
||||
* This ioctl supports setting the following properties via the
|
||||
* %DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY extension, which uses the
|
||||
* generic @drm_xe_ext_set_property struct:
|
||||
* generic &struct drm_xe_ext_set_property:
|
||||
*
|
||||
* - %DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE - set the type of PXP session
|
||||
* this object will be used with. Valid values are listed in enum
|
||||
|
|
@ -1198,10 +1198,10 @@ struct drm_xe_vm_bind_op {
|
|||
/**
|
||||
* struct drm_xe_vm_bind - Input of &DRM_IOCTL_XE_VM_BIND
|
||||
*
|
||||
* Below is an example of a minimal use of @drm_xe_vm_bind to
|
||||
* Below is an example of a minimal use of &struct drm_xe_vm_bind to
|
||||
* asynchronously bind the buffer `data` at address `BIND_ADDRESS` to
|
||||
* illustrate `userptr`. It can be synchronized by using the example
|
||||
* provided for @drm_xe_sync.
|
||||
* provided for &struct drm_xe_sync.
|
||||
*
|
||||
* .. code-block:: C
|
||||
*
|
||||
|
|
@ -1354,7 +1354,7 @@ struct drm_xe_vm_get_property {
|
|||
*
|
||||
* This ioctl supports setting the following properties via the
|
||||
* %DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY extension, which uses the
|
||||
* generic @drm_xe_ext_set_property struct:
|
||||
* generic &struct drm_xe_ext_set_property:
|
||||
*
|
||||
* - %DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY - set the queue priority.
|
||||
* CAP_SYS_NICE is required to set a value above normal.
|
||||
|
|
@ -1389,9 +1389,9 @@ struct drm_xe_vm_get_property {
|
|||
* enable render color cache keying on BTP+BTI instead of just BTI
|
||||
* (only valid for render queues).
|
||||
*
|
||||
* The example below shows how to use @drm_xe_exec_queue_create to create
|
||||
* The example below shows how to use &struct drm_xe_exec_queue_create to create
|
||||
* a simple exec_queue (no parallel submission) of class
|
||||
* &DRM_XE_ENGINE_CLASS_RENDER.
|
||||
* %DRM_XE_ENGINE_CLASS_RENDER.
|
||||
*
|
||||
* .. code-block:: C
|
||||
*
|
||||
|
|
@ -1514,7 +1514,7 @@ struct drm_xe_exec_queue_get_property {
|
|||
* and the @flags can be:
|
||||
* - %DRM_XE_SYNC_FLAG_SIGNAL
|
||||
*
|
||||
* A minimal use of @drm_xe_sync looks like this:
|
||||
* A minimal use of &struct drm_xe_sync looks like this:
|
||||
*
|
||||
* .. code-block:: C
|
||||
*
|
||||
|
|
@ -1580,10 +1580,10 @@ struct drm_xe_sync {
|
|||
/**
|
||||
* struct drm_xe_exec - Input of &DRM_IOCTL_XE_EXEC
|
||||
*
|
||||
* This is an example to use @drm_xe_exec for execution of the object
|
||||
* at BIND_ADDRESS (see example in @drm_xe_vm_bind) by an exec_queue
|
||||
* (see example in @drm_xe_exec_queue_create). It can be synchronized
|
||||
* by using the example provided for @drm_xe_sync.
|
||||
* This is an example to use &struct drm_xe_exec for execution of the object
|
||||
* at BIND_ADDRESS (see example in &struct drm_xe_vm_bind) by an exec_queue
|
||||
* (see example in &struct drm_xe_exec_queue_create). It can be synchronized
|
||||
* by using the example provided for &struct drm_xe_sync.
|
||||
*
|
||||
* .. code-block:: C
|
||||
*
|
||||
|
|
@ -1749,9 +1749,9 @@ enum drm_xe_observation_op {
|
|||
struct drm_xe_observation_param {
|
||||
/** @extensions: Pointer to the first extension struct, if any */
|
||||
__u64 extensions;
|
||||
/** @observation_type: observation stream type, of enum @drm_xe_observation_type */
|
||||
/** @observation_type: observation stream type, of &enum drm_xe_observation_type */
|
||||
__u64 observation_type;
|
||||
/** @observation_op: observation stream op, of enum @drm_xe_observation_op */
|
||||
/** @observation_op: observation stream op, of &enum drm_xe_observation_op */
|
||||
__u64 observation_op;
|
||||
/** @param: Pointer to actual stream params */
|
||||
__u64 param;
|
||||
|
|
@ -1810,7 +1810,7 @@ struct drm_xe_oa_unit {
|
|||
/** @oa_unit_id: OA unit ID */
|
||||
__u32 oa_unit_id;
|
||||
|
||||
/** @oa_unit_type: OA unit type of @drm_xe_oa_unit_type */
|
||||
/** @oa_unit_type: OA unit type of &enum drm_xe_oa_unit_type */
|
||||
__u32 oa_unit_type;
|
||||
|
||||
/** @capabilities: OA capabilities bit-mask */
|
||||
|
|
@ -1873,7 +1873,7 @@ struct drm_xe_query_oa_units {
|
|||
/** @pad: MBZ */
|
||||
__u32 pad;
|
||||
/**
|
||||
* @oa_units: struct @drm_xe_oa_unit array returned for this device.
|
||||
* @oa_units: &struct drm_xe_oa_unit array returned for this device.
|
||||
* Written below as a u64 array to avoid problems with nested flexible
|
||||
* arrays with some compilers
|
||||
*/
|
||||
|
|
@ -1902,22 +1902,22 @@ enum drm_xe_oa_format_type {
|
|||
/**
|
||||
* enum drm_xe_oa_property_id - OA stream property IDs
|
||||
*
|
||||
* Stream params are specified as a chain of @drm_xe_ext_set_property
|
||||
* structs, with @property values from enum @drm_xe_oa_property_id and
|
||||
* @drm_xe_user_extension base.name set to @DRM_XE_OA_EXTENSION_SET_PROPERTY.
|
||||
* @param field in struct @drm_xe_observation_param points to the first
|
||||
* @drm_xe_ext_set_property struct.
|
||||
* Stream params are specified as a chain of &struct drm_xe_ext_set_property
|
||||
* structs, with property values from &enum drm_xe_oa_property_id and
|
||||
* &struct drm_xe_user_extension base.name set to %DRM_XE_OA_EXTENSION_SET_PROPERTY.
|
||||
* The param field in &struct drm_xe_observation_param points to the first
|
||||
* &struct drm_xe_ext_set_property struct.
|
||||
*
|
||||
* Exactly the same mechanism is also used for stream reconfiguration using the
|
||||
* @DRM_XE_OBSERVATION_IOCTL_CONFIG observation stream fd ioctl, though only a
|
||||
* %DRM_XE_OBSERVATION_IOCTL_CONFIG observation stream fd ioctl, though only a
|
||||
* subset of properties below can be specified for stream reconfiguration.
|
||||
*/
|
||||
enum drm_xe_oa_property_id {
|
||||
#define DRM_XE_OA_EXTENSION_SET_PROPERTY 0
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_OA_UNIT_ID: ID of the OA unit on which to open
|
||||
* the OA stream, see @oa_unit_id in 'struct
|
||||
* drm_xe_oa_unit'. Defaults to 0 if not provided.
|
||||
* the OA stream, see oa_unit_id in &struct drm_xe_oa_unit.
|
||||
* Defaults to 0 if not provided.
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_OA_UNIT_ID = 1,
|
||||
|
||||
|
|
@ -1930,7 +1930,7 @@ enum drm_xe_oa_property_id {
|
|||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_OA_METRIC_SET: OA metrics defining contents of OA
|
||||
* reports, previously added via @DRM_XE_OBSERVATION_OP_ADD_CONFIG.
|
||||
* reports, previously added via %DRM_XE_OBSERVATION_OP_ADD_CONFIG.
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_OA_METRIC_SET,
|
||||
|
||||
|
|
@ -1938,7 +1938,7 @@ enum drm_xe_oa_property_id {
|
|||
DRM_XE_OA_PROPERTY_OA_FORMAT,
|
||||
/*
|
||||
* OA_FORMAT's are specified the same way as in PRM/Bspec 52198/60942,
|
||||
* in terms of the following quantities: a. enum @drm_xe_oa_format_type
|
||||
* in terms of the following quantities: a. &enum drm_xe_oa_format_type
|
||||
* b. Counter select c. Counter size and d. BC report. Also refer to the
|
||||
* oa_formats array in drivers/gpu/drm/xe/xe_oa.c.
|
||||
*/
|
||||
|
|
@ -1955,19 +1955,19 @@ enum drm_xe_oa_property_id {
|
|||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_OA_DISABLED: A value of 1 will open the OA
|
||||
* stream in a DISABLED state (see @DRM_XE_OBSERVATION_IOCTL_ENABLE).
|
||||
* stream in a DISABLED state (see %DRM_XE_OBSERVATION_IOCTL_ENABLE).
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_OA_DISABLED,
|
||||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID: Open the stream for a specific
|
||||
* @exec_queue_id. OA queries can be executed on this exec queue.
|
||||
* exec_queue_id. OA queries can be executed on this exec queue.
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID,
|
||||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE: Optional engine instance to
|
||||
* pass along with @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID or will default to 0.
|
||||
* pass along with %DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID or will default to 0.
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE,
|
||||
|
||||
|
|
@ -1979,16 +1979,16 @@ enum drm_xe_oa_property_id {
|
|||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_NUM_SYNCS: Number of syncs in the sync array
|
||||
* specified in @DRM_XE_OA_PROPERTY_SYNCS
|
||||
* specified in %DRM_XE_OA_PROPERTY_SYNCS
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_NUM_SYNCS,
|
||||
|
||||
/**
|
||||
* @DRM_XE_OA_PROPERTY_SYNCS: Pointer to struct @drm_xe_sync array
|
||||
* with array size specified via @DRM_XE_OA_PROPERTY_NUM_SYNCS. OA
|
||||
* @DRM_XE_OA_PROPERTY_SYNCS: Pointer to &struct drm_xe_sync array
|
||||
* with array size specified via %DRM_XE_OA_PROPERTY_NUM_SYNCS. OA
|
||||
* configuration will wait till input fences signal. Output fences
|
||||
* will signal after the new OA configuration takes effect. For
|
||||
* @DRM_XE_SYNC_TYPE_USER_FENCE, @addr is a user pointer, similar
|
||||
* %DRM_XE_SYNC_TYPE_USER_FENCE, addr is a user pointer, similar
|
||||
* to the VM bind case.
|
||||
*/
|
||||
DRM_XE_OA_PROPERTY_SYNCS,
|
||||
|
|
@ -2011,9 +2011,9 @@ enum drm_xe_oa_property_id {
|
|||
/**
|
||||
* struct drm_xe_oa_config - OA metric configuration
|
||||
*
|
||||
* Multiple OA configs can be added using @DRM_XE_OBSERVATION_OP_ADD_CONFIG. A
|
||||
* Multiple OA configs can be added using %DRM_XE_OBSERVATION_OP_ADD_CONFIG. A
|
||||
* particular config can be specified when opening an OA stream using
|
||||
* @DRM_XE_OA_PROPERTY_OA_METRIC_SET property.
|
||||
* %DRM_XE_OA_PROPERTY_OA_METRIC_SET property.
|
||||
*/
|
||||
struct drm_xe_oa_config {
|
||||
/** @extensions: Pointer to the first extension struct, if any */
|
||||
|
|
@ -2034,7 +2034,7 @@ struct drm_xe_oa_config {
|
|||
|
||||
/**
|
||||
* struct drm_xe_oa_stream_status - OA stream status returned from
|
||||
* @DRM_XE_OBSERVATION_IOCTL_STATUS observation stream fd ioctl. Userspace can
|
||||
* %DRM_XE_OBSERVATION_IOCTL_STATUS observation stream fd ioctl. Userspace can
|
||||
* call the ioctl to query stream status in response to EIO errno from
|
||||
* observation fd read().
|
||||
*/
|
||||
|
|
@ -2055,7 +2055,7 @@ struct drm_xe_oa_stream_status {
|
|||
|
||||
/**
|
||||
* struct drm_xe_oa_stream_info - OA stream info returned from
|
||||
* @DRM_XE_OBSERVATION_IOCTL_INFO observation stream fd ioctl
|
||||
* %DRM_XE_OBSERVATION_IOCTL_INFO observation stream fd ioctl
|
||||
*/
|
||||
struct drm_xe_oa_stream_info {
|
||||
/** @extensions: Pointer to the first extension struct, if any */
|
||||
|
|
@ -2092,27 +2092,27 @@ enum drm_xe_pxp_session_type {
|
|||
* enum drm_xe_eu_stall_property_id - EU stall sampling input property ids.
|
||||
*
|
||||
* These properties are passed to the driver at open as a chain of
|
||||
* @drm_xe_ext_set_property structures with @property set to these
|
||||
* properties' enums and @value set to the corresponding values of these
|
||||
* properties. @drm_xe_user_extension base.name should be set to
|
||||
* @DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY.
|
||||
* &struct drm_xe_ext_set_property structures with property set to these
|
||||
* properties' enums and value set to the corresponding values of these
|
||||
* properties. &struct drm_xe_user_extension base.name should be set to
|
||||
* %DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY.
|
||||
*
|
||||
* With the file descriptor obtained from open, user space must enable
|
||||
* the EU stall stream fd with @DRM_XE_OBSERVATION_IOCTL_ENABLE before
|
||||
* the EU stall stream fd with %DRM_XE_OBSERVATION_IOCTL_ENABLE before
|
||||
* calling read(). EIO errno from read() indicates HW dropped data
|
||||
* due to full buffer.
|
||||
*/
|
||||
enum drm_xe_eu_stall_property_id {
|
||||
#define DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY 0
|
||||
/**
|
||||
* @DRM_XE_EU_STALL_PROP_GT_ID: @gt_id of the GT on which
|
||||
* @DRM_XE_EU_STALL_PROP_GT_ID: gt_id of the GT on which
|
||||
* EU stall data will be captured.
|
||||
*/
|
||||
DRM_XE_EU_STALL_PROP_GT_ID = 1,
|
||||
|
||||
/**
|
||||
* @DRM_XE_EU_STALL_PROP_SAMPLE_RATE: Sampling rate in
|
||||
* GPU cycles from @sampling_rates in struct @drm_xe_query_eu_stall
|
||||
* GPU cycles from sampling_rates in &struct drm_xe_query_eu_stall
|
||||
*/
|
||||
DRM_XE_EU_STALL_PROP_SAMPLE_RATE,
|
||||
|
||||
|
|
@ -2127,9 +2127,9 @@ enum drm_xe_eu_stall_property_id {
|
|||
/**
|
||||
* struct drm_xe_query_eu_stall - Information about EU stall sampling.
|
||||
*
|
||||
* If a query is made with a struct @drm_xe_device_query where .query
|
||||
* is equal to @DRM_XE_DEVICE_QUERY_EU_STALL, then the reply uses
|
||||
* struct @drm_xe_query_eu_stall in .data.
|
||||
* If a query is made with a &struct drm_xe_device_query where .query
|
||||
* is equal to %DRM_XE_DEVICE_QUERY_EU_STALL, then the reply uses
|
||||
* &struct drm_xe_query_eu_stall in .data.
|
||||
*/
|
||||
struct drm_xe_query_eu_stall {
|
||||
/** @extensions: Pointer to the first extension struct, if any */
|
||||
|
|
@ -2240,7 +2240,7 @@ struct drm_xe_madvise {
|
|||
|
||||
/**
|
||||
* @preferred_mem_loc.region_instance : Region instance.
|
||||
* MBZ if @devmem_fd <= &DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE.
|
||||
* MBZ if @devmem_fd <= %DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE.
|
||||
* Otherwise should point to the desired device
|
||||
* VRAM instance of the device indicated by
|
||||
* @preferred_mem_loc.devmem_fd.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user