diff mbox series

[v2,03/12] drm/drv: DOC: Add driver example code

Message ID 20190210131039.52664-4-noralf@tronnes.org (mailing list archive)
State New, archived
Headers show
Series drm/tinydrm: Remove tinydrm_device | expand

Commit Message

Noralf Trønnes Feb. 10, 2019, 1:10 p.m. UTC 
Add driver example that shows how devm_drm_dev_init() can be used.

Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
---

I'm not sure how detailed such an example such be and a description of 
some kind is also required. Help is needed :-)

Noralf.

 drivers/gpu/drm/drm_drv.c | 118 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

Comments

Sam Ravnborg Feb. 10, 2019, 9:03 p.m. UTC | #1 
Hi Noralf

On Sun, Feb 10, 2019 at 02:10:30PM +0100, Noralf Trønnes wrote:
> Add driver example that shows how devm_drm_dev_init() can be used.
> 
> Signed-off-by: Noralf Trønnes <noralf@tronnes.org>

Always good with examples!


> ---
> 
> I'm not sure how detailed such an example such be and a description of 
> some kind is also required. Help is needed :-)
> 
> Noralf.
> 
>  drivers/gpu/drm/drm_drv.c | 118 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 118 insertions(+)
> 
> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
> index 351f128ec4b7..99ca3551688f 100644
> --- a/drivers/gpu/drm/drm_drv.c
> +++ b/drivers/gpu/drm/drm_drv.c
> @@ -286,6 +286,124 @@ void drm_minor_release(struct drm_minor *minor)
>   * 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_get() and drm_dev_put() only carefully.
> + *
> + * Display driver example
> + * ~~~~~~~~~~~~~~~~~~~~~~

Maybe add something like this:

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.
The example is used to demonstrate the use of devm_drm_dev_init(), and
shows how the use of a device managed drm_device allows for simpler
remove() and shuttdown() functions.


