[PATCH v3] drm/doc: Add sections about tiny drivers and external refs to intro page

[PATCH v3] drm/doc: Add sections about tiny drivers and external refs to intro page

[Javier Martinez Canillas]

Learning about the DRM subsystem could be quite overwhelming for newcomers
but there are lots of useful talks, slides and articles available that can
help to understand the needed concepts and ease the learning curve.

There are also simple DRM drivers that can be used as example about how a
DRM driver should look like.

Add sections to the introduction page, that contains references to these.

Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
---

Changes in v3:
- Fix typos and grammar errors that found when re-reading the changes.

Changes in v2:
- Remove paragraph that gave wrong impression that DRM is complex (Pekka Paalanen).
- Add Thomas Zimmermann's and Pekka Paalanen's Acked-by tags.
- Replace "Learning material" title with "External References" (Thomas Zimmermann).
- Add a section about tiny DRM drivers being a good first example (Daniel Vetter).
- Add some more external references that I found interesting since v1 was posted.

 Documentation/gpu/introduction.rst | 60 ++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
index 25a56e9c0cfd..f05eccd2c07c 100644
--- a/Documentation/gpu/introduction.rst
+++ b/Documentation/gpu/introduction.rst
@@ -112,3 +112,63 @@ Please conduct yourself in a respectful and civilised manner when
 interacting with community members on mailing lists, IRC, or bug
 trackers. The community represents the project as a whole, and abusive
 or bullying behaviour is not tolerated by the project.
+
+Simple DRM drivers to use as examples
+=====================================
+
+The DRM subsystem contains a lot of helper functions to ease writing drivers for
+simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a
+set of drivers that are simple enough to be implemented in a single source file.
+
+These drivers make use of the `struct drm_simple_display_pipe_funcs`, that hides
+any complexity of the DRM subsystem and just requires drivers to implement a few
+functions needed to operate the device. This could be used for devices that just
+need a display pipeline with one full-screen scanout buffer feeding one output.
+
+The tiny DRM drivers are good examples to understand how DRM drivers should look
+like. Since are just a few hundreds lines of code, they are quite easy to read.
+
+External References
+===================
+
+Delving into a Linux kernel subsystem for the first time can be an overwhelming
+experience, one needs to get familiar with all the concepts and learn about the
+subsystem's internals, among other details.
+
+To shallow the learning curve, this section contains a list of presentations
+and documents that can be used to learn about DRM/KMS and graphics in general.
+
+There are different reasons why someone might want to get into DRM: porting an
+existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that
+could face when working on the graphics user-space stack, etc. For this reason,
+the learning material covers many aspects of the Linux graphics stack. From an
+overview of the kernel and user-space stacks to very specific topics.
+
+The list is sorted in reverse chronological order, to keep the most up-to-date
+material at the top. But all of them contain useful information, and it can be
+valuable to go through older material to understand the rationale and context
+in which the changes to the DRM subsystem were made.
+
+Conference talks
+----------------
+
+* `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020)
+* `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020)
+* `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Daniel Vetter (2019)
+* `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017)
+* `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Daniel Vetter (2016)
+* `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015)
+* `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Daniel Vetter (2015)
+* `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013)
+
+Slides and articles
+-------------------
+
+* `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022)
+* `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021)
+* `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017)
+* `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Daniel Vetter (2015)
+* `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Daniel Vetter (2015)
+* `The DRM/KMS subsystem from a newbie’s point of view <https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf>`_ - Boris Brezillon (2014)
+* `A brief introduction to the Linux graphics stack <https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/>`_ - Iago Toral (2014)
+* `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012)
-- 
2.35.1

Re: [PATCH v3] drm/doc: Add sections about tiny drivers and external refs to intro page

[Daniel Vetter]

On Wed, Apr 20, 2022 at 09:24:11AM +0200, Javier Martinez Canillas wrote:
> Learning about the DRM subsystem could be quite overwhelming for newcomers
> but there are lots of useful talks, slides and articles available that can
> help to understand the needed concepts and ease the learning curve.
> 
> There are also simple DRM drivers that can be used as example about how a
> DRM driver should look like.
> 
> Add sections to the introduction page, that contains references to these.
> 
> Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
> Acked-by: Thomas Zimmermann <tzimmermann@suse.de>

Maybe needs more acks to land?

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

Would be good we can hand out links to pretty htmldocs instead of lore
links to this patch, the latter is rather hard on the eyes :-)

Cheers, Daniel

