Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 78dd5e21 authored by Takashi Iwai's avatar Takashi Iwai
Browse files

ALSA: hda - Add / fix kernel doc comments 



Give some readable comment in kernel doc style for each exported
function, as I promised in the previous meetings.  While we're at it,
fix the wrong comments, too.

Signed-off-by: default avatarTakashi Iwai <tiwai@suse.de>
parent e5e113cf

sound/hda/hdac_bus.c

+14 −0
Original line number Diff line number Diff line
@@ -172,6 +172,15 @@ static void process_unsol_events(struct work_struct *work) 
	}

}



/**

 * snd_hdac_bus_add_device - Add a codec to bus

 * @bus: HDA core bus

 * @codec: HDA core device to add

 *

 * Adds the given codec to the list in the bus.  The caddr_tbl array

 * and codec_powered bits are updated, as well.

 * Returns zero if success, or a negative error code.

 */

int snd_hdac_bus_add_device(struct hdac_bus *bus, struct hdac_device *codec)

{

	if (bus->caddr_tbl[codec->addr]) {
@@ -188,6 +197,11 @@ int snd_hdac_bus_add_device(struct hdac_bus *bus, struct hdac_device *codec) 
}

EXPORT_SYMBOL_GPL(snd_hdac_bus_add_device);



/**

 * snd_hdac_bus_remove_device - Remove a codec from bus

 * @bus: HDA core bus

 * @codec: HDA core device to remove

 */

void snd_hdac_bus_remove_device(struct hdac_bus *bus,

				struct hdac_device *codec)

{

sound/hda/hdac_device.c

+6 −4
Original line number Diff line number Diff line
@@ -629,8 +629,10 @@ int snd_hdac_power_down_pm(struct hdac_device *codec) 
EXPORT_SYMBOL_GPL(snd_hdac_power_down_pm);

#endif



/*

 * Enable/disable the link power for a codec.

/**

 * snd_hdac_link_power - Enable/disable the link power for a codec

 * @codec: the codec object

 * @bool: enable or disable the link power

 */

int snd_hdac_link_power(struct hdac_device *codec, bool enable)

{
@@ -1048,8 +1050,8 @@ int snd_hdac_codec_write(struct hdac_device *hdac, hda_nid_t nid, 
}

EXPORT_SYMBOL_GPL(snd_hdac_codec_write);



/*

 * snd_hdac_check_power_state: check whether the actual power state matches

/**

 * snd_hdac_check_power_state - check whether the actual power state matches

 * with the target state

 *

 * @hdac: the HDAC device

sound/hda/hdac_i915.c

+70 −0
Original line number Diff line number Diff line
@@ -23,6 +23,19 @@ 


static struct i915_audio_component *hdac_acomp;



/**

 * snd_hdac_set_codec_wakeup - Enable / disable HDMI/DP codec wakeup

 * @bus: HDA core bus

 * @enable: enable or disable the wakeup

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function should be called during the chip reset, also called at

 * resume for updating STATESTS register read.

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_set_codec_wakeup(struct hdac_bus *bus, bool enable)

{

	struct i915_audio_component *acomp = bus->audio_component;
@@ -45,6 +58,19 @@ int snd_hdac_set_codec_wakeup(struct hdac_bus *bus, bool enable) 
}

EXPORT_SYMBOL_GPL(snd_hdac_set_codec_wakeup);



/**

 * snd_hdac_display_power - Power up / down the power refcount

 * @bus: HDA core bus

 * @enable: power up or down

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function manages a refcount and calls the i915 get_power() and

 * put_power() ops accordingly, toggling the codec wakeup, too.

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_display_power(struct hdac_bus *bus, bool enable)

{

	struct i915_audio_component *acomp = bus->audio_component;
@@ -71,6 +97,16 @@ int snd_hdac_display_power(struct hdac_bus *bus, bool enable) 
}

EXPORT_SYMBOL_GPL(snd_hdac_display_power);



/**

 * snd_hdac_get_display_clk - Get CDCLK in kHz

 * @bus: HDA core bus

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function queries CDCLK value in kHz from the graphics driver and

 * returns the value.  A negative code is returned in error.

 */

int snd_hdac_get_display_clk(struct hdac_bus *bus)

{

	struct i915_audio_component *acomp = bus->audio_component;
@@ -134,6 +170,17 @@ static int hdac_component_master_match(struct device *dev, void *data) 
	return !strcmp(dev->driver->name, "i915");

}



/**

 * snd_hdac_i915_register_notifier - Register i915 audio component ops

 * @aops: i915 audio component ops

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function sets the given ops to be called by the i915 graphics driver.

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_i915_register_notifier(const struct i915_audio_component_audio_ops *aops)

{

	if (WARN_ON(!hdac_acomp))
@@ -144,6 +191,18 @@ int snd_hdac_i915_register_notifier(const struct i915_audio_component_audio_ops 
}

EXPORT_SYMBOL_GPL(snd_hdac_i915_register_notifier);



/**

 * snd_hdac_i915_init - Initialize i915 audio component

 * @bus: HDA core bus

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function initializes and sets up the audio component to communicate

 * with i915 graphics driver.

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_i915_init(struct hdac_bus *bus)

{

	struct component_match *match = NULL;
@@ -187,6 +246,17 @@ int snd_hdac_i915_init(struct hdac_bus *bus) 
}

EXPORT_SYMBOL_GPL(snd_hdac_i915_init);



/**

 * snd_hdac_i915_exit - Finalize i915 audio component

 * @bus: HDA core bus

 *

 * This function is supposed to be used only by a HD-audio controller

 * driver that needs the interaction with i915 graphics.

 *

 * This function releases the i915 audio component that has been used.

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_i915_exit(struct hdac_bus *bus)

{

	struct device *dev = bus->dev;

sound/hda/hdac_regmap.c

+10 −0
Original line number Diff line number Diff line
@@ -339,6 +339,12 @@ static const struct regmap_config hda_regmap_cfg = { 
	.use_single_rw = true,

};



/**

 * snd_hdac_regmap_init - Initialize regmap for HDA register accesses

 * @codec: the codec object

 *

 * Returns zero for success or a negative error code.

 */

int snd_hdac_regmap_init(struct hdac_device *codec)

{

	struct regmap *regmap;
@@ -352,6 +358,10 @@ int snd_hdac_regmap_init(struct hdac_device *codec) 
}

EXPORT_SYMBOL_GPL(snd_hdac_regmap_init);



/**

 * snd_hdac_regmap_init - Release the regmap from HDA codec

 * @codec: the codec object

 */

void snd_hdac_regmap_exit(struct hdac_device *codec)

{

	if (codec->regmap) {

sound/hda/hdac_stream.c

+2 −1
Original line number Diff line number Diff line
@@ -426,7 +426,8 @@ int snd_hdac_stream_setup_periods(struct hdac_stream *azx_dev) 
}

EXPORT_SYMBOL_GPL(snd_hdac_stream_setup_periods);



/* snd_hdac_stream_set_params - set stream parameters

/**

 * snd_hdac_stream_set_params - set stream parameters

 * @azx_dev: HD-audio core stream for which parameters are to be set

 * @format_val: format value parameter

 *