[Intel-gfx] [PATCH] drm/i915: add kerneldoc for i915_audio_component

[Takashi Iwai]

On Wed, 09 Sep 2015 17:09:52 +0200,
Daniel Vetter wrote:
> 
> On Wed, Sep 09, 2015 at 01:45:47AM +0000, Yang, Libin wrote:
> > Hi Daniel,
> > 
> > As Takashi has already accepted the first 3 patches for 
> > sync_audio_rate() and the patches are not merged
> > into -nightly branch. If I make a kerneldoc patch
> > based on currently -nightly branch, there will
> > be conflict when you are merging Takashi's branch.
> > 
> > What do you think if I make the kerneldoc patch
> > after the sync_audio_rate() patches are merged
> > into the -nightly branch?
> 
> Hm, I do pull in sound/for-next into drm-intel-nightly ... Are the patches
> somewhere else? I can easily add another branch to nightly to make things
> easier. Takashi, which branches should I all pull in to get all the audio
> stuff into drm-intel-nightly?

No, it's not merged into for-next branch because the 4th patch is
missing, and I didn't get your proper ack yet.  The three patches are
left in topic/drm-sync-audio-rate branch.  If these are OK for you,
I'll add Acked-by to them before you pulling it (if any).

But, still I'm not sure whether we should really merge these partial
changes to 4.3.  Will the last patch be ready in time?  If yes, we can
go forward now.


thanks,

Takashi

> 
> Thanks, Daniel
> 
> > 
> > Regards,
> > Libin
> > 
> > 
> > > -----Original Message-----
> > > From: Daniel Vetter [mailto:daniel.vetter at ffwll.ch] On Behalf Of
> > > Daniel Vetter
> > > Sent: Friday, September 04, 2015 3:55 PM
> > > To: Jani Nikula
> > > Cc: Yang, Libin; Daniel Vetter; intel-gfx at lists.freedesktop.org;
> > > daniel.vetter at ffwll.ch; ville.syrjala at linux.intel.com
> > > Subject: Re: [PATCH] drm/i915: add kerneldoc for
> > > i915_audio_component
> > > 
> > > On Fri, Sep 04, 2015 at 09:40:17AM +0300, Jani Nikula wrote:
> > > > On Fri, 04 Sep 2015, "Yang, Libin" <libin.yang at intel.com> wrote:
> > > > >> -----Original Message-----
> > > > >> From: Daniel Vetter [mailto:daniel.vetter at ffwll.ch] On Behalf Of
> > > > >> Daniel Vetter
> > > > >> Sent: Wednesday, September 02, 2015 8:18 PM
> > > > >> To: Yang, Libin
> > > > >> Cc: intel-gfx at lists.freedesktop.org; daniel.vetter at ffwll.ch;
> > > > >> jani.nikula at linux.intel.com; ville.syrjala at linux.intel.com
> > > > >> Subject: Re: [PATCH] drm/i915: add kerneldoc for
> > > > >> i915_audio_component
> > > > >>
> > > > >> On Wed, Sep 02, 2015 at 02:12:24PM +0800,
> > > libin.yang at intel.com
> > > > >> wrote:
> > > > >> > From: Libin Yang <libin.yang at intel.com>
> > > > >> >
> > > > >> > Add the kerneldoc for i915_audio_component in
> > > i915_component.h
> > > > >> >
> > > > >> > Signed-off-by: Libin Yang <libin.yang at intel.com>
> > > > >> > ---
> > > > >> >  include/drm/i915_component.h | 39
> > > ++++++++++++++++++++++++--
> > > > >> -------------
> > > > >> >  1 file changed, 24 insertions(+), 15 deletions(-)
> > > > >> >
> > > > >> > diff --git a/include/drm/i915_component.h
> > > > >> b/include/drm/i915_component.h
> > > > >> > index 8ad6f1b..187acc8 100644
> > > > >> > --- a/include/drm/i915_component.h
> > > > >> > +++ b/include/drm/i915_component.h
> > > > >> > @@ -24,23 +24,32 @@
> > > > >> >  #ifndef _I915_COMPONENT_H_
> > > > >> >  #define _I915_COMPONENT_H_
> > > > >> >
> > > > >> > +/**
> > > > >> > + * struct i915_audio_component_ops - callbacks defined in gfx
> > > > >> driver
> > > > >> > + * @owner: the module owner
> > > > >> > + * @get_power: get the POWER_DOMAIN_AUDIO power well
> > > > >> > + * @put_power: put the POWER_DOMAIN_AUDIO power well
> > > > >> > + * @codec_wake_override: Enable/Disable generating the
> > > codec
> > > > >> wake signal
> > > > >> > + * @get_cdclk_freq: get the Core Display Clock in KHz
> > > > >> > + * @sync_audio_rate: set n/cts based on the sample rate
> > > > >> > + */
> > > > >> > +struct i915_audio_component_ops {
> > > > >> > +	struct module *owner;
> > > > >>
> > > > >> New kerneldoc in 4.3 allows you to split structure documentation
> > > up
> > > > >> into
> > > > >> per-member comments. Especially with vtables I think this makes
> > > a lot
> > > > >> of
> > > > >> sense, since then you have enough space to document where and
> > > how
> > > > >> exactly
> > > > >> a given hook is called (looks, place in the overall sequence).
> > > > >>
> > > > >> Also please include your stancas in the drm.tmpl docbook
> > > template,
> > > > >> otherwise it won't be included in the html docs. And finally please
> > > add
> > > > >
> > > > > OK, I will add it in drm.tmpl.
> > > > >
> > > > >> a
> > > > >> DOC: overview section which explains at a high level how i915 and
> > > > >> hda-intel corporate for hdmi/dp audio.
> > > > >
> > > > > Where the DOC should be located in?
> > > >
> > > > i915/intel_audio.c already has a "DOC: High Definition Audio over
> > > HDMI
> > > > and Display Port" comment. IMO you could just amend that, as
> > > there's
> > > > already some references to the audio driver.
> > > 
> > > Yeah I think that would be a perfect place.
> > > -Daniel
> > > --
> > > Daniel Vetter
> > > Software Engineer, Intel Corporation
> > > http://blog.ffwll.ch
> 
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch
>