[PATCH 2/3] drm/doc: Drop chapter "KMS Initialization and Cleanup"

[Kazlauskas, Nicholas]

On 1/30/19 11:30 AM, Daniel Vetter wrote:
> It only talks about crtc, brings up intel as an exampel and I think is

nit: Should be "example".

> more misleading than useful really. Plus we have lots of discussion
> about how your standard kms driver should be initialized/cleaned up,
> so maybe better to document this when we have a better idea.
> 
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>   Documentation/gpu/drm-kms.rst | 96 -----------------------------------
>   1 file changed, 96 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 75c882e09fee..23a3c986ef6d 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -410,102 +410,6 @@ Encoder Functions Reference
>   .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
>      :export:
>   
> -KMS Initialization and Cleanup
> -==============================
> -
> -A KMS device is abstracted and exposed as a set of planes, CRTCs,
> -encoders and connectors. KMS drivers must thus create and initialize all
> -those objects at load time after initializing mode setting.
> -
> -CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
> ---------------------------------------------
> -
> -A CRTC is an abstraction representing a part of the chip that contains a
> -pointer to a scanout buffer. Therefore, the number of CRTCs available
> -determines how many independent scanout buffers can be active at any
> -given time. The CRTC structure contains several fields to support this:
> -a pointer to some video memory (abstracted as a frame buffer object), a
> -display mode, and an (x, y) offset into the video memory to support
> -panning or configurations where one piece of video memory spans multiple
> -CRTCs.

This is mostly a duplicate of what's already in the CRTC abstraction 
section but it may be worth carrying over the bit about  "the number of 
CRTCs available determining the number of independent scanout buffers 
that can be active at any given time".

> -
> -CRTC Initialization
> -~~~~~~~~~~~~~~~~~~~
> -
> -A KMS device must create and register at least one struct
> -:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
> -allocated and zeroed by the driver, possibly as part of a larger
> -structure, and registered with a call to :c:func:`drm_crtc_init()`
> -with a pointer to CRTC functions.
> -
> -
> -Cleanup
> --------
> -
> -The DRM core manages its objects' lifetime. When an object is not needed
> -anymore the core calls its destroy function, which must clean up and
> -free every resource allocated for the object. Every
> -:c:func:`drm_\*_init()` call must be matched with a corresponding
> -:c:func:`drm_\*_cleanup()` call to cleanup CRTCs
> -(:c:func:`drm_crtc_cleanup()`), planes
> -(:c:func:`drm_plane_cleanup()`), encoders
> -(:c:func:`drm_encoder_cleanup()`) and connectors
> -(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
> -have been added to sysfs must be removed by a call to
> -:c:func:`drm_connector_unregister()` before calling
> -:c:func:`drm_connector_cleanup()`.
> -
> -Connectors state change detection must be cleanup up with a call to
> -:c:func:`drm_kms_helper_poll_fini()`.
> -
> -Output discovery and initialization example
> --------------------------------------------
> -
> -.. code-block:: c
> -
> -    void intel_crt_init(struct drm_device *dev)
> -    {
> -        struct drm_connector *connector;
> -        struct intel_output *intel_output;
> -
> -        intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
> -        if (!intel_output)
> -            return;
> -
> -        connector = &intel_output->base;
> -        drm_connector_init(dev, &intel_output->base,
> -                   &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
> -
> -        drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
> -                 DRM_MODE_ENCODER_DAC);
> -
> -        drm_connector_attach_encoder(&intel_output->base,
> -                          &intel_output->enc);
> -
> -        /* Set up the DDC bus. */
> -        intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
> -        if (!intel_output->ddc_bus) {
> -            dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
> -                   "failed.\n");
> -            return;
> -        }
> -
> -        intel_output->type = INTEL_OUTPUT_ANALOG;
> -        connector->interlace_allowed = 0;
> -        connector->doublescan_allowed = 0;
> -
> -        drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
> -        drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
> -
> -        drm_connector_register(connector);
> -    }
> -
> -In the example above (taken from the i915 driver), a CRTC, connector and
> -encoder combination is created. A device-specific i2c bus is also
> -created for fetching EDID data and performing monitor detection. Once
> -the process is complete, the new connector is registered with sysfs to
> -make its properties available to applications.
> -
>   KMS Locking
>   ===========
>   
> 

Everything else looks fine to drop.

The bits about initialization/cleanup/subclassing/connectors can all be 
found in the Atomic Mode Setting section or one of the abstraction sections.

Nicholas Kazlauskas