drm/i915: Update kerneldoc for intel_dpll_mgr.c
Subsystems (2)
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
@@ -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
Quoted 3 lines · Ander Conselvan de Oliveira
Signed-off-by Ander Conselvan de Oliveira <[email protected]>--- 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@@ -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
-0struct 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
Patchwork
CI✗ 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