[PATCH 2/2] drm/bridge: Document the expected behaviour of DSI host controllers

[Laurent Pinchart]

Hi Dave,

Thank you for the patch.


On Wed, Feb 16, 2022 at 04:59:44PM +0000, Dave Stevenson wrote:
> The exact behaviour of DSI host controllers is not specified,
> therefore define it.
> 
> Signed-off-by: Dave Stevenson <dave.stevenson at raspberrypi.com>
> ---
>  Documentation/gpu/drm-kms-helpers.rst |  7 +++++++
>  drivers/gpu/drm/drm_bridge.c          | 38 +++++++++++++++++++++++++++++++++++
>  2 files changed, 45 insertions(+)
> 
> diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
> index c3ce91eecbc1..362afdb867c6 100644
> --- a/Documentation/gpu/drm-kms-helpers.rst
> +++ b/Documentation/gpu/drm-kms-helpers.rst
> @@ -185,6 +185,13 @@ Bridge Helper Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_bridge.c
>     :export:
>  
> +MIPI-DSI bridge operation
> +-------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
> +   :doc: dsi bridge operations
> +
> +
>  Bridge Connector Helper Reference
>  ---------------------------------
>  
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index 7c24e8340efa..14c2ee9e0328 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -152,6 +152,44 @@
>   * situation when probing.
>   */
>  
> +/**
> + * DOC: dsi bridge operations
> + *
> + * DSI host interfaces are expected to be implemented as bridges rather than
> + * encoders, however there are a few aspects of their operation that need to
> + * be defined in order to provide a consistent interface.
> + *
> + * A DSI host should keep the PHY powered down until the pre_enable op is

I'd write "operation" in full everywhere to avoid mixing the two.

> + * called. All lanes should be in an idle state (not LP-11) up to this point.

Is the idle state LP-00 ? If so I'd state that explicitly.

"[...] in an idle state (LP-00, not LP-11) [...]"

> + * pre_enable should initialise the PHY, set the data lanes to LP-11, and the
> + * clock lane to either LP-11 or HS dependent on the mode_flag

s/dependent/depending/ ?

> + * MIPI_DSI_CLOCK_NON_CONTINUOUS.
> + *
> + * Ordinarily the downstream bridge DSI peripheral pre_enable will have been
> + * called before the DSI host. If the DSI peripheral requires LP-11 and/or
> + * the clock lane to be in HS mode prior to pre_enable, then it can set the
> + * DRM_BRIDGE_OP_UPSTREAM_FIRST flag to request the pre_enable (and
> + * post_disable) order to be altered to enable the DSI host first.
> + *
> + * Either the CRTC being enabled, or the DSI host enable op should switch the
> + * host to actively transmitting video on the data lanes.
> + *
> + * The reverse also applies. The DSI host disable op or stopping the CRTC should
> + * stop transmitting video, and the data lanes should return to the LP-11 state.
> + * The DSI host post_disable op should disable the PHY.
> + * If the DRM_BRIDGE_OP_UPSTREAM_FIRST flag is set, then the DSI peripheral's
> + * bridge post_disable will be called before the DSI host's post_disable.
> + *
> + * Whilst it is valid to call host_transfer prior to pre_enable or after
> + * post_disable, the exact state of the lanes is undefined at this point. The
> + * DSI host should initialise the interface, transmit the data, and then disable
> + * the interface again.
> + *
> + * Ultra Low Power State (ULPS) is not explicitly supported by DRM. If
> + * implemented, it therefore needs to be either handled entirely within the DSI

s/either // (or you need an "or ..." :-))

Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

> + * Host driver.
> + */
> +
>  static DEFINE_MUTEX(bridge_lock);
>  static LIST_HEAD(bridge_list);
>  

-- 
Regards,

Laurent Pinchart