Skip to contentSkip to conversation

drm/i915: Update kerneldoc for intel_dpll_mgr.c

PATCH In review Ander Conselvan de Oliveira 3 participants 3 messages May 17, 2016

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 drm/i915: Update kerneldoc for intel_dpll_mgr.c

---
 drivers/gpu/drm/i915/intel_dpll_mgr.c | 68 ++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 5 deletions(-)
drivers/gpu/drm/i915/intel_dpll_mgr.c +63 -5
index c283ba4..36566f8 100644
@@ -23,6 +23,13 @@
 
 #include "intel_drv.h"
 
+/** 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 +37,13 @@ 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)
@@ -41,6 +55,15 @@ intel_get_shared_dpll_id(struct drm_i915_private *dev_priv,
 	return (enum intel_dpll_id) (pll - dev_priv->shared_dplls);
 }
 
+/** intel_shared_dpll_config_get - get a reference to a DPLL for a crtc
+ * @config: a intel_shared_dpll_config struct
+ * @pll: pll to get a reference to
+ * @crtc: crtc that references the pll
+ *
+ * This gets a reference to @pll for @crtc. Internally is sets the pll's
+ * crtc_mask. @config should be the pll configuration in an atomic state.
+ * A crtc can reference a pll only once.
+ */
 void
 intel_shared_dpll_config_get(struct intel_shared_dpll_config *config,
 			     struct intel_shared_dpll *pll,
@@ -52,6 +75,14 @@ intel_shared_dpll_config_get(struct intel_shared_dpll_config *config,
 	config[id].crtc_mask |= 1 << crtc->pipe;
 }
 
+/** intel_shared_dpll_config_put - release a reference to a DPLL for a crtc
+ * @config: a intel_shared_dpll_config struct
+ * @pll: pll that is referenced by @crtc
+ * @crtc: crtc that references the pll
+ *
+ * This releases the reference to @pll for @crtc. Internally is sets the pll's
+ * crtc_mask. @config should be the pll configuration in an atomic state.
+ */
 void
 intel_shared_dpll_config_put(struct intel_shared_dpll_config *config,
 			     struct intel_shared_dpll *pll,
@@ -80,6 +111,9 @@ 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 mode_set hook
+ * @crtc: crtc which has a shared dpll
+ */
 void intel_prepare_shared_dpll(struct intel_crtc *crtc)
 {
 	struct drm_device *dev = crtc->base.dev;
@@ -102,12 +136,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)
 {
@@ -148,6 +180,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;
@@ -250,6 +288,11 @@ intel_reference_shared_dpll(struct intel_shared_dpll *pll,
 	intel_shared_dpll_config_get(shared_dpll, pll, crtc);
 }
 
+/** intel_shared_dpll_commit - make atomic state DPLL configuration effective
+ * @state: atomic state
+ *
+ * Makes the DPLL configuration in @state effective.
+ */
 void intel_shared_dpll_commit(struct drm_atomic_state *state)
 {
 	struct drm_i915_private *dev_priv = to_i915(state->dev);
@@ -1725,6 +1768,11 @@ 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;
@@ -1768,6 +1816,16 @@ 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.
+ *
+ * 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,
Signature · 6 lines
2.5.5

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#1 lore raw
Quoted 3 lines · Ander Conselvan de Oliveira
---
 drivers/gpu/drm/i915/intel_dpll_mgr.c | 68 ++++++++++++++++++++++++++++++++---

You also need to add a stanza to Documentation/DocBook/gpu.tmpl to actually include this.

Would also be good to document struct intel_dpll and the vfunc stuff and pull that into the same section in gpu.tmpl too.

drivers/gpu/drm/i915/intel_dpll_mgr.c

Quoted 7 lines
 1 file changed, 63 insertions(+), 5 deletions(-)
drivers/gpu/drm/i915/intel_dpll_mgr.c +0 -0
index c283ba4..36566f8 100644
@@ -23,6 +23,13 @@

A few sentences in a DOC: section about what this is supposed to do (also pulled into gpu.tmpl) would be nice. Especially a short overview over the expected calling sequence (in speudo-code, if you have asciidoc installed that should work on top of drm-intel-nightly with topic/kerneldoc).

drivers/gpu/drm/i915/intel_dpll_mgr.c line 26

Quoted 4 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +1 -0
 #include "intel_drv.h"
 
+/** intel_get_shared_dpll_by_id - get a DPLL given its id

I think kernel-doc wants a newline after the /**

Quoted 25 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +13 -0
+ * @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 +37,13 @@ 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)
@@ -41,6 +55,15 @@ intel_get_shared_dpll_id(struct drm_i915_private *dev_priv,
 	return (enum intel_dpll_id) (pll - dev_priv->shared_dplls);

drivers/gpu/drm/i915/intel_dpll_mgr.c intel_get_shared_dpll_id(struct drm_i915_private *dev_priv, · line 65

Quoted 10 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +8 -0
 }
 
+/** intel_shared_dpll_config_get - get a reference to a DPLL for a crtc
+ * @config: a intel_shared_dpll_config struct
+ * @pll: pll to get a reference to
+ * @crtc: crtc that references the pll
+ *
+ * This gets a reference to @pll for @crtc. Internally is sets the pll's
+ * crtc_mask. @config should be the pll configuration in an atomic state.
+ * A crtc can reference a pll only once.

Please add "The acquired reference should be dropped again with intel_shared_dpll_config_put()." With that kerneldoc will add a cross-reference.

Also I thought with atomic we don't need get/put anymore, and state handling is tracked entirely through the atomic check/commit stuff? Also, grep tells me that we could make this static, which avoids the need to add kernel-doc and also resolves some of the confusion we have here. Maybe even just inline _get()/_put() to avoid confusing name - these aren't refcounted anymore, but tracking in atomic states.

Quoted 59 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +21 -5
+ */
 void
 intel_shared_dpll_config_get(struct intel_shared_dpll_config *config,
 			     struct intel_shared_dpll *pll,
@@ -52,6 +75,14 @@ intel_shared_dpll_config_get(struct intel_shared_dpll_config *config,
 	config[id].crtc_mask |= 1 << crtc->pipe;
 }
 
+/** intel_shared_dpll_config_put - release a reference to a DPLL for a crtc
+ * @config: a intel_shared_dpll_config struct
+ * @pll: pll that is referenced by @crtc
+ * @crtc: crtc that references the pll
+ *
+ * This releases the reference to @pll for @crtc. Internally is sets the pll's
+ * crtc_mask. @config should be the pll configuration in an atomic state.
+ */
 void
 intel_shared_dpll_config_put(struct intel_shared_dpll_config *config,
 			     struct intel_shared_dpll *pll,
@@ -80,6 +111,9 @@ 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 mode_set hook
+ * @crtc: crtc which has a shared dpll
+ */
 void intel_prepare_shared_dpll(struct intel_crtc *crtc)
 {
 	struct drm_device *dev = crtc->base.dev;
@@ -102,12 +136,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)
 {
@@ -148,6 +180,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;

drivers/gpu/drm/i915/intel_dpll_mgr.c intel_reference_shared_dpll(struct intel_shared_dpll *pll, · line 296

Quoted 9 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +5 -0
@@ -250,6 +288,11 @@ intel_reference_shared_dpll(struct intel_shared_dpll *pll,
 	intel_shared_dpll_config_get(shared_dpll, pll, crtc);
 }
 
+/** intel_shared_dpll_commit - make atomic state DPLL configuration effective
+ * @state: atomic state
+ *
+ * Makes the DPLL configuration in @state effective.
+ */
 void intel_shared_dpll_commit(struct drm_atomic_state *state)

In atomic we use commit to push out (mostly) the hw state. Just pushing out the software state is done using drm_atomic_helper_swap_state(). And indeed we call this function here right next to the helper. I think better to first rename this to _swap_state() for consistency, and then maybe cross-reference to drm_atomic_helper_swap_state(), e.g.

"This is the dpll version of drm_atomic_helper_swap_state() since the helper does not handle driver-specific global state."

Quoted 18 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +5 -0
 {
 	struct drm_i915_private *dev_priv = to_i915(state->dev);
@@ -1725,6 +1768,11 @@ 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;
@@ -1768,6 +1816,16 @@ void intel_shared_dpll_init(struct drm_device *dev)
 		intel_ddi_pll_init(dev);
 }
 

drivers/gpu/drm/i915/intel_dpll_mgr.c void intel_shared_dpll_init(struct drm_device *dev) · line 1828

Quoted 10 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +10 -0
+/** 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.
+ *
+ * Returns:
+ * A shared DPLL to be used by @crtc and @encoder with the given @crtc_state.
+ */

Major confusion here between this get and the other get. Maybe rename this to _find_?

Quoted 10 lines
drivers/gpu/drm/i915/intel_dpll_mgr.c +0 -0
 struct intel_shared_dpll *
 intel_get_shared_dpll(struct intel_crtc *crtc,
 		      struct intel_crtc_state *crtc_state,
Signature · 6 lines
2.5.5

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Higher level comment: Imo typing kerneldoc only makes sense if you take the opportunity to review the exposed API with fresh eyes, and clean up stuff before typing the documentation. Aka the stuff I've mentioned above.

Otherwise it's just busywork and extracting new files shuffling stuff around for more noise and still not less confusion.

Cheers, Daniel

Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#2 lore raw

✗ Ro.CI.BAT: failure for drm/i915: Update kerneldoc for intel_dpll_mgr.c

In reply to Ander Conselvan de Oliveira
== Series Details ==

== Series Details ==

Series: drm/i915: Update kerneldoc for intel_dpll_mgr.c
URL : https://patchwork.freedesktop.org/series/7294/
State : failure

== Summary ==

Series 7294v1 drm/i915: Update kerneldoc for intel_dpll_mgr.c
http://patchwork.freedesktop.org/api/1.0/series/7294/revisions/1/mbox

Test drv_hangman:

        Subgroup error-state-basic:
                fail       -> PASS       (ro-ilk1-i5-650)
Test gem_exec_flush:
        Subgroup basic-batch-kernel-default-cmd:
                pass       -> FAIL       (fi-byt-n2820)
Test kms_pipe_crc_basic:
        Subgroup hang-read-crc-pipe-c:
                pass       -> DMESG-WARN (ro-ivb2-i7-3770)
fi-bdw-i7-5557u  total:219  pass:206  dwarn:0   dfail:0   fail:0   skip:13 
fi-bsw-n3050     total:218  pass:174  dwarn:0   dfail:0   fail:2   skip:42 
fi-byt-n2820     total:218  pass:174  dwarn:0   dfail:0   fail:3   skip:41 
fi-hsw-i7-4770r  total:219  pass:193  dwarn:0   dfail:0   fail:0   skip:26 
fi-kbl-y         total:219  pass:191  dwarn:1   dfail:0   fail:2   skip:25 
fi-skl-i7-6700k  total:219  pass:191  dwarn:0   dfail:0   fail:0   skip:28 
ro-bdw-i5-5250u  total:219  pass:181  dwarn:0   dfail:0   fail:0   skip:38 
ro-bdw-i7-5557U  total:219  pass:206  dwarn:0   dfail:0   fail:0   skip:13 
ro-bdw-i7-5600u  total:219  pass:187  dwarn:0   dfail:0   fail:0   skip:32 
ro-bsw-n3050     total:219  pass:175  dwarn:0   dfail:0   fail:2   skip:42 
ro-byt-n2820     total:218  pass:174  dwarn:0   dfail:0   fail:3   skip:41 
ro-hsw-i3-4010u  total:218  pass:193  dwarn:0   dfail:0   fail:0   skip:25 
ro-hsw-i7-4770r  total:219  pass:194  dwarn:0   dfail:0   fail:0   skip:25 
ro-ilk-i7-620lm  total:219  pass:151  dwarn:0   dfail:0   fail:1   skip:67 
ro-ilk1-i5-650   total:214  pass:152  dwarn:0   dfail:0   fail:1   skip:61 
ro-ivb-i7-3770   total:219  pass:183  dwarn:0   dfail:0   fail:0   skip:36 
ro-ivb2-i7-3770  total:219  pass:186  dwarn:1   dfail:0   fail:0   skip:32 
ro-skl-i7-6700hq total:214  pass:189  dwarn:0   dfail:0   fail:0   skip:25 
ro-snb-i7-2620M  total:219  pass:177  dwarn:0   dfail:0   fail:1   skip:41 

Results at /archive/results/CI_IGT_test/RO_Patchwork_920/

68c6a6d drm-intel-nightly: 2016y-05m-17d-13h-59m-27s UTC integration manifest 7f06795 drm/i915: Update kerneldoc for intel_dpll_mgr.c

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx