On Tue, Aug 9, 2016 at 9:41 AM, Daniel Vetter daniel.vetter@ffwll.ch 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 daniel.vetter@intel.com

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 <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 <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 <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 Operations -~~~~~~~~~~~~~~~~~~~~

• **Note**
• Unless otherwise state, all operations are mandatory.

-DPMS -''''

-void (*dpms)(struct drm_connector *connector, int mode); -The DPMS operation sets the power state of a connector. The mode -argument is one of

-- DRM_MODE_DPMS_ON

-- DRM_MODE_DPMS_STANDBY

-- DRM_MODE_DPMS_SUSPEND

-- DRM_MODE_DPMS_OFF

-In all but DPMS_ON mode the encoder to which the connector is attached -should put the display in low-power mode by driving its signals -appropriately. If more than one connector is attached to the encoder -care should be taken not to change the power state of other displays as -a side effect. Low-power mode should be propagated to the encoders and -CRTCs when all related connectors are put in low-power mode.

-Modes -'''''

-int (*fill_modes)(struct drm_connector *connector, uint32_t -max_width, uint32_t max_height); -Fill the mode list with all supported modes for the connector. If the -``max_width`` and ``max_height`` arguments are non-zero, the -implementation must ignore all modes wider than ``max_width`` or higher -than ``max_height``.

-The connector must also fill in this operation its display_info -width_mm and height_mm fields with the connected display physical size -in millimeters. The fields should be set to 0 if the value isn't known -or is not applicable (for instance for projector devices).

-Connection Status -'''''''''''''''''

-The connection status is updated through polling or hotplug events when -supported (see ?). The status value is reported to userspace through -ioctls and must not be used inside the driver, as it only gets -initialized by a call to :c:func:`drm_mode_getconnector()` from -userspace.

-enum drm_connector_status (*detect)(struct drm_connector -*connector, bool force); -Check to see if anything is attached to the connector. The ``force`` -parameter is set to false whilst polling or to true when checking the -connector due to user request. ``force`` can be used by the driver to -avoid expensive, destructive operations during automated probing.

-Return connector_status_connected if something is connected to the -connector, connector_status_disconnected if nothing is connected and -connector_status_unknown if the connection state isn't known.

-Drivers should only return connector_status_connected if the -connection status has really been probed as connected. Connectors that -can't detect the connection status, or failed connection status probes, -should return connector_status_unknown.

Cleanup

diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c index 99ece6758061..cedc3bc4e10b 100644 --- a/drivers/gpu/drm/drm_connector.c +++ b/drivers/gpu/drm/drm_connector.c @@ -27,6 +27,37 @@ #include "drm_crtc_internal.h" #include "drm_internal.h"

+/**

• • DOC: overview
• • In DRM connectors are the general abstraction for display sinks, and include
• • als fixed panels or anything else that can display pixels in some form. As
• • opposed to all other KMS objects representing hardware (like CRTC, encoder or
• • plane abstractions) connectors can be hotplugged and unplugged at runtime.
• • Hence they are reference-counted using drm_connector_reference() and
• • drm_connector_unreference().
• • KMS driver must create, initialize, register and attach at a struct
• • &drm_connector for each such sink. The instance is created as other KMS
• • objects and initialized by setting the following fields.
• • The connector is then registered with a call to drm_connector_init() with a
• • pointer to the connector functions and a connector type, and exposed through
• • sysfs with a call to drm_connector_register().
• • 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 drm_mode_connector_attach_encoder(). The
• • driver must also set the struct &drm_connector encoder field to point to the
• • attached encoder.
• • For connectors which are not fixed (like built-in panels) the driver needs to
• • support hotplug notifications. The simplest way to do that is by using the
• • probe helpers, see drm_kms_helper_poll_init() for connectors which don't have
• • hardware support for hotplug interrupts. Connectors with hardware hotplug
• • support can instead use e.g. drm_helper_hpd_irq_event().
• */

struct drm_conn_prop_enum_list { int type; const char *name; diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h index ec2bea0b1b38..c9b275cd4085 100644 --- a/include/drm/drm_connector.h +++ b/include/drm/drm_connector.h @@ -42,9 +42,36 @@ enum drm_connector_force { DRM_FORCE_ON_DIGITAL, /* for DVI-I use digital connector */ };

+/**

• • enum drm_connector_status - status for a &drm_connector
• • This enum is used to track the connector status. There are no separate
• • #defines for the uapi!
• */

enum drm_connector_status {

•   /**
  

•    * @connector_status_connected: The connector is definitely connected to
  

•    * a sink device, and can be enabled.
  

•    */
    connector_status_connected = 1,
  

•   /**
  

•    * @connector_status_disconnected: The connector isn't connected to a
  

•    * sink device which can be autodetect. For digital outputs like DP or
  

•    * HDMI (which can be realiable probed) this means there's really
  

•    * nothing there. It is driver-dependent whether a connector with this
  

•    * status can be lit up or not.
  

•    */
    connector_status_disconnected = 2,
  

•   /**
  

•    * @connector_status_unknown: The connector's status could not be
  

•    * reliably detected. This happens when probing would either cause
  

•    * flicker (like load-detection when the connector is in use), or when a
  

•    * hardware resource isn't available (like when load-detection needs a
  

•    * free CRTC). It should be possible to light up the connector with one
  

•    * of the listed fallback modes. For default configuration userspace
  

•    * should only try to light up connectors with unknown status when
  

•    * there's not connector with @connector_status_connected.
  

•    */
    connector_status_unknown = 3,
  

};

@@ -416,11 +443,9 @@ struct drm_cmdline_mode {

• @modes: modes available on this connector (from fill_modes() + user)
• @status: one of the drm_connector_status enums (connected, not, or unknown)
• @probed_modes: list of modes derived directly from the display

• • @display_info: information about attached display (e.g. from EDID)
  • @funcs: connector control functions
  • @edid_blob_ptr: DRM property containing EDID if present
  • @properties: property tracking for this connector
• • @polled: a DRM_CONNECTOR_POLL_<foo> value for core driven polling
  • @dpms: current dpms state
  • @helper_private: mid-layer private data
  • @cmdline_mode: mode line parsed from the kernel cmdline for this connector

@@ -485,6 +510,13 @@ struct drm_connector { /* these are modes added by probing with DDC or the BIOS */ struct list_head probed_modes;

•   /**
  

•    * @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.
  

•    */
    struct drm_display_info display_info;
    const struct drm_connector_funcs *funcs;
  
  

@@ -519,6 +551,25 @@ struct drm_connector { /* DACs should rarely do this without a lot of testing */ #define DRM_CONNECTOR_POLL_DISCONNECT (1 << 2)

•   /**
  

•    * @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.
  

•    */
    uint8_t polled; /* DRM_CONNECTOR_POLL_* */
  

The comment after polled is redundant now

    /* requested DPMS state */

-- 2.8.1

---

Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx