| Message ID | 1471034937-651-2-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, Aug 12, 2016 at 4:48 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote: > - Move the common vtable stuff to the top > - Move "Tile Group" to a more appropriate heading level > - Throw away the old intro for the crtc helpers (it's entirely stale, > e.g. helpers have become modular years ago), and replace it with a > general intro about the motivation behind helpers. > - Reorder helpers to group them together a bit better, and explain > that grouping in the intro. > - Make sure the introductory DOC section is always first. > > v2: > - Remove bogus files accidentally added (Sean). > - Spelling fixes (Sean). > > Cc: Sean Paul <seanpaul@chromium.org> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Reviewed-by: Sean Paul <seanpaul@chromium.org> > --- > Documentation/gpu/drm-kms-helpers.rst | 208 +++++++++++++++++----------------- > Documentation/gpu/drm-uapi.rst | 3 + > 2 files changed, 107 insertions(+), 104 deletions(-) > > diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst > index 0b302fedf1af..34f755bc9133 100644 > --- a/Documentation/gpu/drm-kms-helpers.rst > +++ b/Documentation/gpu/drm-kms-helpers.rst > @@ -2,38 +2,45 @@ > Mode Setting Helper Functions > ============================= > > -The plane, CRTC, encoder and connector functions provided by the drivers > -implement the DRM API. They're called by the DRM core and ioctl handlers > -to handle device state changes and configuration request. As > -implementing those functions often requires logic not specific to > -drivers, mid-layer helper functions are available to avoid duplicating > -boilerplate code. > - > -The DRM core contains one mid-layer implementation. The mid-layer > -provides implementations of several plane, CRTC, encoder and connector > -functions (called from the top of the mid-layer) that pre-process > -requests and call lower-level functions provided by the driver (at the > -bottom of the mid-layer). For instance, the > -:c:func:`drm_crtc_helper_set_config()` function can be used to > -fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>` > -set_config field. When called, it will split the set_config operation > -in smaller, simpler operations and call the driver to handle them. > - > -To use the mid-layer, drivers call > -:c:func:`drm_crtc_helper_add()`, > -:c:func:`drm_encoder_helper_add()` and > -:c:func:`drm_connector_helper_add()` functions to install their > -mid-layer bottom operations handlers, and fill the :c:type:`struct > -drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct > -drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct > -drm_connector_funcs <drm_connector_funcs>` structures with > -pointers to the mid-layer top API functions. Installing the mid-layer > -bottom operation handlers is best done right after registering the > -corresponding KMS object. > - > -The mid-layer is not split between CRTC, encoder and connector > -operations. To use it, a driver must provide bottom functions for all of > -the three KMS entities. > +The DRM subsystem aims for a strong separation between core code and helper > +libraries. Core code takes care of general setup and teardown and decoding > +userspace requests to kernel internal objects. Everything else is handled by a > +large set of helper libraries, which can be combined freely to pick and choose > +for each driver what fits, and avoid shared code where special behaviour is > +needed. > + > +This distinction between core code and helpers is especially strong in the > +modesetting code, where there's a shared userspace ABI for all drivers. This is > +in contrast to the render side, where pretty much everything (with very few > +exceptions) can be considered optional helper code. > + > +There are a few areas these helpers can grouped into: > + > +* Helpers to implement modesetting. The important ones here are the atomic > + helpers. Old drivers still often use the legacy CRTC helpers. They both share > + the same set of common helper vtables. For really simple drivers (anything > + that would have been a great fit in the deprecated fbdev subsystem) there's > + also the simple display pipe helpers. > + > +* There's a big pile of helpers for handling outputs. First the generic bridge > + helpers for handling encoder and transcoder IP blocks. Second the panel helpers > + for handling panel-related information and logic. Plus then a big set of > + helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally > + there's also generic helpers for handling output probing, and for dealing with > + EDIDs. > + > +* The last group of helpers concerns itself with the frontend side of a display > + pipeline: Planes, handling rectangles for visibility checking and scissoring, > + flip queues and assorted bits. > + > +Modeset Helper Reference for Common Vtables > +=========================================== > + > +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h > + :internal: > + > +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h > + :doc: overview > > Atomic Modeset Helper Functions Reference > ========================================= > @@ -62,33 +69,27 @@ Atomic State Reset and Initialization > .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c > :export: > > -Modeset Helper Reference for Common Vtables > -=========================================== > - > -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h > - :internal: > - > -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h > - :doc: overview > - > Legacy CRTC/Modeset Helper Functions Reference > ============================================== > > .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c > - :export: > + :doc: overview > > .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c > - :doc: overview > + :export: > > -Output Probing Helper Functions Reference > -========================================= > +Simple KMS Helper Reference > +=========================== > > -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c > - :doc: output probing helper overview > +.. kernel-doc:: include/drm/drm_simple_kms_helper.h > + :internal: > > -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c > +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c > :export: > > +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c > + :doc: overview > + > fbdev Helper Functions Reference > ================================ > > @@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference > .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c > :export: > > +Bridges > +======= > + > +Overview > +-------- > + > +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > + :doc: overview > + > +Default bridge callback sequence > +-------------------------------- > + > +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > + :doc: bridge callbacks > + > +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > + :export: > + > +Panel Helper Reference > +====================== > + > +.. kernel-doc:: include/drm/drm_panel.h > + :internal: > + > +.. kernel-doc:: drivers/gpu/drm/drm_panel.c > + :export: > + > +.. kernel-doc:: drivers/gpu/drm/drm_panel.c > + :doc: drm panel > + > Display Port Helper Functions Reference > ======================================= > > @@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference > .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c > :export: > > +Output Probing Helper Functions Reference > +========================================= > + > +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c > + :doc: output probing helper overview > + > +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c > + :export: > + > EDID Helper Functions Reference > =============================== > > @@ -176,18 +216,6 @@ Rectangle Utilities Reference > .. kernel-doc:: drivers/gpu/drm/drm_rect.c > :export: > > -Flip-work Helper Reference > -========================== > - > -.. kernel-doc:: include/drm/drm_flip_work.h > - :doc: flip utils > - > -.. kernel-doc:: include/drm/drm_flip_work.h > - :internal: > - > -.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c > - :export: > - > HDMI Infoframes Helper Reference > ================================ > > @@ -202,59 +230,31 @@ libraries and hence is also included here. > .. kernel-doc:: drivers/video/hdmi.c > :export: > > -Plane Helper Reference > -====================== > - > -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c > - :export: > - > -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c > - :doc: overview > - > -Tile group > ----------- > - > -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c > - :doc: Tile group > - > -Bridges > -======= > - > -Overview > --------- > - > -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > - :doc: overview > +Flip-work Helper Reference > +========================== > > -Default bridge callback sequence > --------------------------------- > +.. kernel-doc:: include/drm/drm_flip_work.h > + :doc: flip utils > > -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > - :doc: bridge callbacks > +.. kernel-doc:: include/drm/drm_flip_work.h > + :internal: > > -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c > +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c > :export: > > -Panel Helper Reference > +Plane Helper Reference > ====================== > > -.. kernel-doc:: include/drm/drm_panel.h > - :internal: > +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c > + :doc: overview > > -.. kernel-doc:: drivers/gpu/drm/drm_panel.c > +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c > :export: > > -.. kernel-doc:: drivers/gpu/drm/drm_panel.c > - :doc: drm panel > - > -Simple KMS Helper Reference > -=========================== > - > -.. kernel-doc:: include/drm/drm_simple_kms_helper.h > - :internal: > +Tile group > +========== > > -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c > - :export: > +# FIXME: This should probably be moved into a property documentation section > > -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c > - :doc: overview > +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c > + :doc: Tile group > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst > index 536bf3eaadd4..94876938aef3 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication > .. kernel-doc:: include/drm/drm_auth.h > :internal: > > +Open-Source Userspace Requirements > +================================== > + > Render nodes > ============ > > -- > 2.8.1 >
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..34f755bc9133 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -2,38 +2,45 @@ Mode Setting Helper Functions ============================= -The plane, CRTC, encoder and connector functions provided by the drivers -implement the DRM API. They're called by the DRM core and ioctl handlers -to handle device state changes and configuration request. As -implementing those functions often requires logic not specific to -drivers, mid-layer helper functions are available to avoid duplicating -boilerplate code. - -The DRM core contains one mid-layer implementation. The mid-layer -provides implementations of several plane, CRTC, encoder and connector -functions (called from the top of the mid-layer) that pre-process -requests and call lower-level functions provided by the driver (at the -bottom of the mid-layer). For instance, the -:c:func:`drm_crtc_helper_set_config()` function can be used to -fill the :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>` -set_config field. When called, it will split the set_config operation -in smaller, simpler operations and call the driver to handle them. - -To use the mid-layer, drivers call -:c:func:`drm_crtc_helper_add()`, -:c:func:`drm_encoder_helper_add()` and -:c:func:`drm_connector_helper_add()` functions to install their -mid-layer bottom operations handlers, and fill the :c:type:`struct -drm_crtc_funcs <drm_crtc_funcs>`, :c:type:`struct -drm_encoder_funcs <drm_encoder_funcs>` and :c:type:`struct -drm_connector_funcs <drm_connector_funcs>` structures with -pointers to the mid-layer top API functions. Installing the mid-layer -bottom operation handlers is best done right after registering the -corresponding KMS object. - -The mid-layer is not split between CRTC, encoder and connector -operations. To use it, a driver must provide bottom functions for all of -the three KMS entities. +The DRM subsystem aims for a strong separation between core code and helper +libraries. Core code takes care of general setup and teardown and decoding +userspace requests to kernel internal objects. Everything else is handled by a +large set of helper libraries, which can be combined freely to pick and choose +for each driver what fits, and avoid shared code where special behaviour is +needed. + +This distinction between core code and helpers is especially strong in the +modesetting code, where there's a shared userspace ABI for all drivers. This is +in contrast to the render side, where pretty much everything (with very few +exceptions) can be considered optional helper code. + +There are a few areas these helpers can grouped into: + +* Helpers to implement modesetting. The important ones here are the atomic + helpers. Old drivers still often use the legacy CRTC helpers. They both share + the same set of common helper vtables. For really simple drivers (anything + that would have been a great fit in the deprecated fbdev subsystem) there's + also the simple display pipe helpers. + +* There's a big pile of helpers for handling outputs. First the generic bridge + helpers for handling encoder and transcoder IP blocks. Second the panel helpers + for handling panel-related information and logic. Plus then a big set of + helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally + there's also generic helpers for handling output probing, and for dealing with + EDIDs. + +* The last group of helpers concerns itself with the frontend side of a display + pipeline: Planes, handling rectangles for visibility checking and scissoring, + flip queues and assorted bits. + +Modeset Helper Reference for Common Vtables +=========================================== + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :internal: + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :doc: overview Atomic Modeset Helper Functions Reference ========================================= @@ -62,33 +69,27 @@ Atomic State Reset and Initialization .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Modeset Helper Reference for Common Vtables -=========================================== - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview - Legacy CRTC/Modeset Helper Functions Reference ============================================== .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: + :doc: overview .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview + :export: -Output Probing Helper Functions Reference -========================================= +Simple KMS Helper Reference +=========================== -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c - :doc: output probing helper overview +.. kernel-doc:: include/drm/drm_simple_kms_helper.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + fbdev Helper Functions Reference ================================ @@ -110,6 +111,36 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: +Bridges +======= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: overview + +Default bridge callback sequence +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge callbacks + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :export: + +Panel Helper Reference +====================== + +.. kernel-doc:: include/drm/drm_panel.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + Display Port Helper Functions Reference ======================================= @@ -158,6 +189,15 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c :export: +Output Probing Helper Functions Reference +========================================= + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :doc: output probing helper overview + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :export: + EDID Helper Functions Reference =============================== @@ -176,18 +216,6 @@ Rectangle Utilities Reference .. kernel-doc:: drivers/gpu/drm/drm_rect.c :export: -Flip-work Helper Reference -========================== - -.. kernel-doc:: include/drm/drm_flip_work.h - :doc: flip utils - -.. kernel-doc:: include/drm/drm_flip_work.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c - :export: - HDMI Infoframes Helper Reference ================================ @@ -202,59 +230,31 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview - -Tile group ----------- - -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group - -Bridges -======= - -Overview --------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: overview +Flip-work Helper Reference +========================== -Default bridge callback sequence --------------------------------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks +.. kernel-doc:: include/drm/drm_flip_work.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export: -Panel Helper Reference +Plane Helper Reference ====================== -.. kernel-doc:: include/drm/drm_panel.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_panel.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel - -Simple KMS Helper Reference -=========================== - -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +Tile group +========== -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :export: +# FIXME: This should probably be moved into a property documentation section -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 536bf3eaadd4..94876938aef3 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -33,6 +33,9 @@ Primary Nodes, DRM Master and Authentication .. kernel-doc:: include/drm/drm_auth.h :internal: +Open-Source Userspace Requirements +================================== + Render nodes ============
- Move the common vtable stuff to the top - Move "Tile Group" to a more appropriate heading level - Throw away the old intro for the crtc helpers (it's entirely stale, e.g. helpers have become modular years ago), and replace it with a general intro about the motivation behind helpers. - Reorder helpers to group them together a bit better, and explain that grouping in the intro. - Make sure the introductory DOC section is always first. v2: - Remove bogus files accidentally added (Sean). - Spelling fixes (Sean). Cc: Sean Paul <seanpaul@chromium.org> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> --- Documentation/gpu/drm-kms-helpers.rst | 208 +++++++++++++++++----------------- Documentation/gpu/drm-uapi.rst | 3 + 2 files changed, 107 insertions(+), 104 deletions(-)