Re: [Intel-gfx] [PATCH 17/20] drm: Update connector documentation

[Sean Paul]

On Tue, Aug 9, 2016 at 9:41 AM, Daniel Vetter  wrote:
> - Shuffle docs from drm-kms.rst into the structure docs where it makes
>   sense.
> - Put the remaining bits into a new overview section.
>
> One thing I've changed is around probing: Old docs says that you
> _must_ use the probe helpers, which isn't correct. Helpers are always
> optional.
>
> Signed-off-by: Daniel Vetter 
> ---
>  Documentation/gpu/drm-kms.rst   | 170 
> ++--
>  drivers/gpu/drm/drm_connector.c |  31 
>  include/drm/drm_connector.h |  55 -
>  3 files changed, 92 insertions(+), 164 deletions(-)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 6e7ab57924f0..fa948b4e029b 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -110,8 +110,14 @@ Display Modes Function Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_modes.c
> :export:
>
> -Connector Display Sink Abstraction
> -==
> +Connector Abstraction
> +=
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_connector.c
> +   :doc: overview
> +
> +Connector Functions Reference
> +-
>
>  .. kernel-doc:: include/drm/drm_connector.h
> :internal:
> @@ -232,166 +238,6 @@ encoders unattached at initialization time. 
> Applications (or the fbdev
>  compatibility layer when implemented) are responsible for attaching the
>  encoders they want to use to a CRTC.
>
> -Connectors (:c:type:`struct drm_connector `)
> 
> -
> -A connector is the final destination for pixel data on a device, and
> -usually connects directly to an external display device like a monitor
> -or laptop panel. A connector can only be attached to one encoder at a
> -time. The connector is also the structure where information about the
> -attached display is kept, so it contains fields for display data, EDID
> -data, DPMS & connection status, and information about modes supported on
> -the attached displays.
> -
> -Connector Initialization
> -
> -
> -Finally a KMS driver must create, initialize, register and attach at
> -least one :c:type:`struct drm_connector `
> -instance. The instance is created as other KMS objects and initialized
> -by setting the following fields.
> -
> -interlace_allowed
> -Whether the connector can handle interlaced modes.
> -
> -doublescan_allowed
> -Whether the connector can handle doublescan.
> -
> -display_info
> -Display information is filled from EDID information when a display
> -is detected. For non hot-pluggable displays such as flat panels in
> -embedded systems, the driver should initialize the
> -display_info.width_mm and display_info.height_mm fields with the
> -physical size of the display.
> -
> -polled
> -Connector polling mode, a combination of
> -
> -DRM_CONNECTOR_POLL_HPD
> -The connector generates hotplug events and doesn't need to be
> -periodically polled. The CONNECT and DISCONNECT flags must not
> -be set together with the HPD flag.
> -
> -DRM_CONNECTOR_POLL_CONNECT
> -Periodically poll the connector for connection.
> -
> -DRM_CONNECTOR_POLL_DISCONNECT
> -Periodically poll the connector for disconnection.
> -
> -Set to 0 for connectors that don't support connection status
> -discovery.
> -
> -The connector is then registered with a call to
> -:c:func:`drm_connector_init()` with a pointer to the connector
> -functions and a connector type, and exposed through sysfs with a call to
> -:c:func:`drm_connector_register()`.
> -
> -Supported connector types are
> -
> --  DRM_MODE_CONNECTOR_VGA
> --  DRM_MODE_CONNECTOR_DVII
> --  DRM_MODE_CONNECTOR_DVID
> --  DRM_MODE_CONNECTOR_DVIA
> --  DRM_MODE_CONNECTOR_Composite
> --  DRM_MODE_CONNECTOR_SVIDEO
> --  DRM_MODE_CONNECTOR_LVDS
> --  DRM_MODE_CONNECTOR_Component
> --  DRM_MODE_CONNECTOR_9PinDIN
> --  DRM_MODE_CONNECTOR_DisplayPort
> --  DRM_MODE_CONNECTOR_HDMIA
> --  DRM_MODE_CONNECTOR_HDMIB
> --  DRM_MODE_CONNECTOR_TV
> --  DRM_MODE_CONNECTOR_eDP
> --  DRM_MODE_CONNECTOR_VIRTUAL
> -
> -Connectors must be attached to an encoder to be used. For devices that
> -map connectors to encoders 1:1, the connector should be attached at
> -initialization time with a call to
> -:c:func:`drm_mode_connector_attach_encoder()`. The driver must
> -also set the :c:type:`struct drm_connector `
> -encoder field to point to the attached encoder.
> -
> -Finally, drivers must initialize the connectors state change detection
> -with a call to :c:func:`drm_kms_helper_poll_init()`. If at least
> -one connector is pollable but can't generate hotplug interrupts
> -(indicated by the DRM_CONNECTOR_POLL_CONNECT and
> -DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
> -automatically be queued to periodically poll for changes. 

[Intel-gfx] [PATCH 17/20] drm: Update connector documentation

[Daniel Vetter]

- Shuffle docs from drm-kms.rst into the structure docs where it makes
  sense.
- Put the remaining bits into a new overview section.

One thing I've changed is around probing: Old docs says that you
_must_ use the probe helpers, which isn't correct. Helpers are always
optional.

Signed-off-by: Daniel Vetter 
---
 Documentation/gpu/drm-kms.rst   | 170 ++--
 drivers/gpu/drm/drm_connector.c |  31 
 include/drm/drm_connector.h |  55 -
 3 files changed, 92 insertions(+), 164 deletions(-)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 6e7ab57924f0..fa948b4e029b 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -110,8 +110,14 @@ Display Modes Function Reference
 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
:export:
 
-Connector Display Sink Abstraction
-==
+Connector Abstraction
+=
+
+.. kernel-doc:: drivers/gpu/drm/drm_connector.c
+   :doc: overview
+
+Connector Functions Reference
+-
 
 .. kernel-doc:: include/drm/drm_connector.h
:internal:
@@ -232,166 +238,6 @@ encoders unattached at initialization time. Applications 
(or the fbdev
 compatibility layer when implemented) are responsible for attaching the
 encoders they want to use to a CRTC.
 
-Connectors (:c:type:`struct drm_connector `)

-
-A connector is the final destination for pixel data on a device, and
-usually connects directly to an external display device like a monitor
-or laptop panel. A connector can only be attached to one encoder at a
-time. The connector is also the structure where information about the
-attached display is kept, so it contains fields for display data, EDID
-data, DPMS & connection status, and information about modes supported on
-the attached displays.
-
-Connector Initialization
-
-
-Finally a KMS driver must create, initialize, register and attach at
-least one :c:type:`struct drm_connector `
-instance. The instance is created as other KMS objects and initialized
-by setting the following fields.
-
-interlace_allowed
-Whether the connector can handle interlaced modes.
-
-doublescan_allowed
-Whether the connector can handle doublescan.
-
-display_info
-Display information is filled from EDID information when a display
-is detected. For non hot-pluggable displays such as flat panels in
-embedded systems, the driver should initialize the
-display_info.width_mm and display_info.height_mm fields with the
-physical size of the display.
-
-polled
-Connector polling mode, a combination of
-
-DRM_CONNECTOR_POLL_HPD
-The connector generates hotplug events and doesn't need to be
-periodically polled. The CONNECT and DISCONNECT flags must not
-be set together with the HPD flag.
-
-DRM_CONNECTOR_POLL_CONNECT
-Periodically poll the connector for connection.
-
-DRM_CONNECTOR_POLL_DISCONNECT
-Periodically poll the connector for disconnection.
-
-Set to 0 for connectors that don't support connection status
-discovery.
-
-The connector is then registered with a call to
-:c:func:`drm_connector_init()` with a pointer to the connector
-functions and a connector type, and exposed through sysfs with a call to
-:c:func:`drm_connector_register()`.
-
-Supported connector types are
-
--  DRM_MODE_CONNECTOR_VGA
--  DRM_MODE_CONNECTOR_DVII
--  DRM_MODE_CONNECTOR_DVID
--  DRM_MODE_CONNECTOR_DVIA
--  DRM_MODE_CONNECTOR_Composite
--  DRM_MODE_CONNECTOR_SVIDEO
--  DRM_MODE_CONNECTOR_LVDS
--  DRM_MODE_CONNECTOR_Component
--  DRM_MODE_CONNECTOR_9PinDIN
--  DRM_MODE_CONNECTOR_DisplayPort
--  DRM_MODE_CONNECTOR_HDMIA
--  DRM_MODE_CONNECTOR_HDMIB
--  DRM_MODE_CONNECTOR_TV
--  DRM_MODE_CONNECTOR_eDP
--  DRM_MODE_CONNECTOR_VIRTUAL
-
-Connectors must be attached to an encoder to be used. For devices that
-map connectors to encoders 1:1, the connector should be attached at
-initialization time with a call to
-:c:func:`drm_mode_connector_attach_encoder()`. The driver must
-also set the :c:type:`struct drm_connector `
-encoder field to point to the attached encoder.
-
-Finally, drivers must initialize the connectors state change detection
-with a call to :c:func:`drm_kms_helper_poll_init()`. If at least
-one connector is pollable but can't generate hotplug interrupts
-(indicated by the DRM_CONNECTOR_POLL_CONNECT and
-DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
-automatically be queued to periodically poll for changes. Connectors
-that can generate hotplug interrupts must be marked with the
-DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
-call :c:func:`drm_helper_hpd_irq_event()`. The function will
-queue a delayed work to check the state of all connectors, but no
-periodic polling will be done.
-
-Connector