On Fri, Aug 12, 2016 at 4:48 PM, Daniel Vetter <daniel.vetter@xxxxxxxx> 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@xxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> Reviewed-by: Sean Paul <seanpaul@xxxxxxxxxxxx> > --- > 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 > _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
