Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

drm/docs: improve docs for drm_drv.c

Just a bit of drive-by reading:
- drm_dev_set_unique() is really the exception, make that clear.
- drm_dev_init() is the recomended approach.

Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190111164048.29067-1-daniel.vetter@ffwll.ch

+11 -12
+11 -12
drivers/gpu/drm/drm_drv.c
··· 264 264 * DOC: driver instance overview 265 265 * 266 266 * A device instance for a drm driver is represented by &struct drm_device. This 267 - * is allocated with drm_dev_alloc(), usually from bus-specific ->probe() 267 + * is initialized with drm_dev_init(), usually from bus-specific ->probe() 268 268 * callbacks implemented by the driver. The driver then needs to initialize all 269 269 * the various subsystems for the drm device like memory management, vblank 270 270 * handling, modesetting support and intial output configuration plus obviously 271 - * initialize all the corresponding hardware bits. An important part of this is 272 - * also calling drm_dev_set_unique() to set the userspace-visible unique name of 273 - * this device instance. Finally when everything is up and running and ready for 274 - * userspace the device instance can be published using drm_dev_register(). 271 + * initialize all the corresponding hardware bits. Finally when everything is up 272 + * and running and ready for userspace the device instance can be published 273 + * using drm_dev_register(). 275 274 * 276 275 * There is also deprecated support for initalizing device instances using 277 276 * bus-specific helpers and the &drm_driver.load callback. But due to ··· 286 287 * Note that the lifetime rules for &drm_device instance has still a lot of 287 288 * historical baggage. Hence use the reference counting provided by 288 289 * drm_dev_get() and drm_dev_put() only carefully. 289 - * 290 - * It is recommended that drivers embed &struct drm_device into their own device 291 - * structure, which is supported through drm_dev_init(). 292 290 */ 293 291 294 292 /** ··· 470 474 * 471 475 * The initial ref-count of the object is 1. Use drm_dev_get() and 472 476 * drm_dev_put() to take and drop further ref-counts. 477 + * 478 + * It is recommended that drivers embed &struct drm_device into their own device 479 + * structure. 473 480 * 474 481 * Drivers that do not want to allocate their own device struct 475 482 * embedding &struct drm_device can call drm_dev_alloc() instead. For drivers ··· 764 765 * @flags: Flags passed to the driver's .load() function 765 766 * 766 767 * Register the DRM device @dev with the system, advertise device to user-space 767 - * and start normal device operation. @dev must be allocated via drm_dev_alloc() 768 + * and start normal device operation. @dev must be initialized via drm_dev_init() 768 769 * previously. 769 770 * 770 771 * Never call this twice on any device! ··· 876 877 * @dev: device of which to set the unique name 877 878 * @name: unique name 878 879 * 879 - * Sets the unique name of a DRM device using the specified string. Drivers 880 - * can use this at driver probe time if the unique name of the devices they 881 - * drive is static. 880 + * Sets the unique name of a DRM device using the specified string. This is 881 + * already done by drm_dev_init(), drivers should only override the default 882 + * unique name for backwards compatibility reasons. 882 883 * 883 884 * Return: 0 on success or a negative error code on failure. 884 885 */