> + *
> + * .. code-block:: c
> + *
> + *	struct driver_device {
> + *		struct drm_device drm;
> + *		void *userspace_facing;
> + *		struct clk *pclk;
> + *	};
> + *
> + *	static inline struct driver_device *drm_to_priv(struct drm_device *drm)
> + *	{
> + *		return container_of(drm, struct driver_device, drm);
> + *	}
> + *
> + *	static void driver_drm_release(struct drm_device *drm)
> + *	{
> + *		struct driver_device *priv = drm_to_priv(drm);
> + *
> + *		drm_mode_config_cleanup(drm);
> + *		drm_dev_fini(drm);
> + *		kfree(priv->userspace_facing);
> + *		kfree(priv);
> + *	}
> + *
> + *	static struct drm_driver driver_drm_driver = {
> + *		[...]
> + *		.release = driver_drm_release,
> + *	};
> + *
> + *	static int driver_probe(struct platform_device *pdev)
> + *	{
> + *		struct driver_device *priv;
> + *		struct drm_device *drm;
> + *		int ret;
> + *
> + *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
Add a comment that explains why we cannot use devm_kzalloc()?
It is used in a lot of places today...

> + *		if (!priv)
> + *			return -ENOMEM;
> + *
> + *		drm = &priv->drm;
> + *
> + *		ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
> + *		if (ret) {
> + *			kfree(drm);
This should be kfree(priv);

> + *			return ret;
> + *		}
> + *
> + *		drm_mode_config_init(drm);
> + *
> + *		priv->userspace_facing = kzalloc(..., GFP_KERNEL);
> + *		if (!priv->userspace_facing)
> + *			return -ENOMEM;
If we fail here we should also free priv?

> + *
> + *		priv->pclk = devm_clk_get(dev, "PCLK");
> + *		if (IS_ERR(priv->pclk))
> + *			return PTR_ERR(priv->pclk);
> + *
> + *		[ Further setup, display pipeline etc ]
> + *
> + *		drm_mode_config_reset(drm);
> + *
> + *		ret = drm_dev_register(drm);
> + *		if (ret)
> + *			return ret;
> + *
> + *		platform_set_drvdata(pdev, drm);
> + *
> + *		drm_fbdev_generic_setup(drm, 32);
> + *
> + *		return 0;
> + *	}
> + *
> + *	[ This function is called before the devm_ resources are released ]
> + *	static int driver_remove(struct platform_device *pdev)
> + *	{
> + *		struct drm_device *drm = platform_get_drvdata(pdev);
> + *
> + *		drm_dev_unregister(drm);
> + *		drm_atomic_helper_shutdown(drm)
> + *
> + *		return 0;
> + *	}
> + *
> + *	static void driver_shutdown(struct platform_device *pdev)
> + *	{
> + *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
> + *	}
> + *
> + *	static int __maybe_unused driver_pm_suspend(struct device *dev)
> + *	{
> + *		return drm_mode_config_helper_suspend(dev_get_drvdata(dev));
> + *	}
> + *
> + *	static int __maybe_unused driver_pm_resume(struct device *dev)
> + *	{
> + *		drm_mode_config_helper_resume(dev_get_drvdata(dev));
> + *
> + *		return 0;
> + *	}
> + *
> + *	static const struct dev_pm_ops driver_pm_ops = {
> + *		SET_SYSTEM_SLEEP_PM_OPS(driver_pm_suspend, driver_pm_resume)
> + *	};
> + *
> + *	static struct platform_driver driver_driver = {
> + *		.driver = {
> + *			[...]
> + *			.pm = &driver_pm_ops,
> + *		},
> + *		.probe = driver_probe,
> + *		.remove = driver_remove,
> + *		.shutdown = driver_shutdown,
> + *	};
> + *	module_platform_driver(driver_driver);
> + *
>   */
>  
>  /**
> -- 
> 2.20.1
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Noralf Trønnes Feb. 12, 2019, 1:20 p.m. UTC | #2 
Den 10.02.2019 22.03, skrev Sam Ravnborg:
> Hi Noralf
> 
> On Sun, Feb 10, 2019 at 02:10:30PM +0100, Noralf Trønnes wrote:
>> Add driver example that shows how devm_drm_dev_init() can be used.
>>
>> Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
> 
> Always good with examples!
> 
> 
>> ---
>>
>> I'm not sure how detailed such an example such be and a description of 
>> some kind is also required. Help is needed :-)
>>
>> Noralf.
>>
>>  drivers/gpu/drm/drm_drv.c | 118 ++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 118 insertions(+)
>>
>> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
>> index 351f128ec4b7..99ca3551688f 100644
>> --- a/drivers/gpu/drm/drm_drv.c
>> +++ b/drivers/gpu/drm/drm_drv.c
>> @@ -286,6 +286,124 @@ void drm_minor_release(struct drm_minor *minor)
>>   * 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_get() and drm_dev_put() only carefully.
>> + *
>> + * Display driver example
>> + * ~~~~~~~~~~~~~~~~~~~~~~
> 
> Maybe add something like this:
> 
> 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.
> The example is used to demonstrate the use of devm_drm_dev_init(), and
> shows how the use of a device managed drm_device allows for simpler
> remove() and shuttdown() functions.

Using devm_drm_dev_init() doesn't affect the use of shutdown(), and for
remove() it only saves one drm_dev_put(). The main benefit that I see is
for a simpler probe() function.

Maybe the last part can be:

The example is used to demonstrate the use of devm_drm_dev_init() and
its accompanying drm_driver->release callback.

Thanks for helping me with this. Daniel is big on documentation so I try
to follow up, but words for humans isn't my strong side :-)

> 
> 
>> + *
>> + * .. code-block:: c
>> + *
>> + *	struct driver_device {
>> + *		struct drm_device drm;

Maybe I should add a comment for userspace_facing:

     *		[ Represents a resource that is accessed by userspace ]
>> + *		void *userspace_facing;
>> + *		struct clk *pclk;
>> + *	};
>> + *
>> + *	static inline struct driver_device *drm_to_priv(struct drm_device *drm)
>> + *	{
>> + *		return container_of(drm, struct driver_device, drm);
>> + *	}
>> + *
>> + *	static void driver_drm_release(struct drm_device *drm)
>> + *	{
>> + *		struct driver_device *priv = drm_to_priv(drm);
>> + *
>> + *		drm_mode_config_cleanup(drm);
>> + *		drm_dev_fini(drm);
>> + *		kfree(priv->userspace_facing);
>> + *		kfree(priv);
>> + *	}
>> + *
>> + *	static struct drm_driver driver_drm_driver = {
>> + *		[...]
>> + *		.release = driver_drm_release,
>> + *	};
>> + *
>> + *	static int driver_probe(struct platform_device *pdev)
>> + *	{
>> + *		struct driver_device *priv;
>> + *		struct drm_device *drm;
>> + *		int ret;
>> + *
>> + *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
> Add a comment that explains why we cannot use devm_kzalloc()?
> It is used in a lot of places today...

That makes sense:

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.

> 
>> + *		if (!priv)
>> + *			return -ENOMEM;
>> + *
>> + *		drm = &priv->drm;
>> + *
>> + *		ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
>> + *		if (ret) {
>> + *			kfree(drm);
> This should be kfree(priv);
> 
>> + *			return ret;
>> + *		}
>> + *
>> + *		drm_mode_config_init(drm);
>> + *
>> + *		priv->userspace_facing = kzalloc(..., GFP_KERNEL);
>> + *		if (!priv->userspace_facing)
>> + *			return -ENOMEM;
> If we fail here we should also free priv?
> 

This is where one benfit of device managed resources kicks in.
If probing fails, happens in drivers/base/dd.c:really_probe(),
devres_release_all() is called which results in:
devm_drm_dev_init_release() -> drm_dev_put() -> driver_drm_release().

If the driver only uses devm_ managed resources or releases the
resource(s) in drm_driver->release, there's no need for an error path in
the probe function.

The ->userspace_facing resource is an attempt to showcase a resource
that is released in drm_driver->release, but I'm unsure if it's really a
good example. It would have been better to have a real world example.

>> + *
>> + *		priv->pclk = devm_clk_get(dev, "PCLK");
>> + *		if (IS_ERR(priv->pclk))
>> + *			return PTR_ERR(priv->pclk);
>> + *
>> + *		[ Further setup, display pipeline etc ]
>> + *
>> + *		drm_mode_config_reset(drm);
>> + *
>> + *		ret = drm_dev_register(drm);
>> + *		if (ret)
>> + *			return ret;
>> + *
>> + *		platform_set_drvdata(pdev, drm);
>> + *
>> + *		drm_fbdev_generic_setup(drm, 32);
>> + *
>> + *		return 0;
>> + *	}
>> + *
>> + *	[ This function is called before the devm_ resources are released ]
>> + *	static int driver_remove(struct platform_device *pdev)
>> + *	{
>> + *		struct drm_device *drm = platform_get_drvdata(pdev);
>> + *
>> + *		drm_dev_unregister(drm);

You asked about drm_dev_unplug() in the other patch. It is used if the
driver supports device unplug, like for USB or unloading a Device Tree
overlay (not sure if all the pieces exists in mainline yet for that).

Maybe I can add this section after the example:

Drivers that want to support device unplugging (USB, DT overlay unload)
should use drm_dev_unplug() instead of drm_dev_unregister(). The driver
must protect regions that is accessing device resources to avoid use
after they're released. This is done using drm_dev_enter() and
drm_dev_exit(). There is one shortcoming however, drm_dev_unplug() marks
the drm_device as unplugged before drm_atomic_helper_shutdown() is
called. This means that if the disable code paths are protected, they
will not run on regular driver module unload, possibily leaving the
hardware enabled.


>> + *		drm_atomic_helper_shutdown(drm)
>> + *
>> + *		return 0;
>> + *	}
>> + *

I can add a comment for shutdown:

This function is called on kernel restart and shutdown

>> + *	static void driver_shutdown(struct platform_device *pdev)
>> + *	{
>> + *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
>> + *	}
>> + *
>> + *	static int __maybe_unused driver_pm_suspend(struct device *dev)
>> + *	{
>> + *		return drm_mode_config_helper_suspend(dev_get_drvdata(dev));
>> + *	}
>> + *
>> + *	static int __maybe_unused driver_pm_resume(struct device *dev)
>> + *	{
>> + *		drm_mode_config_helper_resume(dev_get_drvdata(dev));
>> + *
>> + *		return 0;
>> + *	}
>> + *
>> + *	static const struct dev_pm_ops driver_pm_ops = {
>> + *		SET_SYSTEM_SLEEP_PM_OPS(driver_pm_suspend, driver_pm_resume)
>> + *	};
>> + *
>> + *	static struct platform_driver driver_driver = {
>> + *		.driver = {
>> + *			[...]
>> + *			.pm = &driver_pm_ops,
>> + *		},
>> + *		.probe = driver_probe,
>> + *		.remove = driver_remove,
>> + *		.shutdown = driver_shutdown,
>> + *	};
>> + *	module_platform_driver(driver_driver);
>> + *
>>   */
>>  
>>  /**
>> -- 
>> 2.20.1
>>
>> _______________________________________________
>> dri-devel mailing list
>> dri-devel@lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Daniel Vetter Feb. 12, 2019, 2:06 p.m. UTC | #3 
On Sun, Feb 10, 2019 at 02:10:30PM +0100, Noralf Trønnes wrote:
> Add driver example that shows how devm_drm_dev_init() can be used.
> 
> Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
> ---
> 
> I'm not sure how detailed such an example such be and a description of 
> some kind is also required. Help is needed :-)

Personally I'd make it more minimal, pseudo-code style, removing most of
the boilerplate (e.g. the container_of wrapper). That way it can highlight
the important bits more. But it's already very minimal.

Wrt text, maybe a minimal intro paragraph. Aside from that looks all good
to me.

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>

One question below.
> 
> Noralf.
> 
>  drivers/gpu/drm/drm_drv.c | 118 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 118 insertions(+)
> 
> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
> index 351f128ec4b7..99ca3551688f 100644
> --- a/drivers/gpu/drm/drm_drv.c
> +++ b/drivers/gpu/drm/drm_drv.c
> @@ -286,6 +286,124 @@ void drm_minor_release(struct drm_minor *minor)
>   * 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_get() and drm_dev_put() only carefully.
> + *
> + * Display driver example
> + * ~~~~~~~~~~~~~~~~~~~~~~
> + *
> + * .. code-block:: c
> + *
> + *	struct driver_device {
> + *		struct drm_device drm;
> + *		void *userspace_facing;
> + *		struct clk *pclk;
> + *	};
> + *
> + *	static inline struct driver_device *drm_to_priv(struct drm_device *drm)
> + *	{
> + *		return container_of(drm, struct driver_device, drm);
> + *	}
> + *
> + *	static void driver_drm_release(struct drm_device *drm)
> + *	{
> + *		struct driver_device *priv = drm_to_priv(drm);
> + *
> + *		drm_mode_config_cleanup(drm);
> + *		drm_dev_fini(drm);
> + *		kfree(priv->userspace_facing);
> + *		kfree(priv);
> + *	}
> + *
> + *	static struct drm_driver driver_drm_driver = {
> + *		[...]
> + *		.release = driver_drm_release,
> + *	};
> + *
> + *	static int driver_probe(struct platform_device *pdev)
> + *	{
> + *		struct driver_device *priv;
> + *		struct drm_device *drm;
> + *		int ret;
> + *
> + *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
> + *		if (!priv)
> + *			return -ENOMEM;
> + *
> + *		drm = &priv->drm;
> + *
> + *		ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
> + *		if (ret) {
> + *			kfree(drm);
> + *			return ret;
> + *		}
> + *
> + *		drm_mode_config_init(drm);
> + *
> + *		priv->userspace_facing = kzalloc(..., GFP_KERNEL);
> + *		if (!priv->userspace_facing)
> + *			return -ENOMEM;
> + *
> + *		priv->pclk = devm_clk_get(dev, "PCLK");
> + *		if (IS_ERR(priv->pclk))
> + *			return PTR_ERR(priv->pclk);
> + *
> + *		[ Further setup, display pipeline etc ]
> + *
> + *		drm_mode_config_reset(drm);
> + *
> + *		ret = drm_dev_register(drm);
> + *		if (ret)
> + *			return ret;
> + *
> + *		platform_set_drvdata(pdev, drm);

Hm, don't we need to set that before registering? Or even before
drm_mode_config_reset? Kinda depends upon what the driver is using the
drvdata for.

> + *
> + *		drm_fbdev_generic_setup(drm, 32);
> + *
> + *		return 0;
> + *	}
> + *
> + *	[ This function is called before the devm_ resources are released ]
> + *	static int driver_remove(struct platform_device *pdev)
> + *	{
> + *		struct drm_device *drm = platform_get_drvdata(pdev);
> + *
> + *		drm_dev_unregister(drm);
> + *		drm_atomic_helper_shutdown(drm)
> + *
> + *		return 0;
> + *	}
> + *
> + *	static void driver_shutdown(struct platform_device *pdev)
> + *	{
> + *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
> + *	}
> + *
> + *	static int __maybe_unused driver_pm_suspend(struct device *dev)
> + *	{
> + *		return drm_mode_config_helper_suspend(dev_get_drvdata(dev));
> + *	}
> + *
> + *	static int __maybe_unused driver_pm_resume(struct device *dev)
> + *	{
> + *		drm_mode_config_helper_resume(dev_get_drvdata(dev));
> + *
> + *		return 0;
> + *	}
> + *
> + *	static const struct dev_pm_ops driver_pm_ops = {
> + *		SET_SYSTEM_SLEEP_PM_OPS(driver_pm_suspend, driver_pm_resume)
> + *	};
> + *
> + *	static struct platform_driver driver_driver = {
> + *		.driver = {
> + *			[...]
> + *			.pm = &driver_pm_ops,
> + *		},
> + *		.probe = driver_probe,
> + *		.remove = driver_remove,
> + *		.shutdown = driver_shutdown,
> + *	};
> + *	module_platform_driver(driver_driver);
> + *
>   */
>  
>  /**
> -- 
> 2.20.1
>
Noralf Trønnes Feb. 12, 2019, 2:37 p.m. UTC | #4 
Den 12.02.2019 15.06, skrev Daniel Vetter:
> On Sun, Feb 10, 2019 at 02:10:30PM +0100, Noralf Trønnes wrote:
>> Add driver example that shows how devm_drm_dev_init() can be used.
>>
>> Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
>> ---
>>
>> I'm not sure how detailed such an example such be and a description of 
>> some kind is also required. Help is needed :-)
> 
> Personally I'd make it more minimal, pseudo-code style, removing most of
> the boilerplate (e.g. the container_of wrapper). That way it can highlight
> the important bits more. But it's already very minimal.
> 
> Wrt text, maybe a minimal intro paragraph. Aside from that looks all good
> to me.
> 
> Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> One question below.
>>
>> Noralf.
>>
>>  drivers/gpu/drm/drm_drv.c | 118 ++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 118 insertions(+)
>>
>> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
>> index 351f128ec4b7..99ca3551688f 100644
>> --- a/drivers/gpu/drm/drm_drv.c
>> +++ b/drivers/gpu/drm/drm_drv.c
>> @@ -286,6 +286,124 @@ void drm_minor_release(struct drm_minor *minor)
>>   * 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_get() and drm_dev_put() only carefully.
>> + *
>> + * Display driver example
>> + * ~~~~~~~~~~~~~~~~~~~~~~
>> + *
>> + * .. code-block:: c
>> + *
>> + *	struct driver_device {
>> + *		struct drm_device drm;
>> + *		void *userspace_facing;
>> + *		struct clk *pclk;
>> + *	};
>> + *
>> + *	static inline struct driver_device *drm_to_priv(struct drm_device *drm)
>> + *	{
>> + *		return container_of(drm, struct driver_device, drm);
>> + *	}
>> + *
>> + *	static void driver_drm_release(struct drm_device *drm)
>> + *	{
>> + *		struct driver_device *priv = drm_to_priv(drm);
>> + *
>> + *		drm_mode_config_cleanup(drm);
>> + *		drm_dev_fini(drm);
>> + *		kfree(priv->userspace_facing);
>> + *		kfree(priv);
>> + *	}
>> + *
>> + *	static struct drm_driver driver_drm_driver = {
>> + *		[...]
>> + *		.release = driver_drm_release,
>> + *	};
>> + *
>> + *	static int driver_probe(struct platform_device *pdev)
>> + *	{
>> + *		struct driver_device *priv;
>> + *		struct drm_device *drm;
>> + *		int ret;
>> + *
>> + *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
>> + *		if (!priv)
>> + *			return -ENOMEM;
>> + *
>> + *		drm = &priv->drm;
>> + *
>> + *		ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
>> + *		if (ret) {
>> + *			kfree(drm);
>> + *			return ret;
>> + *		}
>> + *
>> + *		drm_mode_config_init(drm);
>> + *
>> + *		priv->userspace_facing = kzalloc(..., GFP_KERNEL);
>> + *		if (!priv->userspace_facing)
>> + *			return -ENOMEM;
>> + *
>> + *		priv->pclk = devm_clk_get(dev, "PCLK");
>> + *		if (IS_ERR(priv->pclk))
>> + *			return PTR_ERR(priv->pclk);
>> + *
>> + *		[ Further setup, display pipeline etc ]
>> + *
>> + *		drm_mode_config_reset(drm);
>> + *
>> + *		ret = drm_dev_register(drm);
>> + *		if (ret)
>> + *			return ret;
>> + *
>> + *		platform_set_drvdata(pdev, drm);
> 
> Hm, don't we need to set that before registering? Or even before
> drm_mode_config_reset? Kinda depends upon what the driver is using the
> drvdata for.
> 

Yeah, it depends. I can move up though, it doesn't hurt, since drvdata
is cleared by the driver core if probe fails.

Noralf.

>> + *
>> + *		drm_fbdev_generic_setup(drm, 32);
>> + *
>> + *		return 0;
>> + *	}
>> + *
>> + *	[ This function is called before the devm_ resources are released ]
>> + *	static int driver_remove(struct platform_device *pdev)
>> + *	{
>> + *		struct drm_device *drm = platform_get_drvdata(pdev);
>> + *
>> + *		drm_dev_unregister(drm);
>> + *		drm_atomic_helper_shutdown(drm)
>> + *
>> + *		return 0;
>> + *	}
>> + *
>> + *	static void driver_shutdown(struct platform_device *pdev)
>> + *	{
>> + *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
>> + *	}
>> + *
>> + *	static int __maybe_unused driver_pm_suspend(struct device *dev)
>> + *	{
>> + *		return drm_mode_config_helper_suspend(dev_get_drvdata(dev));
>> + *	}
>> + *
>> + *	static int __maybe_unused driver_pm_resume(struct device *dev)
>> + *	{
>> + *		drm_mode_config_helper_resume(dev_get_drvdata(dev));
>> + *
>> + *		return 0;
>> + *	}
>> + *
>> + *	static const struct dev_pm_ops driver_pm_ops = {
>> + *		SET_SYSTEM_SLEEP_PM_OPS(driver_pm_suspend, driver_pm_resume)
>> + *	};
>> + *
>> + *	static struct platform_driver driver_driver = {
>> + *		.driver = {
>> + *			[...]
>> + *			.pm = &driver_pm_ops,
>> + *		},
>> + *		.probe = driver_probe,
>> + *		.remove = driver_remove,
>> + *		.shutdown = driver_shutdown,
>> + *	};
>> + *	module_platform_driver(driver_driver);
>> + *
>>   */
>>  
>>  /**
>> -- 
>> 2.20.1
>>
>
diff mbox series

Patch

diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
index 351f128ec4b7..99ca3551688f 100644
--- a/drivers/gpu/drm/drm_drv.c
+++ b/drivers/gpu/drm/drm_drv.c
@@ -286,6 +286,124 @@  void drm_minor_release(struct drm_minor *minor)
  * 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_get() and drm_dev_put() only carefully.
+ *
+ * Display driver example
+ * ~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * .. code-block:: c
+ *
+ *	struct driver_device {
+ *		struct drm_device drm;
+ *		void *userspace_facing;
+ *		struct clk *pclk;
+ *	};
+ *
+ *	static inline struct driver_device *drm_to_priv(struct drm_device *drm)
+ *	{
+ *		return container_of(drm, struct driver_device, drm);
+ *	}
+ *
+ *	static void driver_drm_release(struct drm_device *drm)
+ *	{
+ *		struct driver_device *priv = drm_to_priv(drm);
+ *
+ *		drm_mode_config_cleanup(drm);
+ *		drm_dev_fini(drm);
+ *		kfree(priv->userspace_facing);
+ *		kfree(priv);
+ *	}
+ *
+ *	static struct drm_driver driver_drm_driver = {
+ *		[...]
+ *		.release = driver_drm_release,
+ *	};
+ *
+ *	static int driver_probe(struct platform_device *pdev)
+ *	{
+ *		struct driver_device *priv;
+ *		struct drm_device *drm;
+ *		int ret;
+ *
+ *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
+ *		if (!priv)
+ *			return -ENOMEM;
+ *
+ *		drm = &priv->drm;
+ *
+ *		ret = devm_drm_dev_init(&pdev->dev, drm, &driver_drm_driver);
+ *		if (ret) {
+ *			kfree(drm);
+ *			return ret;
+ *		}
+ *
+ *		drm_mode_config_init(drm);
+ *
+ *		priv->userspace_facing = kzalloc(..., GFP_KERNEL);
+ *		if (!priv->userspace_facing)
+ *			return -ENOMEM;
+ *
+ *		priv->pclk = devm_clk_get(dev, "PCLK");
+ *		if (IS_ERR(priv->pclk))
+ *			return PTR_ERR(priv->pclk);
+ *
+ *		[ Further setup, display pipeline etc ]
+ *
+ *		drm_mode_config_reset(drm);
+ *
+ *		ret = drm_dev_register(drm);
+ *		if (ret)
+ *			return ret;
+ *
+ *		platform_set_drvdata(pdev, drm);
+ *
+ *		drm_fbdev_generic_setup(drm, 32);
+ *
+ *		return 0;
+ *	}
+ *
+ *	[ This function is called before the devm_ resources are released ]
+ *	static int driver_remove(struct platform_device *pdev)
+ *	{
+ *		struct drm_device *drm = platform_get_drvdata(pdev);
+ *
+ *		drm_dev_unregister(drm);
+ *		drm_atomic_helper_shutdown(drm)
+ *
+ *		return 0;
+ *	}
+ *
+ *	static void driver_shutdown(struct platform_device *pdev)
+ *	{
+ *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
+ *	}
+ *
+ *	static int __maybe_unused driver_pm_suspend(struct device *dev)
+ *	{
+ *		return drm_mode_config_helper_suspend(dev_get_drvdata(dev));
+ *	}
+ *
+ *	static int __maybe_unused driver_pm_resume(struct device *dev)
+ *	{
+ *		drm_mode_config_helper_resume(dev_get_drvdata(dev));
+ *
+ *		return 0;
+ *	}
+ *
+ *	static const struct dev_pm_ops driver_pm_ops = {
+ *		SET_SYSTEM_SLEEP_PM_OPS(driver_pm_suspend, driver_pm_resume)
+ *	};
+ *
+ *	static struct platform_driver driver_driver = {
+ *		.driver = {
+ *			[...]
+ *			.pm = &driver_pm_ops,
+ *		},
+ *		.probe = driver_probe,
+ *		.remove = driver_remove,
+ *		.shutdown = driver_shutdown,
+ *	};
+ *	module_platform_driver(driver_driver);
+ *
  */
 
 /**