| Message ID | 1463756065-11082-4-git-send-email-ander.conselvan.de.oliveira@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
> -----Original Message----- > From: Intel-gfx [mailto:intel-gfx-bounces@lists.freedesktop.org] On Behalf > Of Ander Conselvan de Oliveira > Sent: Friday, May 20, 2016 8:24 PM > To: intel-gfx@lists.freedesktop.org > Cc: Conselvan De Oliveira, Ander <ander.conselvan.de.oliveira@intel.com> > Subject: [Intel-gfx] [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@ffwll.ch> > Signed-off-by: Ander Conselvan de Oliveira > <ander.conselvan.de.oliveira@intel.com> > --- > 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@intel.com> 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@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/intel-gfx
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 + */ 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 + * @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
The documentation for most of the non-static members and structs were missing. Fix that. Cc: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira@intel.com> --- 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(-)