drm/managed: Cleanup of unused functions and polishing docs

Following functions are only used internally, not by drivers:
- devm_drm_dev_init

Also, now that we have a very slick and polished way to allocate a
drm_device with devm_drm_dev_alloc, update all the docs to reflect the
new reality. Mostly this consists of deleting old and misleading
hints. Two main ones:

- it is no longer required that the drm_device base class is first in
  the structure. devm_drm_dev_alloc can cope with it being anywhere

- obviously embedded now strongly recommends using devm_drm_dev_alloc

v2: Fix typos (Noralf)

v3: Split out the removal of drm_dev_init, that's blocked on some
discussions on how to convert vgem/vkms/i915-selftests. Adjust commit
message to reflect that.

Cc: Noralf Trønnes <noralf@tronnes.org>
Acked-by: Noralf Trønnes <noralf@tronnes.org> (v2)
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Cc: Luben Tuikov <luben.tuikov@amd.com>
Cc: amd-gfx@lists.freedesktop.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20200902072627.3617301-1-daniel.vetter@ffwll.ch

diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst
index eaaaafc21134f1bbff9c8d10f6750943bd08e47f..aa4d2420f79e81e8fba3e5a36e84869c14b8122c 100644 (file)
--- a/Documentation/driver-api/driver-model/devres.rst
+++ b/Documentation/driver-api/driver-model/devres.rst
@@ -263,7 +263,7 @@ DMA
   dmam_pool_destroy()
 
 DRM
-  devm_drm_dev_init()
+  devm_drm_dev_alloc()
 
 GPIO
   devm_gpiod_get()

diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
index 13068fdf4331a2c814400364b94e1b179d15c1e7..3b70f91e4316a2661e513a5622f5e44083c14bb6 100644 (file)
--- a/drivers/gpu/drm/drm_drv.c
+++ b/drivers/gpu/drm/drm_drv.c
@@ -240,13 +240,13 @@ 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 initialized with drm_dev_init(), 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. Finally when everything is up
- * and running and ready for userspace the device instance can be published
- * using drm_dev_register().
+ * is allocated and initialized with devm_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 initial output
+ * configuration plus obviously initialize all the corresponding hardware bits.
+ * 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 &drm_driver.load callback. But due to
@@ -274,7 +274,7 @@ void drm_minor_release(struct drm_minor *minor)
  *
  * The following example shows a typical structure of a DRM display driver.
  * The example focus on the probe() function and the other functions that is
- * almost always present and serves as a demonstration of devm_drm_dev_init().
+ * almost always present and serves as a demonstration of devm_drm_dev_alloc().
  *
  * .. code-block:: c
  *
@@ -294,22 +294,12 @@ void drm_minor_release(struct drm_minor *minor)
  *             struct drm_device *drm;
  *             int ret;
  *
- *             // devm_kzalloc() can't be used here because the drm_device '
- *             // lifetime can exceed the device lifetime if driver unbind
- *             // happens when userspace still has open file descriptors.
- *             priv = kzalloc(sizeof(*priv), GFP_KERNEL);
- *             if (!priv)
- *                     return -ENOMEM;
- *
+ *             priv = devm_drm_dev_alloc(&pdev->dev, &driver_drm_driver,
+ *                                       struct driver_device, drm);
+ *             if (IS_ERR(priv))
+ *                     return PTR_ERR(priv);
  *             drm = &priv->drm;
  *
- *             ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
- *             if (ret) {
- *                     kfree(priv);
- *                     return ret;
- *             }
- *             drmm_add_final_kfree(drm, priv);
- *
  *             ret = drmm_mode_config_init(drm);
  *             if (ret)
  *                     return ret;
@@ -550,9 +540,9 @@ static void drm_fs_inode_free(struct inode *inode)
  * following guidelines apply:
  *
  *  - The entire device initialization procedure should be run from the
- *    &component_master_ops.master_bind callback, starting with drm_dev_init(),
- *    then binding all components with component_bind_all() and finishing with
- *    drm_dev_register().
+ *    &component_master_ops.master_bind callback, starting with
+ *    devm_drm_dev_alloc(), then binding all components with
+ *    component_bind_all() and finishing with drm_dev_register().
  *
  *  - The opaque pointer passed to all components through component_bind_all()
  *    should point at &struct drm_device of the device instance, not some driver
@@ -706,24 +696,9 @@ static void devm_drm_dev_init_release(void *data)
        drm_dev_put(data);
 }
 
