* [android-common:android13-5.10 1023/29766] htmldocs: ./include/drm/drm_drv.h:492: warning: Incorrect use of kernel-doc format: * @gem_prime_get_uuid
@ 2023-08-21 16:50 kernel test robot
0 siblings, 0 replies; only message in thread
From: kernel test robot @ 2023-08-21 16:50 UTC (permalink / raw)
To: cros-kernel-buildreports; +Cc: oe-kbuild-all
tree: https://android.googlesource.com/kernel/common android13-5.10
head: c69294897c585e659328b3c6b747643af883015a
commit: 5674a23c0c7199882393fcd3eb327c6d668349c0 [1023/29766] FROMLIST: drm/prime: add support for virtio exported objects
reproduce: (https://download.01.org/0day-ci/archive/20230822/202308220049.K2TvCamX-lkp@intel.com/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202308220049.K2TvCamX-lkp@intel.com/
All warnings (new ones prefixed by >>):
>> ./include/drm/drm_drv.h:492: warning: Incorrect use of kernel-doc format: * @gem_prime_get_uuid
>> ./include/drm/drm_drv.h:626: warning: Function parameter or member 'gem_prime_get_uuid' not described in 'drm_driver'
vim +492 ./include/drm/drm_drv.h
153
154 /**
155 * struct drm_driver - DRM driver structure
156 *
157 * This structure represent the common code for a family of cards. There will be
158 * one &struct drm_device for each card present in this family. It contains lots
159 * of vfunc entries, and a pile of those probably should be moved to more
160 * appropriate places like &drm_mode_config_funcs or into a new operations
161 * structure for GEM drivers.
162 */
163 struct drm_driver {
164 /**
165 * @load:
166 *
167 * Backward-compatible driver callback to complete
168 * initialization steps after the driver is registered. For
169 * this reason, may suffer from race conditions and its use is
170 * deprecated for new drivers. It is therefore only supported
171 * for existing drivers not yet converted to the new scheme.
172 * See drm_dev_init() and drm_dev_register() for proper and
173 * race-free way to set up a &struct drm_device.
174 *
175 * This is deprecated, do not use!
176 *
177 * Returns:
178 *
179 * Zero on success, non-zero value on failure.
180 */
181 int (*load) (struct drm_device *, unsigned long flags);
182
183 /**
184 * @open:
185 *
186 * Driver callback when a new &struct drm_file is opened. Useful for
187 * setting up driver-private data structures like buffer allocators,
188 * execution contexts or similar things. Such driver-private resources
189 * must be released again in @postclose.
190 *
191 * Since the display/modeset side of DRM can only be owned by exactly
192 * one &struct drm_file (see &drm_file.is_master and &drm_device.master)
193 * there should never be a need to set up any modeset related resources
194 * in this callback. Doing so would be a driver design bug.
195 *
196 * Returns:
197 *
198 * 0 on success, a negative error code on failure, which will be
199 * promoted to userspace as the result of the open() system call.
200 */
201 int (*open) (struct drm_device *, struct drm_file *);
202
203 /**
204 * @postclose:
205 *
206 * One of the driver callbacks when a new &struct drm_file is closed.
207 * Useful for tearing down driver-private data structures allocated in
208 * @open like buffer allocators, execution contexts or similar things.
209 *
210 * Since the display/modeset side of DRM can only be owned by exactly
211 * one &struct drm_file (see &drm_file.is_master and &drm_device.master)
212 * there should never be a need to tear down any modeset related
213 * resources in this callback. Doing so would be a driver design bug.
214 */
215 void (*postclose) (struct drm_device *, struct drm_file *);
216
217 /**
218 * @lastclose:
219 *
220 * Called when the last &struct drm_file has been closed and there's
221 * currently no userspace client for the &struct drm_device.
222 *
223 * Modern drivers should only use this to force-restore the fbdev
224 * framebuffer using drm_fb_helper_restore_fbdev_mode_unlocked().
225 * Anything else would indicate there's something seriously wrong.
226 * Modern drivers can also use this to execute delayed power switching
227 * state changes, e.g. in conjunction with the :ref:`vga_switcheroo`
228 * infrastructure.
229 *
230 * This is called after @postclose hook has been called.
231 *
232 * NOTE:
233 *
234 * All legacy drivers use this callback to de-initialize the hardware.
235 * This is purely because of the shadow-attach model, where the DRM
236 * kernel driver does not really own the hardware. Instead ownershipe is
237 * handled with the help of userspace through an inheritedly racy dance
238 * to set/unset the VT into raw mode.
239 *
240 * Legacy drivers initialize the hardware in the @firstopen callback,
241 * which isn't even called for modern drivers.
242 */
243 void (*lastclose) (struct drm_device *);
244
245 /**
246 * @unload:
247 *
248 * Reverse the effects of the driver load callback. Ideally,
249 * the clean up performed by the driver should happen in the
250 * reverse order of the initialization. Similarly to the load
251 * hook, this handler is deprecated and its usage should be
252 * dropped in favor of an open-coded teardown function at the
253 * driver layer. See drm_dev_unregister() and drm_dev_put()
254 * for the proper way to remove a &struct drm_device.
255 *
256 * The unload() hook is called right after unregistering
257 * the device.
258 *
259 */
260 void (*unload) (struct drm_device *);
261
262 /**
263 * @release:
264 *
265 * Optional callback for destroying device data after the final
266 * reference is released, i.e. the device is being destroyed. Drivers
267 * using this callback are responsible for calling drm_dev_fini()
268 * to finalize the device and then freeing the struct themselves.
269 */
270 void (*release) (struct drm_device *);
271
272 /**
273 * @irq_handler:
274 *
275 * Interrupt handler called when using drm_irq_install(). Not used by
276 * drivers which implement their own interrupt handling.
277 */
278 irqreturn_t(*irq_handler) (int irq, void *arg);
279
280 /**
281 * @irq_preinstall:
282 *
283 * Optional callback used by drm_irq_install() which is called before
284 * the interrupt handler is registered. This should be used to clear out
285 * any pending interrupts (from e.g. firmware based drives) and reset
286 * the interrupt handling registers.
287 */
288 void (*irq_preinstall) (struct drm_device *dev);
289
290 /**
291 * @irq_postinstall:
292 *
293 * Optional callback used by drm_irq_install() which is called after
294 * the interrupt handler is registered. This should be used to enable
295 * interrupt generation in the hardware.
296 */
297 int (*irq_postinstall) (struct drm_device *dev);
298
299 /**
300 * @irq_uninstall:
301 *
302 * Optional callback used by drm_irq_uninstall() which is called before
303 * the interrupt handler is unregistered. This should be used to disable
304 * interrupt generation in the hardware.
305 */
306 void (*irq_uninstall) (struct drm_device *dev);
307
308 /**
309 * @master_set:
310 *
311 * Called whenever the minor master is set. Only used by vmwgfx.
312 */
313 int (*master_set)(struct drm_device *dev, struct drm_file *file_priv,
314 bool from_open);
315 /**
316 * @master_drop:
317 *
318 * Called whenever the minor master is dropped. Only used by vmwgfx.
319 */
320 void (*master_drop)(struct drm_device *dev, struct drm_file *file_priv);
321
322 /**
323 * @debugfs_init:
324 *
325 * Allows drivers to create driver-specific debugfs files.
326 */
327 int (*debugfs_init)(struct drm_minor *minor);
328
329 /**
330 * @gem_free_object: deconstructor for drm_gem_objects
331 *
332 * This is deprecated and should not be used by new drivers. Use
333 * &drm_gem_object_funcs.free instead.
334 */
335 void (*gem_free_object) (struct drm_gem_object *obj);
336
337 /**
338 * @gem_free_object_unlocked: deconstructor for drm_gem_objects
339 *
340 * This is deprecated and should not be used by new drivers. Use
341 * &drm_gem_object_funcs.free instead.
342 * Compared to @gem_free_object this is not encumbered with
343 * &drm_device.struct_mutex legacy locking schemes.
344 */
345 void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
346
347 /**
348 * @gem_open_object:
349 *
350 * This callback is deprecated in favour of &drm_gem_object_funcs.open.
351 *
352 * Driver hook called upon gem handle creation
353 */
354 int (*gem_open_object) (struct drm_gem_object *, struct drm_file *);
355
356 /**
357 * @gem_close_object:
358 *
359 * This callback is deprecated in favour of &drm_gem_object_funcs.close.
360 *
361 * Driver hook called upon gem handle release
362 */
363 void (*gem_close_object) (struct drm_gem_object *, struct drm_file *);
364
365 /**
366 * @gem_print_info:
367 *
368 * This callback is deprecated in favour of
369 * &drm_gem_object_funcs.print_info.
370 *
371 * If driver subclasses struct &drm_gem_object, it can implement this
372 * optional hook for printing additional driver specific info.
373 *
374 * drm_printf_indent() should be used in the callback passing it the
375 * indent argument.
376 *
377 * This callback is called from drm_gem_print_info().
378 */
379 void (*gem_print_info)(struct drm_printer *p, unsigned int indent,
380 const struct drm_gem_object *obj);
381
382 /**
383 * @gem_create_object: constructor for gem objects
384 *
385 * Hook for allocating the GEM object struct, for use by the CMA and
386 * SHMEM GEM helpers.
387 */
388 struct drm_gem_object *(*gem_create_object)(struct drm_device *dev,
389 size_t size);
390 /**
391 * @prime_handle_to_fd:
392 *
393 * Main PRIME export function. Should be implemented with
394 * drm_gem_prime_handle_to_fd() for GEM based drivers.
395 *
396 * For an in-depth discussion see :ref:`PRIME buffer sharing
397 * documentation <prime_buffer_sharing>`.
398 */
399 int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv,
400 uint32_t handle, uint32_t flags, int *prime_fd);
401 /**
402 * @prime_fd_to_handle:
403 *
404 * Main PRIME import function. Should be implemented with
405 * drm_gem_prime_fd_to_handle() for GEM based drivers.
406 *
407 * For an in-depth discussion see :ref:`PRIME buffer sharing
408 * documentation <prime_buffer_sharing>`.
409 */
410 int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv,
411 int prime_fd, uint32_t *handle);
412 /**
413 * @gem_prime_export:
414 *
415 * Export hook for GEM drivers. Deprecated in favour of
416 * &drm_gem_object_funcs.export.
417 */
418 struct dma_buf * (*gem_prime_export)(struct drm_gem_object *obj,
419 int flags);
420 /**
421 * @gem_prime_import:
422 *
423 * Import hook for GEM drivers.
424 *
425 * This defaults to drm_gem_prime_import() if not set.
426 */
427 struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
428 struct dma_buf *dma_buf);
429
430 /**
431 * @gem_prime_pin:
432 *
433 * Deprecated hook in favour of &drm_gem_object_funcs.pin.
434 */
435 int (*gem_prime_pin)(struct drm_gem_object *obj);
436
437 /**
438 * @gem_prime_unpin:
439 *
440 * Deprecated hook in favour of &drm_gem_object_funcs.unpin.
441 */
442 void (*gem_prime_unpin)(struct drm_gem_object *obj);
443
444
445 /**
446 * @gem_prime_get_sg_table:
447 *
448 * Deprecated hook in favour of &drm_gem_object_funcs.get_sg_table.
449 */
450 struct sg_table *(*gem_prime_get_sg_table)(struct drm_gem_object *obj);
451
452 /**
453 * @gem_prime_import_sg_table:
454 *
455 * Optional hook used by the PRIME helper functions
456 * drm_gem_prime_import() respectively drm_gem_prime_import_dev().
457 */
458 struct drm_gem_object *(*gem_prime_import_sg_table)(
459 struct drm_device *dev,
460 struct dma_buf_attachment *attach,
461 struct sg_table *sgt);
462 /**
463 * @gem_prime_vmap:
464 *
465 * Deprecated vmap hook for GEM drivers. Please use
466 * &drm_gem_object_funcs.vmap instead.
467 */
468 void *(*gem_prime_vmap)(struct drm_gem_object *obj);
469
470 /**
471 * @gem_prime_vunmap:
472 *
473 * Deprecated vunmap hook for GEM drivers. Please use
474 * &drm_gem_object_funcs.vunmap instead.
475 */
476 void (*gem_prime_vunmap)(struct drm_gem_object *obj, void *vaddr);
477
478 /**
479 * @gem_prime_mmap:
480 *
481 * mmap hook for GEM drivers, used to implement dma-buf mmap in the
482 * PRIME helpers.
483 *
484 * FIXME: There's way too much duplication going on here, and also moved
485 * to &drm_gem_object_funcs.
486 */
487 int (*gem_prime_mmap)(struct drm_gem_object *obj,
488 struct vm_area_struct *vma);
489
490 /**
491 * @gem_prime_get_uuid
> 492 *
493 * get_uuid hook for GEM drivers. Retrieves the virtio uuid of the
494 * given GEM buffer.
495 */
496 int (*gem_prime_get_uuid)(struct drm_gem_object *obj,
497 uuid_t *uuid);
498
499 /**
500 * @dumb_create:
501 *
502 * This creates a new dumb buffer in the driver's backing storage manager (GEM,
503 * TTM or something else entirely) and returns the resulting buffer handle. This
504 * handle can then be wrapped up into a framebuffer modeset object.
505 *
506 * Note that userspace is not allowed to use such objects for render
507 * acceleration - drivers must create their own private ioctls for such a use
508 * case.
509 *
510 * Width, height and depth are specified in the &drm_mode_create_dumb
511 * argument. The callback needs to fill the handle, pitch and size for
512 * the created buffer.
513 *
514 * Called by the user via ioctl.
515 *
516 * Returns:
517 *
518 * Zero on success, negative errno on failure.
519 */
520 int (*dumb_create)(struct drm_file *file_priv,
521 struct drm_device *dev,
522 struct drm_mode_create_dumb *args);
523 /**
524 * @dumb_map_offset:
525 *
526 * Allocate an offset in the drm device node's address space to be able to
527 * memory map a dumb buffer.
528 *
529 * The default implementation is drm_gem_create_mmap_offset(). GEM based
530 * drivers must not overwrite this.
531 *
532 * Called by the user via ioctl.
533 *
534 * Returns:
535 *
536 * Zero on success, negative errno on failure.
537 */
538 int (*dumb_map_offset)(struct drm_file *file_priv,
539 struct drm_device *dev, uint32_t handle,
540 uint64_t *offset);
541 /**
542 * @dumb_destroy:
543 *
544 * This destroys the userspace handle for the given dumb backing storage buffer.
545 * Since buffer objects must be reference counted in the kernel a buffer object
546 * won't be immediately freed if a framebuffer modeset object still uses it.
547 *
548 * Called by the user via ioctl.
549 *
550 * The default implementation is drm_gem_dumb_destroy(). GEM based drivers
551 * must not overwrite this.
552 *
553 * Returns:
554 *
555 * Zero on success, negative errno on failure.
556 */
557 int (*dumb_destroy)(struct drm_file *file_priv,
558 struct drm_device *dev,
559 uint32_t handle);
560
561 /**
562 * @gem_vm_ops: Driver private ops for this object
563 *
564 * For GEM drivers this is deprecated in favour of
565 * &drm_gem_object_funcs.vm_ops.
566 */
567 const struct vm_operations_struct *gem_vm_ops;
568
569 /** @major: driver major number */
570 int major;
571 /** @minor: driver minor number */
572 int minor;
573 /** @patchlevel: driver patch level */
574 int patchlevel;
575 /** @name: driver name */
576 char *name;
577 /** @desc: driver description */
578 char *desc;
579 /** @date: driver date */
580 char *date;
581
582 /**
583 * @driver_features:
584 * Driver features, see &enum drm_driver_feature. Drivers can disable
585 * some features on a per-instance basis using
586 * &drm_device.driver_features.
587 */
588 u32 driver_features;
589
590 /**
591 * @ioctls:
592 *
593 * Array of driver-private IOCTL description entries. See the chapter on
594 * :ref:`IOCTL support in the userland interfaces
595 * chapter<drm_driver_ioctl>` for the full details.
596 */
597
598 const struct drm_ioctl_desc *ioctls;
599 /** @num_ioctls: Number of entries in @ioctls. */
600 int num_ioctls;
601
602 /**
603 * @fops:
604 *
605 * File operations for the DRM device node. See the discussion in
606 * :ref:`file operations<drm_driver_fops>` for in-depth coverage and
607 * some examples.
608 */
609 const struct file_operations *fops;
610
611 /* Everything below here is for legacy driver, never use! */
612 /* private: */
613
614 /* List of devices hanging off this driver with stealth attach. */
615 struct list_head legacy_dev_list;
616 int (*firstopen) (struct drm_device *);
617 void (*preclose) (struct drm_device *, struct drm_file *file_priv);
618 int (*dma_ioctl) (struct drm_device *dev, void *data, struct drm_file *file_priv);
619 int (*dma_quiescent) (struct drm_device *);
620 int (*context_dtor) (struct drm_device *dev, int context);
621 u32 (*get_vblank_counter)(struct drm_device *dev, unsigned int pipe);
622 int (*enable_vblank)(struct drm_device *dev, unsigned int pipe);
623 void (*disable_vblank)(struct drm_device *dev, unsigned int pipe);
624 int dev_priv_size;
625 };
> 626
--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-08-21 16:50 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-08-21 16:50 [android-common:android13-5.10 1023/29766] htmldocs: ./include/drm/drm_drv.h:492: warning: Incorrect use of kernel-doc format: * @gem_prime_get_uuid kernel test robot
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.