Re: [PATCH 4/4] drm/i915: Update kerneldoc for intel_dpll_mgr.c

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



> -----Original Message-----
> From: Intel-gfx [mailto:intel-gfx-bounces@xxxxxxxxxxxxxxxxxxxxx] On Behalf
> Of Ander Conselvan de Oliveira
> Sent: Friday, May 20, 2016 8:24 PM
> To: intel-gfx@xxxxxxxxxxxxxxxxxxxxx
> Cc: Conselvan De Oliveira, Ander <ander.conselvan.de.oliveira@xxxxxxxxx>
> Subject:  [PATCH 4/4] drm/i915: Update kerneldoc for
> intel_dpll_mgr.c
> 
> The documentation for most of the non-static members and structs were
> missing. Fix that.
> 
> Cc: Daniel Vetter <daniel@xxxxxxxx>
> Signed-off-by: Ander Conselvan de Oliveira
> <ander.conselvan.de.oliveira@xxxxxxxxx>
> ---
>  Documentation/DocBook/gpu.tmpl        |  7 +++
>  drivers/gpu/drm/i915/intel_dpll_mgr.c | 88
> +++++++++++++++++++++++++++++++++--
>  drivers/gpu/drm/i915/intel_dpll_mgr.h | 83
> +++++++++++++++++++++++++++++----
>  3 files changed, 163 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/DocBook/gpu.tmpl
> b/Documentation/DocBook/gpu.tmpl
> index 7586bf75..b96875d 100644
> --- a/Documentation/DocBook/gpu.tmpl
> +++ b/Documentation/DocBook/gpu.tmpl
> @@ -3355,6 +3355,13 @@ int num_ioctls;</synopsis>
>  !Idrivers/gpu/drm/i915/intel_bios.c
>  !Idrivers/gpu/drm/i915/intel_vbt_defs.h
>        </sect2>
> +
> +      <sect2>
> +	<title>Display PLLs</title>
> +!Pdrivers/gpu/drm/i915/intel_dpll_mgr.c Display PLLs
> +!Idrivers/gpu/drm/i915/intel_dpll_mgr.c
> +!Idrivers/gpu/drm/i915/intel_dpll_mgr.h
> +      </sect2>
>      </sect1>
> 
>      <sect1>
> diff --git a/drivers/gpu/drm/i915/intel_dpll_mgr.c
> b/drivers/gpu/drm/i915/intel_dpll_mgr.c
> index 26c9955..bcfe7a9 100644
> --- a/drivers/gpu/drm/i915/intel_dpll_mgr.c
> +++ b/drivers/gpu/drm/i915/intel_dpll_mgr.c
> @@ -23,6 +23,33 @@
> 
>  #include "intel_drv.h"
> 
> +/**
> + * DOC: Display PLLs
> + *
> + * Display PLLs used for driving outputs vary by platform. While some have
> + * per-pipe or per-encoder dedicated PLLs, others allow the use of any PLL
> + * from a pool. In the latter scenario, it is possible that multiple pipes
> + * share a PLL if their configurations match.
> + *
> + * This file provides an abstraction over display PLLs. The function
> + * intel_shared_dpll_init() initializes the PLLs for the given platform.  The
> + * users of a PLL are tracked and that tracking is integrated with the atomic
> + * modest interface. During an atomic operation, a PLL can be requested for
> a
> + * given crtc and encoder configuration by calling intel_get_shared_dpll()
> and
> + * a previously used PLL can be released with intel_release_shared_dpll().
> + * Changes to the users are first staged in the atomic state, and then made
> + * effective by calling intel_shared_dpll_swap_state() during the atomic
> + * commit phase.
> + */
> +
> +/**
> + * intel_get_shared_dpll_by_id - get a DPLL given its id
> + * @dev_priv: i915 device instance
> + * @id: pll id
> + *
> + * Returns:
> + * A pointer the DPLL with @id

A pointer 'to' the DPLL...

> + */
>  struct intel_shared_dpll *
>  intel_get_shared_dpll_by_id(struct drm_i915_private *dev_priv,
>  			    enum intel_dpll_id id)
> @@ -30,6 +57,14 @@ intel_get_shared_dpll_by_id(struct drm_i915_private
> *dev_priv,
>  	return &dev_priv->shared_dplls[id];
>  }
> 
> +/**
> + * intel_get_shared_dpll_id - get the id of a DPLL
> + * @dev_priv: i915 device instance
> + * @pll: the DPLL
> + *
> + * Returns:
> + * The id of @pll
> + */
>  enum intel_dpll_id
>  intel_get_shared_dpll_id(struct drm_i915_private *dev_priv,
>  			 struct intel_shared_dpll *pll)
> @@ -58,6 +93,13 @@ void assert_shared_dpll(struct drm_i915_private
> *dev_priv,
>  			pll->name, onoff(state), onoff(cur_state));
>  }
> 
> +/**
> + * intel_prepare_shared_dpll - call a dpll's prepare hook
> + * @crtc: crtc which has a shared dpll
> + *
> + * This calls the PLL's prepare hook if it has one and if the PLL is not
> + * already enabled. The prepare hook is platform specific.
> + */
>  void intel_prepare_shared_dpll(struct intel_crtc *crtc)
>  {
>  	struct drm_device *dev = crtc->base.dev;
> @@ -80,12 +122,10 @@ void intel_prepare_shared_dpll(struct intel_crtc
> *crtc)
>  }
> 
>  /**
> - * intel_enable_shared_dpll - enable PCH PLL
> - * @dev_priv: i915 private structure
> - * @pipe: pipe PLL to enable
> + * intel_enable_shared_dpll - enable a crtc's shared DPLL
> + * @crtc: crtc which has a shared DPLL
>   *
> - * The PCH PLL needs to be enabled before the PCH transcoder, since it
> - * drives the transcoder clock.
> + * Enable the shared DPLL used by @crtc.
>   */
>  void intel_enable_shared_dpll(struct intel_crtc *crtc)
>  {
> @@ -126,6 +166,12 @@ out:
>  	mutex_unlock(&dev_priv->dpll_lock);
>  }
> 
> +/**
> + * intel_disable_shared_dpll - disable a crtc's shared DPLL
> + * @crtc: crtc which has a shared DPLL
> + *
> + * Disable the shared DPLL used by @crtc.
> + */
>  void intel_disable_shared_dpll(struct intel_crtc *crtc)
>  {
>  	struct drm_device *dev = crtc->base.dev;
> @@ -228,6 +274,16 @@ intel_reference_shared_dpll(struct
> intel_shared_dpll *pll,
>  	shared_dpll[pll->id].crtc_mask |= 1 << crtc->pipe;
>  }
> 
> +/**
> + * intel_shared_dpll_swap_state - make atomic DPLL configuration
> effective
> + * @state: atomic state
> + *
> + * This is the dpll version of drm_atomic_helper_swap_state() since the
> + * helper does not handle driver-specific global state.
> + *
> + * Note thar this doesn't actually swap states, the dpll configutation in

s/thar/that

Reviewed-by: Durgadoss R <durgadoss.r@xxxxxxxxx>

Thanks,
Durga

> + * @state is left unchanged.
> + */
>  void intel_shared_dpll_swap_state(struct drm_atomic_state *state)
>  {
>  	struct drm_i915_private *dev_priv = to_i915(state->dev);
> @@ -1706,6 +1762,12 @@ static const struct intel_dpll_mgr bxt_pll_mgr = {
>  	.get_dpll = bxt_get_dpll,
>  };
> 
> +/**
> + * intel_shared_dpll_init - Initialize shared DPLLs
> + * @dev: drm device
> + *
> + * Initialize shared DPLLs for @dev.
> + */
>  void intel_shared_dpll_init(struct drm_device *dev)
>  {
>  	struct drm_i915_private *dev_priv = dev->dev_private;
> @@ -1749,6 +1811,20 @@ void intel_shared_dpll_init(struct drm_device
> *dev)
>  		intel_ddi_pll_init(dev);
>  }
> 
> +/**
> + * intel_get_shared_dpll - get a shared DPLL for crtc and encoder
> combination
> + * @crtc: crtc
> + * @crtc_state: atomic state for @crtc
> + * @encoder: encoder
> + *
> + * Find an appropriate DPLL for the given crtc and encoder combination. A
> + * reference from the @crtc to the returned pll is registered in the atomic
> + * state. That configuration is made effective by FIXME name. The
> reference
> + * should be released by calling intel_release_shared_dpll().
> + *
> + * Returns:
> + * A shared DPLL to be used by @crtc and @encoder with the given
> @crtc_state.
> + */
>  struct intel_shared_dpll *
>  intel_get_shared_dpll(struct intel_crtc *crtc,
>  		      struct intel_crtc_state *crtc_state,
> @@ -1768,6 +1844,8 @@ intel_get_shared_dpll(struct intel_crtc *crtc,
>   * @crtc: crtc
>   * @crtc_state: atomic stat for @crtc
>   *
> + * This function releases the reference from @crtc to its shared dpll from
> the
> + * atomic state. The new configuration is made effective by FIXME name.
>   */
>  void intel_release_shared_dpll(struct intel_crtc *crtc,
>  			       struct intel_crtc_state *crtc_state)
> diff --git a/drivers/gpu/drm/i915/intel_dpll_mgr.h
> b/drivers/gpu/drm/i915/intel_dpll_mgr.h
> index 087e6b1..6032bda 100644
> --- a/drivers/gpu/drm/i915/intel_dpll_mgr.h
> +++ b/drivers/gpu/drm/i915/intel_dpll_mgr.h
> @@ -40,6 +40,9 @@ struct intel_encoder;
>  struct intel_shared_dpll;
>  struct intel_dpll_mgr;
> 
> +/**
> + * enum intel_dpll_id - possible DPLL ids
> + */
>  enum intel_dpll_id {
>  	DPLL_ID_PRIVATE = -1, /* non-shared dpll in use */
>  	/* real shared dpll ids must be >= 0 */
> @@ -61,11 +64,6 @@ enum intel_dpll_id {
>  };
>  #define I915_NUM_PLLS 6
> 
> -/** Inform the state checker that the DPLL is kept enabled even if not
> - * in use by any crtc.
> - */
> -#define INTEL_DPLL_ALWAYS_ON	(1 << 0)
> -
>  struct intel_dpll_hw_state {
>  	/* i9xx, pch plls */
>  	uint32_t dpll;
> @@ -98,34 +96,99 @@ struct intel_shared_dpll_config {
>  	struct intel_dpll_hw_state hw_state;
>  };
> 
> +/**
> + * intel_shared_dpll_funcs - platform specific hooks for managing DPLLs
> + */
>  struct intel_shared_dpll_funcs {
> -	/* The mode_set hook is optional and should be used together with
> the
> -	 * intel_prepare_shared_dpll function. */
> +	/**
> +	 * @prepare:
> +	 *
> +	 * Optional hook to perform operations prior to enabling the PLL.
> +	 * Called from intel_prepare_shared_dpll() function.
> +	 */
>  	void (*prepare)(struct drm_i915_private *dev_priv,
>  			 struct intel_shared_dpll *pll);
> +
> +	/**
> +	 * @enable:
> +	 *
> +	 * Hook for enabling the pll, called from intel_enable_shared_dpll()
> +	 * if the pll is not already enabled.
> +	 */
>  	void (*enable)(struct drm_i915_private *dev_priv,
>  		       struct intel_shared_dpll *pll);
> +
> +	/**
> +	 * @disable:
> +	 *
> +	 * Hook for disabling the pll, called from intel_disable_shared_dpll()
> +	 * only when it is safe to disable the pll, i.e., there are no more
> +	 * tracked users for it.
> +	 */
>  	void (*disable)(struct drm_i915_private *dev_priv,
>  			struct intel_shared_dpll *pll);
> +
> +	/**
> +	 * @get_hw_state
> +	 *
> +	 * Hook for reading the values currently programmed to the DPLL
> +	 * registers. This is used for initial hw state readout and state
> +	 * verification after a mode set.
> +	 */
>  	bool (*get_hw_state)(struct drm_i915_private *dev_priv,
>  			     struct intel_shared_dpll *pll,
>  			     struct intel_dpll_hw_state *hw_state);
>  };
> 
> +/**
> + * struct intel_shared_dpll - display PLL with tracked state and users
> + */
>  struct intel_shared_dpll {
>  	struct intel_shared_dpll_config config;
> 
> -	unsigned active_mask; /* mask of active CRTCs (i.e. DPMS on) */
> -	bool on; /* is the PLL actually active? Disabled during modeset */
> +	/**
> +	 * @active_mask: mask of active CRTCs (i.e. DPMS on)
> +	 */
> +	unsigned active_mask;
> +
> +	/**
> +	 * @on: is the PLL actually active? Disabled during modeset
> +	 */
> +	bool on;
> +
> +	/**
> +	 * @name: DPLL name; used for logging
> +	 */
>  	const char *name;
> -	/* should match the index in the dev_priv->shared_dplls array */
> +
> +	/**
> +	 * @id: unique indentifier for this DPLL; should match the index in the
> +	 * dev_priv->shared_dplls array
> +	 */
>  	enum intel_dpll_id id;
> 
> +	/**
> +	 * @funcs: platform specific hooks
> +	 */
>  	struct intel_shared_dpll_funcs funcs;
> 
> +	/**
> +	 * @flags:
> +	 *
> +	 * accepted flags: INTEL_DPLL_ALWAYS_ON
> +	 */
>  	uint32_t flags;
>  };
> 
> +/**
> + * INTEL_DPLL_ALWAYS_ON
> + *
> + * Inform the state checker that the DPLL is kept enabled even if not
> + * in use by any crtc.
> + */
> +#define INTEL_DPLL_ALWAYS_ON	(1 << 0)
> +
> +
>  #define SKL_DPLL0 0
>  #define SKL_DPLL1 1
>  #define SKL_DPLL2 2
> --
> 2.5.5
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/intel-gfx




[Index of Archives]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]
  Powered by Linux