History

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

Shuicheng Lin committed 7 months ago

Commit 4bd87e71 parent ea842c21 file · +53 −53Browse files

Showing the changes to include/uapi (1 of 1 file). Show all

Unified · Split

include/uapi/drm/xe_drm.h+53−53
@@ -229,9 +229,9 @@ struct drm_xe_ext_set_property { · 228 unmodified lines
229229 /**
230230 * struct drm_xe_engine_class_instance - instance of an engine class
231231 *
232− * It is returned as part of the @drm_xe_engine, but it also is used as
233− * the input of engine selection for both @drm_xe_exec_queue_create and
234− * @drm_xe_query_engine_cycles
232+ * It is returned as part of the &struct drm_xe_engine, but it also is used as
233+ * the input of engine selection for both &struct drm_xe_exec_queue_create and
234+ * &struct drm_xe_query_engine_cycles
235235 *
236236 * The @engine_class can be:
237237 * - %DRM_XE_ENGINE_CLASS_RENDER
@@ -264,7 +264,7 @@ struct drm_xe_engine_class_instance { · 26 unmodified lines
264264 * struct drm_xe_engine - describe hardware engine
265265 */
266266 struct drm_xe_engine {
267− /** @instance: The @drm_xe_engine_class_instance */
267+ /** @instance: The &struct drm_xe_engine_class_instance */
268268 struct drm_xe_engine_class_instance instance;
269269
270270 /** @reserved: Reserved */
@@ -274,9 +274,9 @@ struct drm_xe_engine { · 3 unmodified lines
274274 /**
275275 * struct drm_xe_query_engines - describe engines
276276 *
277− * If a query is made with a struct @drm_xe_device_query where .query
277+ * If a query is made with a &struct drm_xe_device_query where .query
278278 * is equal to %DRM_XE_DEVICE_QUERY_ENGINES, then the reply uses an array of
279− * struct @drm_xe_query_engines in .data.
279+ * &struct drm_xe_query_engines in .data.
280280 */
281281 struct drm_xe_query_engines {
282282 /** @num_engines: number of engines returned in @engines */
@@ -825,7 +825,7 @@ struct drm_xe_device_query { · 542 unmodified lines
825825 *
826826 * This ioctl supports setting the following properties via the
827827 * %DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY extension, which uses the
828− * generic @drm_xe_ext_set_property struct:
828+ * generic &struct drm_xe_ext_set_property:
829829 *
830830 * - %DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE - set the type of PXP session
831831 * this object will be used with. Valid values are listed in enum
@@ -1198,10 +1198,10 @@ struct drm_xe_vm_bind_op { · 366 unmodified lines
11981198 /**
11991199 * struct drm_xe_vm_bind - Input of &DRM_IOCTL_XE_VM_BIND
12001200 *
1201− * Below is an example of a minimal use of @drm_xe_vm_bind to
1201+ * Below is an example of a minimal use of &struct drm_xe_vm_bind to
12021202 * asynchronously bind the buffer `data` at address `BIND_ADDRESS` to
12031203 * illustrate `userptr`. It can be synchronized by using the example
1204− * provided for @drm_xe_sync.
1204+ * provided for &struct drm_xe_sync.
12051205 *
12061206 * .. code-block:: C
12071207 *
@@ -1354,7 +1354,7 @@ struct drm_xe_vm_get_property { · 146 unmodified lines
13541354 *
13551355 * This ioctl supports setting the following properties via the
13561356 * %DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY extension, which uses the
1357− * generic @drm_xe_ext_set_property struct:
1357+ * generic &struct drm_xe_ext_set_property:
13581358 *
13591359 * - %DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY - set the queue priority.
13601360 * CAP_SYS_NICE is required to set a value above normal.
@@ -1389,9 +1389,9 @@ struct drm_xe_vm_get_property { · 28 unmodified lines
13891389 * enable render color cache keying on BTP+BTI instead of just BTI
13901390 * (only valid for render queues).
13911391 *
1392− * The example below shows how to use @drm_xe_exec_queue_create to create
1392+ * The example below shows how to use &struct drm_xe_exec_queue_create to create
13931393 * a simple exec_queue (no parallel submission) of class
1394− * &DRM_XE_ENGINE_CLASS_RENDER.
1394+ * %DRM_XE_ENGINE_CLASS_RENDER.
13951395 *
13961396 * .. code-block:: C
13971397 *
@@ -1514,7 +1514,7 @@ struct drm_xe_exec_queue_get_property { · 116 unmodified lines
15141514 * and the @flags can be:
15151515 * - %DRM_XE_SYNC_FLAG_SIGNAL
15161516 *
1517− * A minimal use of @drm_xe_sync looks like this:
1517+ * A minimal use of &struct drm_xe_sync looks like this:
15181518 *
15191519 * .. code-block:: C
15201520 *
@@ -1580,10 +1580,10 @@ struct drm_xe_sync { · 59 unmodified lines
15801580 /**
15811581 * struct drm_xe_exec - Input of &DRM_IOCTL_XE_EXEC
15821582 *
1583− * This is an example to use @drm_xe_exec for execution of the object
1584− * at BIND_ADDRESS (see example in @drm_xe_vm_bind) by an exec_queue
1585− * (see example in @drm_xe_exec_queue_create). It can be synchronized
1586− * by using the example provided for @drm_xe_sync.
1583+ * This is an example to use &struct drm_xe_exec for execution of the object
1584+ * at BIND_ADDRESS (see example in &struct drm_xe_vm_bind) by an exec_queue
1585+ * (see example in &struct drm_xe_exec_queue_create). It can be synchronized
1586+ * by using the example provided for &struct drm_xe_sync.
15871587 *
15881588 * .. code-block:: C
15891589 *
@@ -1749,9 +1749,9 @@ enum drm_xe_observation_op { · 159 unmodified lines
17491749 struct drm_xe_observation_param {
17501750 /** @extensions: Pointer to the first extension struct, if any */
17511751 __u64 extensions;
1752− /** @observation_type: observation stream type, of enum @drm_xe_observation_type */
1752+ /** @observation_type: observation stream type, of &enum drm_xe_observation_type */
17531753 __u64 observation_type;
1754− /** @observation_op: observation stream op, of enum @drm_xe_observation_op */
1754+ /** @observation_op: observation stream op, of &enum drm_xe_observation_op */
17551755 __u64 observation_op;
17561756 /** @param: Pointer to actual stream params */
17571757 __u64 param;
@@ -1810,7 +1810,7 @@ struct drm_xe_oa_unit { · 52 unmodified lines
18101810 /** @oa_unit_id: OA unit ID */
18111811 __u32 oa_unit_id;
18121812
1813− /** @oa_unit_type: OA unit type of @drm_xe_oa_unit_type */
1813+ /** @oa_unit_type: OA unit type of &enum drm_xe_oa_unit_type */
18141814 __u32 oa_unit_type;
18151815
18161816 /** @capabilities: OA capabilities bit-mask */
@@ -1873,7 +1873,7 @@ struct drm_xe_query_oa_units { · 56 unmodified lines
18731873 /** @pad: MBZ */
18741874 __u32 pad;
18751875 /**
1876− * @oa_units: struct @drm_xe_oa_unit array returned for this device.
1876+ * @oa_units: &struct drm_xe_oa_unit array returned for this device.
18771877 * Written below as a u64 array to avoid problems with nested flexible
18781878 * arrays with some compilers
18791879 */
@@ -1902,22 +1902,22 @@ enum drm_xe_oa_format_type { · 22 unmodified lines
19021902 /**
19031903 * enum drm_xe_oa_property_id - OA stream property IDs
19041904 *
1905− * Stream params are specified as a chain of @drm_xe_ext_set_property
1906− * structs, with @property values from enum @drm_xe_oa_property_id and
1907− * @drm_xe_user_extension base.name set to @DRM_XE_OA_EXTENSION_SET_PROPERTY.
1908− * @param field in struct @drm_xe_observation_param points to the first
1909− * @drm_xe_ext_set_property struct.
1905+ * Stream params are specified as a chain of &struct drm_xe_ext_set_property
1906+ * structs, with property values from &enum drm_xe_oa_property_id and
1907+ * &struct drm_xe_user_extension base.name set to %DRM_XE_OA_EXTENSION_SET_PROPERTY.
1908+ * The param field in &struct drm_xe_observation_param points to the first
1909+ * &struct drm_xe_ext_set_property struct.
19101910 *
19111911 * Exactly the same mechanism is also used for stream reconfiguration using the
1912− * @DRM_XE_OBSERVATION_IOCTL_CONFIG observation stream fd ioctl, though only a
1912+ * %DRM_XE_OBSERVATION_IOCTL_CONFIG observation stream fd ioctl, though only a
19131913 * subset of properties below can be specified for stream reconfiguration.
19141914 */
19151915 enum drm_xe_oa_property_id {
19161916 #define DRM_XE_OA_EXTENSION_SET_PROPERTY 0
19171917 /**
19181918 * @DRM_XE_OA_PROPERTY_OA_UNIT_ID: ID of the OA unit on which to open
1919− * the OA stream, see @oa_unit_id in 'struct
1920− * drm_xe_oa_unit'. Defaults to 0 if not provided.
1919+ * the OA stream, see oa_unit_id in &struct drm_xe_oa_unit.
1920+ * Defaults to 0 if not provided.
19211921 */
19221922 DRM_XE_OA_PROPERTY_OA_UNIT_ID = 1,
19231923
@@ -1930,7 +1930,7 @@ enum drm_xe_oa_property_id { · 6 unmodified lines
19301930
19311931 /**
19321932 * @DRM_XE_OA_PROPERTY_OA_METRIC_SET: OA metrics defining contents of OA
1933− * reports, previously added via @DRM_XE_OBSERVATION_OP_ADD_CONFIG.
1933+ * reports, previously added via %DRM_XE_OBSERVATION_OP_ADD_CONFIG.
19341934 */
19351935 DRM_XE_OA_PROPERTY_OA_METRIC_SET,
19361936
@@ -1938,7 +1938,7 @@ enum drm_xe_oa_property_id { · 1 unmodified line
19381938 DRM_XE_OA_PROPERTY_OA_FORMAT,
19391939 /*
19401940 * OA_FORMAT's are specified the same way as in PRM/Bspec 52198/60942,
1941− * in terms of the following quantities: a. enum @drm_xe_oa_format_type
1941+ * in terms of the following quantities: a. &enum drm_xe_oa_format_type
19421942 * b. Counter select c. Counter size and d. BC report. Also refer to the
19431943 * oa_formats array in drivers/gpu/drm/xe/xe_oa.c.
19441944 */
@@ -1955,19 +1955,19 @@ enum drm_xe_oa_property_id { · 10 unmodified lines
19551955
19561956 /**
19571957 * @DRM_XE_OA_PROPERTY_OA_DISABLED: A value of 1 will open the OA
1958− * stream in a DISABLED state (see @DRM_XE_OBSERVATION_IOCTL_ENABLE).
1958+ * stream in a DISABLED state (see %DRM_XE_OBSERVATION_IOCTL_ENABLE).
19591959 */
19601960 DRM_XE_OA_PROPERTY_OA_DISABLED,
19611961
19621962 /**
19631963 * @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID: Open the stream for a specific
1964− * @exec_queue_id. OA queries can be executed on this exec queue.
1964+ * exec_queue_id. OA queries can be executed on this exec queue.
19651965 */
19661966 DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID,
19671967
19681968 /**
19691969 * @DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE: Optional engine instance to
1970− * pass along with @DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID or will default to 0.
1970+ * pass along with %DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID or will default to 0.
19711971 */
19721972 DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE,
19731973
@@ -1979,16 +1979,16 @@ enum drm_xe_oa_property_id { · 5 unmodified lines
19791979
19801980 /**
19811981 * @DRM_XE_OA_PROPERTY_NUM_SYNCS: Number of syncs in the sync array
1982− * specified in @DRM_XE_OA_PROPERTY_SYNCS
1982+ * specified in %DRM_XE_OA_PROPERTY_SYNCS
19831983 */
19841984 DRM_XE_OA_PROPERTY_NUM_SYNCS,
19851985
19861986 /**
1987− * @DRM_XE_OA_PROPERTY_SYNCS: Pointer to struct @drm_xe_sync array
1988− * with array size specified via @DRM_XE_OA_PROPERTY_NUM_SYNCS. OA
1987+ * @DRM_XE_OA_PROPERTY_SYNCS: Pointer to &struct drm_xe_sync array
1988+ * with array size specified via %DRM_XE_OA_PROPERTY_NUM_SYNCS. OA
19891989 * configuration will wait till input fences signal. Output fences
19901990 * will signal after the new OA configuration takes effect. For
1991− * @DRM_XE_SYNC_TYPE_USER_FENCE, @addr is a user pointer, similar
1991+ * %DRM_XE_SYNC_TYPE_USER_FENCE, addr is a user pointer, similar
19921992 * to the VM bind case.
19931993 */
19941994 DRM_XE_OA_PROPERTY_SYNCS,
@@ -2011,9 +2011,9 @@ enum drm_xe_oa_property_id { · 16 unmodified lines
20112011 /**
20122012 * struct drm_xe_oa_config - OA metric configuration
20132013 *
2014− * Multiple OA configs can be added using @DRM_XE_OBSERVATION_OP_ADD_CONFIG. A
2014+ * Multiple OA configs can be added using %DRM_XE_OBSERVATION_OP_ADD_CONFIG. A
20152015 * particular config can be specified when opening an OA stream using
2016− * @DRM_XE_OA_PROPERTY_OA_METRIC_SET property.
2016+ * %DRM_XE_OA_PROPERTY_OA_METRIC_SET property.
20172017 */
20182018 struct drm_xe_oa_config {
20192019 /** @extensions: Pointer to the first extension struct, if any */
@@ -2034,7 +2034,7 @@ struct drm_xe_oa_config { · 14 unmodified lines
20342034
20352035 /**
20362036 * struct drm_xe_oa_stream_status - OA stream status returned from
2037− * @DRM_XE_OBSERVATION_IOCTL_STATUS observation stream fd ioctl. Userspace can
2037+ * %DRM_XE_OBSERVATION_IOCTL_STATUS observation stream fd ioctl. Userspace can
20382038 * call the ioctl to query stream status in response to EIO errno from
20392039 * observation fd read().
20402040 */
@@ -2055,7 +2055,7 @@ struct drm_xe_oa_stream_status { · 14 unmodified lines
20552055
20562056 /**
20572057 * struct drm_xe_oa_stream_info - OA stream info returned from
2058− * @DRM_XE_OBSERVATION_IOCTL_INFO observation stream fd ioctl
2058+ * %DRM_XE_OBSERVATION_IOCTL_INFO observation stream fd ioctl
20592059 */
20602060 struct drm_xe_oa_stream_info {
20612061 /** @extensions: Pointer to the first extension struct, if any */
@@ -2092,27 +2092,27 @@ enum drm_xe_pxp_session_type { · 30 unmodified lines
20922092 * enum drm_xe_eu_stall_property_id - EU stall sampling input property ids.
20932093 *
20942094 * These properties are passed to the driver at open as a chain of
2095− * @drm_xe_ext_set_property structures with @property set to these
2096− * properties' enums and @value set to the corresponding values of these
2097− * properties. @drm_xe_user_extension base.name should be set to
2098− * @DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY.
2095+ * &struct drm_xe_ext_set_property structures with property set to these
2096+ * properties' enums and value set to the corresponding values of these
2097+ * properties. &struct drm_xe_user_extension base.name should be set to
2098+ * %DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY.
20992099 *
21002100 * With the file descriptor obtained from open, user space must enable
2101− * the EU stall stream fd with @DRM_XE_OBSERVATION_IOCTL_ENABLE before
2101+ * the EU stall stream fd with %DRM_XE_OBSERVATION_IOCTL_ENABLE before
21022102 * calling read(). EIO errno from read() indicates HW dropped data
21032103 * due to full buffer.
21042104 */
21052105 enum drm_xe_eu_stall_property_id {
21062106 #define DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY 0
21072107 /**
2108− * @DRM_XE_EU_STALL_PROP_GT_ID: @gt_id of the GT on which
2108+ * @DRM_XE_EU_STALL_PROP_GT_ID: gt_id of the GT on which
21092109 * EU stall data will be captured.
21102110 */
21112111 DRM_XE_EU_STALL_PROP_GT_ID = 1,
21122112
21132113 /**
21142114 * @DRM_XE_EU_STALL_PROP_SAMPLE_RATE: Sampling rate in
2115− * GPU cycles from @sampling_rates in struct @drm_xe_query_eu_stall
2115+ * GPU cycles from sampling_rates in &struct drm_xe_query_eu_stall
21162116 */
21172117 DRM_XE_EU_STALL_PROP_SAMPLE_RATE,
21182118
@@ -2127,9 +2127,9 @@ enum drm_xe_eu_stall_property_id { · 8 unmodified lines
21272127 /**
21282128 * struct drm_xe_query_eu_stall - Information about EU stall sampling.
21292129 *
2130− * If a query is made with a struct @drm_xe_device_query where .query
2131− * is equal to @DRM_XE_DEVICE_QUERY_EU_STALL, then the reply uses
2132− * struct @drm_xe_query_eu_stall in .data.
2130+ * If a query is made with a &struct drm_xe_device_query where .query
2131+ * is equal to %DRM_XE_DEVICE_QUERY_EU_STALL, then the reply uses
2132+ * &struct drm_xe_query_eu_stall in .data.
21332133 */
21342134 struct drm_xe_query_eu_stall {
21352135 /** @extensions: Pointer to the first extension struct, if any */
@@ -2240,7 +2240,7 @@ struct drm_xe_madvise { · 104 unmodified lines
22402240
22412241 /**
22422242 * @preferred_mem_loc.region_instance : Region instance.
2243− * MBZ if @devmem_fd <= &DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE.
2243+ * MBZ if @devmem_fd <= %DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE.
22442244 * Otherwise should point to the desired device
22452245 * VRAM instance of the device indicated by
22462246 * @preferred_mem_loc.devmem_fd.