[alsa-devel] [PATCH v2] drm/i915: Improve kernel-doc for i915_audio_component struct

[Daniel Vetter]

On Tue, Oct 13, 2015 at 11:40:23AM +0200, Takashi Iwai wrote:
> On Mon, 12 Oct 2015 10:17:51 +0200,
> David Henningsson wrote:
> > 
> > 
> > 
> > On 2015-10-12 10:07, David Henningsson wrote:
> > > To make kernel-doc happy, the i915_audio_component_audio_ops struct
> > > cannot be nested.
> > >
> > > Signed-off-by: David Henningsson <david.henningsson at canonical.com>
> > > ---
> > 
> > Changes since v1:
> > 
> >   * Added a notice about when pin_eld_notify is called
> > 
> >   * Uses new inline struct member style
> > 
> > Verified with "make htmldocs", looks fine to me.
> > 
> > Also, applies to Takashi's tree (master branch), maybe we should take it 
> > through Takashi's tree to avoid conflicts, especially as there might be 
> > more stuff coming that way (dp mst support from Mengdong, and perhaps 
> > info retrieval from me).
> 
> I'm fine to take it, just let me know (and give acks).

There's other doc patches floating around for this, and I've already
pulled in your branch. Soproabbyl simpler if I pull this into
drm-intel.git
-Daniel
> 
> 
> thanks,
> 
> Takashi
> 
> 
> > 
> > 
> > >   Documentation/DocBook/drm.tmpl |  1 +
> > >   include/drm/i915_component.h   | 92 ++++++++++++++++++++++++++++++------------
> > >   2 files changed, 67 insertions(+), 26 deletions(-)
> > >
> > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> > > index 9ddf8c6..f16e4e8 100644
> > > --- a/Documentation/DocBook/drm.tmpl
> > > +++ b/Documentation/DocBook/drm.tmpl
> > > @@ -4051,6 +4051,7 @@ int num_ioctls;</synopsis>
> > >   	<title>High Definition Audio</title>
> > >   !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port
> > >   !Idrivers/gpu/drm/i915/intel_audio.c
> > > +!Iinclude/drm/i915_component.h
> > >         </sect2>
> > >         <sect2>
> > >   	<title>Panel Self Refresh PSR (PSR/SRD)</title>
> > > diff --git a/include/drm/i915_component.h b/include/drm/i915_component.h
> > > index 89dc7d6..76c10c8 100644
> > > --- a/include/drm/i915_component.h
> > > +++ b/include/drm/i915_component.h
> > > @@ -30,38 +30,78 @@
> > >    */
> > >   #define MAX_PORTS 5
> > >
> > > +/**
> > > + * struct i915_audio_component_ops - Ops implemented by i915 driver, called by hda driver
> > > + */
> > > +struct i915_audio_component_ops {
> > > +	/**
> > > +	 * @owner: i915 module
> > > +	 */
> > > +	struct module *owner;
> > > +	/**
> > > +	 * @get_power: Request that power well is to be turned on
> > > +	 */
> > > +	void (*get_power)(struct device *);
> > > +	/**
> > > +	 * @put_power: Allow the power well to be turned off
> > > +	 */
> > > +	void (*put_power)(struct device *);
> > > +	/**
> > > +	 * @codec_wake_override: Force the audio codec to stay awake
> > > +	 */
> > > +	void (*codec_wake_override)(struct device *, bool enable);
> > > +	/**
> > > +	 * @get_cdclk_freq: Query the i915 driver about the current cdclk frequency
> > > +	 */
> > > +	int (*get_cdclk_freq)(struct device *);
> > > +	/**
> > > +	 * @sync_audio_rate: set n/cts based on the sample rate
> > > +	 *
> > > +	 * Called from audio driver. After audio driver sets the
> > > +	 * sample rate, it will call this function to set n/cts
> > > +	 */
> > > +	int (*sync_audio_rate)(struct device *, int port, int rate);
> > > +};
> > > +
> > > +/**
> > > + * struct i915_audio_component_audio_ops - Ops implemented by hda driver, called by i915 driver
> > > + */
> > > +struct i915_audio_component_audio_ops {
> > > +	/**
> > > +	 * @audio_ptr: Pointer to be used in call to pin_eld_notify
> > > +	 */
> > > +	void *audio_ptr;
> > > +	/**
> > > +	 * @pin_eld_notify: Notify the HDA driver that pin sense and/or ELD information has changed
> > > +	 *
> > > +	 * Called when the i915 driver has set up audio pipeline or has just
> > > +	 * begun to tear it down. This allows the HDA driver to update its
> > > +	 * status accordingly (even when the HDA controller is in power save
> > > +	 * mode).
> > > +	 */
> > > +	void (*pin_eld_notify)(void *audio_ptr, int port);
> > > +};
> > > +
> > > +/**
> > > + * struct i915_audio_component - Used for direct communication between i915 and hda drivers
> > > + */
> > >   struct i915_audio_component {
> > > +	/**
> > > +	 * @dev: i915 device, used as parameter for ops
> > > +	 */
> > >   	struct device *dev;
> > >   	/**
> > >   	 * @aud_sample_rate: the array of audio sample rate per port
> > >   	 */
> > >   	int aud_sample_rate[MAX_PORTS];
> > > -
> > > -	const struct i915_audio_component_ops {
> > > -		struct module *owner;
> > > -		void (*get_power)(struct device *);
> > > -		void (*put_power)(struct device *);
> > > -		void (*codec_wake_override)(struct device *, bool enable);
> > > -		int (*get_cdclk_freq)(struct device *);
> > > -		/**
> > > -		 * @sync_audio_rate: set n/cts based on the sample rate
> > > -		 *
> > > -		 * Called from audio driver. After audio driver sets the
> > > -		 * sample rate, it will call this function to set n/cts
> > > -		 */
> > > -		int (*sync_audio_rate)(struct device *, int port, int rate);
> > > -	} *ops;
> > > -
> > > -	const struct i915_audio_component_audio_ops {
> > > -		void *audio_ptr;
> > > -		/**
> > > -		 * Call from i915 driver, notifying the HDA driver that
> > > -		 * pin sense and/or ELD information has changed.
> > > -		 * @audio_ptr:		HDA driver object
> > > -		 * @port:		Which port has changed (PORTA / PORTB / PORTC etc)
> > > -		 */
> > > -		void (*pin_eld_notify)(void *audio_ptr, int port);
> > > -	} *audio_ops;
> > > +	/**
> > > +	 * @ops: Ops implemented by i915 driver, called by hda driver
> > > +	 */
> > > +	const struct i915_audio_component_ops *ops;
> > > +	/**
> > > +	 * @audio_ops: Ops implemented by hda driver, called by i915 driver
> > > +	 */
> > > +	const struct i915_audio_component_audio_ops *audio_ops;
> > >   };
> > >
> > >   #endif /* _I915_COMPONENT_H_ */
> > >
> > 
> > -- 
> > David Henningsson, Canonical Ltd.
> > https://launchpad.net/~diwic
> > 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch