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

[Daniel Vetter]

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?

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