[Intel-gfx] [PATCH v2] drm/i915: Improve kernel-doc for i915_audio_component struct

[Takashi Iwai]

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).


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
>