> ---
> 
> Changes in v3:
> - Fix typos and grammar errors that found when re-reading the changes.
> 
> Changes in v2:
> - Remove paragraph that gave wrong impression that DRM is complex (Pekka Paalanen).
> - Add Thomas Zimmermann's and Pekka Paalanen's Acked-by tags.
> - Replace "Learning material" title with "External References" (Thomas Zimmermann).
> - Add a section about tiny DRM drivers being a good first example (Daniel Vetter).
> - Add some more external references that I found interesting since v1 was posted.
> 
>  Documentation/gpu/introduction.rst | 60 ++++++++++++++++++++++++++++++
>  1 file changed, 60 insertions(+)
> 
> diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
> index 25a56e9c0cfd..f05eccd2c07c 100644
> --- a/Documentation/gpu/introduction.rst
> +++ b/Documentation/gpu/introduction.rst
> @@ -112,3 +112,63 @@ Please conduct yourself in a respectful and civilised manner when
>  interacting with community members on mailing lists, IRC, or bug
>  trackers. The community represents the project as a whole, and abusive
>  or bullying behaviour is not tolerated by the project.
> +
> +Simple DRM drivers to use as examples
> +=====================================
> +
> +The DRM subsystem contains a lot of helper functions to ease writing drivers for
> +simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a
> +set of drivers that are simple enough to be implemented in a single source file.
> +
> +These drivers make use of the `struct drm_simple_display_pipe_funcs`, that hides
> +any complexity of the DRM subsystem and just requires drivers to implement a few
> +functions needed to operate the device. This could be used for devices that just
> +need a display pipeline with one full-screen scanout buffer feeding one output.
> +
> +The tiny DRM drivers are good examples to understand how DRM drivers should look
> +like. Since are just a few hundreds lines of code, they are quite easy to read.
> +
> +External References
> +===================
> +
> +Delving into a Linux kernel subsystem for the first time can be an overwhelming
> +experience, one needs to get familiar with all the concepts and learn about the
> +subsystem's internals, among other details.
> +
> +To shallow the learning curve, this section contains a list of presentations
> +and documents that can be used to learn about DRM/KMS and graphics in general.
> +
> +There are different reasons why someone might want to get into DRM: porting an
> +existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that
> +could face when working on the graphics user-space stack, etc. For this reason,
> +the learning material covers many aspects of the Linux graphics stack. From an
> +overview of the kernel and user-space stacks to very specific topics.
> +
> +The list is sorted in reverse chronological order, to keep the most up-to-date
> +material at the top. But all of them contain useful information, and it can be
> +valuable to go through older material to understand the rationale and context
> +in which the changes to the DRM subsystem were made.
> +
> +Conference talks
> +----------------
> +
> +* `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020)
> +* `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020)
> +* `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Daniel Vetter (2019)
> +* `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017)
> +* `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Daniel Vetter (2016)
> +* `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015)
> +* `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Daniel Vetter (2015)
> +* `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013)
> +
> +Slides and articles
> +-------------------
> +
> +* `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022)
> +* `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021)
> +* `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017)
> +* `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Daniel Vetter (2015)
> +* `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Daniel Vetter (2015)
> +* `The DRM/KMS subsystem from a newbie’s point of view <https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf>`_ - Boris Brezillon (2014)
> +* `A brief introduction to the Linux graphics stack <https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/>`_ - Iago Toral (2014)
> +* `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012)
> -- 
> 2.35.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH v3] drm/doc: Add sections about tiny drivers and external refs to intro page

[Javier Martinez Canillas]

Hello Daniel,

On 4/27/22 17:29, Daniel Vetter wrote:
> On Wed, Apr 20, 2022 at 09:24:11AM +0200, Javier Martinez Canillas wrote:
>> Learning about the DRM subsystem could be quite overwhelming for newcomers
>> but there are lots of useful talks, slides and articles available that can
>> help to understand the needed concepts and ease the learning curve.
>>
>> There are also simple DRM drivers that can be used as example about how a
>> DRM driver should look like.
>>
>> Add sections to the introduction page, that contains references to these.
>>
>> Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
>> Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
>> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
>> Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
> 
> Maybe needs more acks to land?
> 
> Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
>

Thanks! But this landed already a few days ago in drm-misc-next:

https://cgit.freedesktop.org/drm/drm-misc/commit/?id=e41a2999f746
 
> Would be good we can hand out links to pretty htmldocs instead of lore
> links to this patch, the latter is rather hard on the eyes :-)
>

Agreed :)
 -- 
Best regards,

Javier Martinez Canillas
Linux Engineering
Red Hat