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

[David Henningsson]

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


>   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