-/**
- * devm_drm_dev_init - Resource managed drm_dev_init()
- * @parent: Parent device object
- * @dev: DRM device
- * @driver: DRM driver
- *
- * Managed drm_dev_init(). The DRM device initialized with this function is
- * automatically put on driver detach using drm_dev_put().
- *
- * Note that drivers must call drmm_add_final_kfree() after this function has
- * completed successfully.
- *
- * RETURNS:
- * 0 on success, or error code on failure.
- */
-int devm_drm_dev_init(struct device *parent,
-                     struct drm_device *dev,
-                     struct drm_driver *driver)
+static int devm_drm_dev_init(struct device *parent,
+                            struct drm_device *dev,
+                            struct drm_driver *driver)
 {
        int ret;
 
@@ -737,7 +712,6 @@ int devm_drm_dev_init(struct device *parent,
 
        return ret;
 }
-EXPORT_SYMBOL(devm_drm_dev_init);
 
 void *__devm_drm_dev_alloc(struct device *parent, struct drm_driver *driver,
                           size_t size, size_t offset)
@@ -767,19 +741,9 @@ EXPORT_SYMBOL(__devm_drm_dev_alloc);
  * @driver: DRM driver to allocate device for
  * @parent: Parent device object
  *
- * 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. 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_get() and
- * drm_dev_put() to take and drop further ref-counts.
- *
- * Note that for purely virtual devices @parent can be NULL.
- *
- * Drivers that wish to subclass or embed &struct drm_device into their
- * own struct should look at using drm_dev_init() instead.
+ * This is the deprecated version of devm_drm_dev_alloc(), which does not support
+ * subclassing through embedding the struct &drm_device in a driver private
+ * structure, and which does not support automatic cleanup through devres.
  *
  * RETURNS:
  * Pointer to new DRM device, or ERR_PTR on failure.

diff --git a/drivers/gpu/drm/drm_managed.c b/drivers/gpu/drm/drm_managed.c
index 1e1356560c2ef9d10594741aa3022cb919d3a614..c36e3d98fd7131e25084020bd2031108a9d05bc5 100644 (file)
--- a/drivers/gpu/drm/drm_managed.c
+++ b/drivers/gpu/drm/drm_managed.c
@@ -27,7 +27,7 @@
  * be done directly with drmm_kmalloc() and the related functions. Everything
  * will be released on the final drm_dev_put() in reverse order of how the
  * release actions have been added and memory has been allocated since driver
- * loading started with drm_dev_init().
+ * loading started with devm_drm_dev_alloc().
  *
  * Note that release actions and managed memory can also be added and removed
  * during the lifetime of the driver, all the functions are fully concurrent

diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index 0988351d743c446454a7bfb4e1a35158afabb955..f4f68e7a9149ed721d6ed4588333078958f46f9a 100644 (file)
--- a/include/drm/drm_device.h
+++ b/include/drm/drm_device.h
@@ -92,7 +92,7 @@ struct drm_device {
         * NULL.
         *
         * Instead of using this pointer it is recommended that drivers use
-        * drm_dev_init() and embed struct &drm_device in their larger
+        * devm_drm_dev_alloc() and embed struct &drm_device in their larger
         * per-device structure.
         */
        void *dev_private;

diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index 7116abc1a04e039d8b46e73a93e8b7293d02bacd..9b11a2f0babc088d59bf392502e36ed39b5c05e3 100644 (file)
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -163,13 +163,12 @@ struct drm_driver {
        /**
         * @load:
         *
-        * Backward-compatible driver callback to complete
-        * initialization steps after the driver is registered.  For
-        * this reason, may suffer from race conditions and its use is
-        * deprecated for new drivers.  It is therefore only supported
-        * for existing drivers not yet converted to the new scheme.
-        * See drm_dev_init() and drm_dev_register() for proper and
-        * race-free way to set up a &struct drm_device.
+        * Backward-compatible driver callback to complete initialization steps
+        * after the driver is registered.  For this reason, may suffer from
+        * race conditions and its use is deprecated for new drivers.  It is
+        * therefore only supported for existing drivers not yet converted to
+        * the new scheme.  See devm_drm_dev_alloc() and drm_dev_register() for
+        * proper and race-free way to set up a &struct drm_device.
         *
         * This is deprecated, do not use!
         *
@@ -592,9 +591,6 @@ struct drm_driver {
 int drm_dev_init(struct drm_device *dev,
                 struct drm_driver *driver,
                 struct device *parent);
-int devm_drm_dev_init(struct device *parent,
-                     struct drm_device *dev,
-                     struct drm_driver *driver);
 
 void *__devm_drm_dev_alloc(struct device *parent, struct drm_driver *driver,
                           size_t size, size_t offset);