diff options
Diffstat (limited to 'drivers/gpu/drm/drm_drv.c')
| -rw-r--r-- | drivers/gpu/drm/drm_drv.c | 55 |
1 files changed, 51 insertions, 4 deletions
diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c index 9ad823fcde87..d01f8d6c5fdb 100644 --- a/drivers/gpu/drm/drm_drv.c +++ b/drivers/gpu/drm/drm_drv.c @@ -397,15 +397,51 @@ void drm_minor_release(struct drm_minor *minor) } /** + * DOC: driver instance overview + * + * A device instance for a drm driver is represented by struct &drm_device. This + * is allocated with drm_dev_alloc(), usually from bus-specific ->probe() + * callbacks implemented by the driver. The driver then needs to initialize all + * the various subsystems for the drm device like memory management, vblank + * handling, modesetting support and intial output configuration plus obviously + * initialize all the corresponding hardware bits. An important part of this is + * also calling drm_dev_set_unique() to set the userspace-visible unique name of + * this device instance. Finally when everything is up and running and ready for + * userspace the device instance can be published using drm_dev_register(). + * + * There is also deprecated support for initalizing device instances using + * bus-specific helpers and the ->load() callback. But due to + * backwards-compatibility needs the device instance have to be published too + * early, which requires unpretty global locking to make safe and is therefore + * only support for existing drivers not yet converted to the new scheme. + * + * When cleaning up a device instance everything needs to be done in reverse: + * First unpublish the device instance with drm_dev_unregister(). Then clean up + * any other resources allocated at device initialization and drop the driver's + * reference to &drm_device using drm_dev_unref(). + * + * Note that the lifetime rules for &drm_device instance has still a lot of + * historical baggage. Hence use the reference counting provided by + * drm_dev_ref() and drm_dev_unref() only carefully. + * + * Also note that embedding of &drm_device is currently not (yet) supported (but + * it would be easy to add). Drivers can store driver-private data in the + * dev_priv field of &drm_device. + */ + +/** * drm_put_dev - Unregister and release a DRM device * @dev: DRM device * * Called at module unload time or when a PCI device is unplugged. * - * Use of this function is discouraged. It will eventually go away completely. - * Please use drm_dev_unregister() and drm_dev_unref() explicitly instead. - * * Cleans up all DRM device, calling drm_lastclose(). + * + * Note: Use of this function is deprecated. It will eventually go away + * completely. Please use drm_dev_unregister() and drm_dev_unref() explicitly + * instead to make sure that the device isn't userspace accessible any more + * while teardown is in progress, ensuring that userspace can't access an + * inconsistent state. */ void drm_put_dev(struct drm_device *dev) { @@ -518,7 +554,9 @@ static void drm_fs_inode_free(struct inode *inode) * * Allocate and initialize a new DRM device. No device registration is done. * Call drm_dev_register() to advertice the device to user space and register it - * with other core subsystems. + * with other core subsystems. This should be done last in the device + * initialization sequence to make sure userspace can't access an inconsistent + * state. * * The initial ref-count of the object is 1. Use drm_dev_ref() and * drm_dev_unref() to take and drop further ref-counts. @@ -673,6 +711,12 @@ EXPORT_SYMBOL(drm_dev_unref); * * Never call this twice on any device! * + * NOTE: To ensure backward compatibility with existing drivers method this + * function calls the ->load() method after registering the device nodes, + * creating race conditions. Usage of the ->load() methods is therefore + * deprecated, drivers must perform all initialization before calling + * drm_dev_register(). + * * RETURNS: * 0 on success, negative error code on failure. */ @@ -720,6 +764,9 @@ EXPORT_SYMBOL(drm_dev_register); * Unregister the DRM device from the system. This does the reverse of * drm_dev_register() but does not deallocate the device. The caller must call * drm_dev_unref() to drop their final reference. + * + * This should be called first in the device teardown code to make sure + * userspace can't access the device instance any more. */ void drm_dev_unregister(struct drm_device *dev) { |