Re: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'

kbuild test robot
2019-10-13T19:30:27Z

[-- Attachment #1: Type: text/plain, Size: 16652 bytes --]

Hi Changbin,

Thank you for the patch! Perhaps something to improve:

[auto build test WARNING on linus/master]
[cannot apply to v5.4-rc2 next-20191010]
[if your patch is applied to the wrong git tree, please drop us a note to help
improve the system. BTW, we also suggest to use '--base' option to specify the
base tree in git format-patch, please see https://stackoverflow.com/a/37406982]

url: https://github.com/0day-ci/linux/commits/Changbin-Du/kernel-doc-rename-the-kernel-doc-directive-functions-to-specific/20191014-013215
reproduce: make htmldocs

If you fix the issue, kindly add following tag
Reported-by: kbuild test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.
WARNING: dot(1) not found, for better output quality install graphviz from http://www.graphviz.org
WARNING: convert(1) not found, for SVG to PDF conversion install ImageMagick (https://www.imagemagick.org)
Error: Cannot open file drivers/dma-buf/reservation.c
Error: Cannot open file drivers/dma-buf/reservation.c
Error: Cannot open file drivers/dma-buf/reservation.c
Error: Cannot open file include/linux/reservation.h
Error: Cannot open file include/linux/reservation.h
>> include/linux/regulator/machine.h:196: warning: struct member 'max_uV_step' not described in 'regulation_constraints'
>> include/linux/regulator/driver.h:223: warning: struct member 'resume' not described in 'regulator_ops'
>> include/linux/i2c.h:337: warning: struct member 'init_irq' not described in 'i2c_client'
drivers/gpio/gpiolib-of.c:92: warning: Excess function parameter 'dev' description in 'of_gpio_need_valid_mask'
>> include/linux/spi/spi.h:190: warning: struct member 'driver_override' not described in 'spi_device'
mm/util.c:1: warning: 'get_user_pages_fast' not found
>> mm/slab.c:4215: warning: function parameter 'objp' not described in '__ksize'
drivers/usb/typec/bus.c:1: warning: 'typec_altmode_register_driver' not found
drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found
drivers/usb/typec/class.c:1: warning: 'typec_altmode_unregister_notifier' not found
drivers/usb/typec/class.c:1: warning: 'typec_altmode_register_notifier' not found
>> include/linux/w1.h:277: warning: struct member 'of_match_table' not described in 'w1_family'
drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c:335: warning: Excess function parameter 'dev' description in 'amdgpu_gem_prime_export'
drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c:336: warning: Excess function parameter 'dev' description in 'amdgpu_gem_prime_export'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c:142: warning: function parameter 'blockable' not described in 'amdgpu_mn_read_lock'
drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:347: warning: cannot understand function prototype: 'struct amdgpu_vm_pt_cursor '
drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:348: warning: cannot understand function prototype: 'struct amdgpu_vm_pt_cursor '
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:494: warning: function parameter 'start' not described in 'amdgpu_vm_pt_first_dfs'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'adev' not described in 'for_each_amdgpu_vm_pt_dfs_safe'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'vm' not described in 'for_each_amdgpu_vm_pt_dfs_safe'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'start' not described in 'for_each_amdgpu_vm_pt_dfs_safe'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'cursor' not described in 'for_each_amdgpu_vm_pt_dfs_safe'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'entry' not described in 'for_each_amdgpu_vm_pt_dfs_safe'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:821: warning: function parameter 'level' not described in 'amdgpu_vm_bo_param'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'params' not described in 'amdgpu_vm_update_flags'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'bo' not described in 'amdgpu_vm_update_flags'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'level' not described in 'amdgpu_vm_update_flags'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'pe' not described in 'amdgpu_vm_update_flags'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'addr' not described in 'amdgpu_vm_update_flags'
>> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter 'count' not described in 'amdgpu_vm_update_flags'

vim +1207 drivers/gpu/drm/i915/i915_drv.h

eec688e1420da5 Robert Bragg 2016-11-07 1069
16d98b31f80775 Robert Bragg 2016-12-07 1070 /**
16d98b31f80775 Robert Bragg 2016-12-07 1071 * struct i915_perf_stream - state for a single open stream FD
16d98b31f80775 Robert Bragg 2016-12-07 1072 */
eec688e1420da5 Robert Bragg 2016-11-07 1073 struct i915_perf_stream {
16d98b31f80775 Robert Bragg 2016-12-07 1074 /**
16d98b31f80775 Robert Bragg 2016-12-07 1075 * @dev_priv: i915 drm device
16d98b31f80775 Robert Bragg 2016-12-07 1076 */
eec688e1420da5 Robert Bragg 2016-11-07 1077 struct drm_i915_private *dev_priv;
eec688e1420da5 Robert Bragg 2016-11-07 1078
16d98b31f80775 Robert Bragg 2016-12-07 1079 /**
16d98b31f80775 Robert Bragg 2016-12-07 1080 * @link: Links the stream into ``&drm_i915_private->streams``
16d98b31f80775 Robert Bragg 2016-12-07 1081 */
eec688e1420da5 Robert Bragg 2016-11-07 1082 struct list_head link;
eec688e1420da5 Robert Bragg 2016-11-07 1083
6d2438c8233bd0 Chris Wilson 2019-01-15 1084 /**
6d2438c8233bd0 Chris Wilson 2019-01-15 1085 * @wakeref: As we keep the device awake while the perf stream is
6d2438c8233bd0 Chris Wilson 2019-01-15 1086 * active, we track our runtime pm reference for later release.
6d2438c8233bd0 Chris Wilson 2019-01-15 1087 */
6619c0075f784d Chris Wilson 2019-01-14 1088 intel_wakeref_t wakeref;
6619c0075f784d Chris Wilson 2019-01-14 1089
16d98b31f80775 Robert Bragg 2016-12-07 1090 /**
16d98b31f80775 Robert Bragg 2016-12-07 1091 * @sample_flags: Flags representing the `DRM_I915_PERF_PROP_SAMPLE_*`
16d98b31f80775 Robert Bragg 2016-12-07 1092 * properties given when opening a stream, representing the contents
16d98b31f80775 Robert Bragg 2016-12-07 1093 * of a single sample as read() by userspace.
16d98b31f80775 Robert Bragg 2016-12-07 1094 */
eec688e1420da5 Robert Bragg 2016-11-07 1095 u32 sample_flags;
16d98b31f80775 Robert Bragg 2016-12-07 1096
16d98b31f80775 Robert Bragg 2016-12-07 1097 /**
16d98b31f80775 Robert Bragg 2016-12-07 1098 * @sample_size: Considering the configured contents of a sample
16d98b31f80775 Robert Bragg 2016-12-07 1099 * combined with the required header size, this is the total size
16d98b31f80775 Robert Bragg 2016-12-07 1100 * of a single sample record.
16d98b31f80775 Robert Bragg 2016-12-07 1101 */
d79651522e89c4 Robert Bragg 2016-11-07 1102 int sample_size;
eec688e1420da5 Robert Bragg 2016-11-07 1103
16d98b31f80775 Robert Bragg 2016-12-07 1104 /**
16d98b31f80775 Robert Bragg 2016-12-07 1105 * @ctx: %NULL if measuring system-wide across all contexts or a
16d98b31f80775 Robert Bragg 2016-12-07 1106 * specific context that is being monitored.
16d98b31f80775 Robert Bragg 2016-12-07 1107 */
eec688e1420da5 Robert Bragg 2016-11-07 1108 struct i915_gem_context *ctx;
16d98b31f80775 Robert Bragg 2016-12-07 1109
16d98b31f80775 Robert Bragg 2016-12-07 1110 /**
16d98b31f80775 Robert Bragg 2016-12-07 1111 * @enabled: Whether the stream is currently enabled, considering
16d98b31f80775 Robert Bragg 2016-12-07 1112 * whether the stream was opened in a disabled state and based
16d98b31f80775 Robert Bragg 2016-12-07 1113 * on `I915_PERF_IOCTL_ENABLE` and `I915_PERF_IOCTL_DISABLE` calls.
16d98b31f80775 Robert Bragg 2016-12-07 1114 */
eec688e1420da5 Robert Bragg 2016-11-07 1115 bool enabled;
eec688e1420da5 Robert Bragg 2016-11-07 1116
16d98b31f80775 Robert Bragg 2016-12-07 1117 /**
16d98b31f80775 Robert Bragg 2016-12-07 1118 * @ops: The callbacks providing the implementation of this specific
16d98b31f80775 Robert Bragg 2016-12-07 1119 * type of configured stream.
16d98b31f80775 Robert Bragg 2016-12-07 1120 */
d79651522e89c4 Robert Bragg 2016-11-07 1121 const struct i915_perf_stream_ops *ops;
701f8231a2fe17 Lionel Landwerlin 2017-08-03 1122
701f8231a2fe17 Lionel Landwerlin 2017-08-03 1123 /**
701f8231a2fe17 Lionel Landwerlin 2017-08-03 1124 * @oa_config: The OA configuration used by the stream.
701f8231a2fe17 Lionel Landwerlin 2017-08-03 1125 */
701f8231a2fe17 Lionel Landwerlin 2017-08-03 1126 struct i915_oa_config *oa_config;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1127
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1128 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1129 * The OA context specific information.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1130 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1131 struct intel_context *pinned_ctx;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1132 u32 specific_ctx_id;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1133 u32 specific_ctx_id_mask;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1134
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1135 struct hrtimer poll_check_timer;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1136 wait_queue_head_t poll_wq;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1137 bool pollin;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1138
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1139 bool periodic;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1140 int period_exponent;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1141
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1142 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1143 * State of the OA buffer.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1144 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1145 struct {
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1146 struct i915_vma *vma;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1147 u8 *vaddr;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1148 u32 last_ctx_id;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1149 int format;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1150 int format_size;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1151 int size_exponent;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1152
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1153 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1154 * Locks reads and writes to all head/tail state
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1155 *
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1156 * Consider: the head and tail pointer state needs to be read
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1157 * consistently from a hrtimer callback (atomic context) and
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1158 * read() fop (user context) with tail pointer updates happening
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1159 * in atomic context and head updates in user context and the
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1160 * (unlikely) possibility of read() errors needing to reset all
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1161 * head/tail state.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1162 *
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1163 * Note: Contention/performance aren't currently a significant
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1164 * concern here considering the relatively low frequency of
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1165 * hrtimer callbacks (5ms period) and that reads typically only
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1166 * happen in response to a hrtimer event and likely complete
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1167 * before the next callback.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1168 *
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1169 * Note: This lock is not held *while* reading and copying data
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1170 * to userspace so the value of head observed in htrimer
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1171 * callbacks won't represent any partial consumption of data.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1172 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1173 spinlock_t ptr_lock;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1174
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1175 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1176 * One 'aging' tail pointer and one 'aged' tail pointer ready to
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1177 * used for reading.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1178 *
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1179 * Initial values of 0xffffffff are invalid and imply that an
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1180 * update is required (and should be ignored by an attempted
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1181 * read)
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1182 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1183 struct {
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1184 u32 offset;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1185 } tails[2];
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1186
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1187 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1188 * Index for the aged tail ready to read() data up to.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1189 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1190 unsigned int aged_tail_idx;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1191
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1192 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1193 * A monotonic timestamp for when the current aging tail pointer
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1194 * was read; used to determine when it is old enough to trust.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1195 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1196 u64 aging_timestamp;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1197
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1198 /**
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 @1199 * Although we can always read back the head pointer register,
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1200 * we prefer to avoid trusting the HW state, just to avoid any
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1201 * risk that some hardware condition could * somehow bump the
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1202 * head pointer unpredictably and cause us to forward the wrong
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1203 * OA buffer data to userspace.
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1204 */
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1205 u32 head;
a37f08a882b01a Umesh Nerlige Ramappa 2019-08-06 1206 } oa_buffer;
d79651522e89c4 Robert Bragg 2016-11-07 @1207 };
d79651522e89c4 Robert Bragg 2016-11-07 1208

:::::: The code at line 1207 was first introduced by commit
:::::: d79651522e89c4ffa8992b48dfe449f0c583f809 drm/i915: Enable i915 perf stream for Haswell OA unit

:::::: TO: Robert Bragg <robert@sixbynine.org>
:::::: CC: Daniel Vetter <daniel.vetter@ffwll.ch>

---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 7279 bytes --]