Skip to content

Commit

Permalink
ASoC: fix documentation in CS4270 codec driver
Browse files Browse the repository at this point in the history 
Spruce up the documentation in the CS4270 codec.  Use kerneldoc where
appropriate.  Fix incorrect comments.

Signed-off-by: Timur Tabi <timur@freescale.com>
Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
  • Loading branch information
Timur Tabi authored and Mark Brown committed Jan 31, 2009
1 parent 04eb093 commit ff7bf02
Showing 1 changed file with 105 additions and 58 deletions.
163 changes: 105 additions & 58 deletions sound/soc/codecs/cs4270.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
*
* Author: Timur Tabi <timur@freescale.com>
*
* Copyright 2007 Freescale Semiconductor, Inc. This file is licensed under
* the terms of the GNU General Public License version 2. This program
* is licensed "as is" without any warranty of any kind, whether express
* or implied.
* Copyright 2007-2009 Freescale Semiconductor, Inc. This file is licensed
* under the terms of the GNU General Public License version 2. This
* program is licensed "as is" without any warranty of any kind, whether
* express or implied.
*
* This is an ASoC device driver for the Cirrus Logic CS4270 codec.
*
Expand Down Expand Up @@ -111,8 +111,13 @@ struct cs4270_private {
unsigned int mode; /* The mode (I2S or left-justified) */
};

/*
* Clock Ratio Selection for Master Mode with I2C enabled
/**
* struct cs4270_mode_ratios - clock ratio tables
* @ratio: the ratio of MCLK to the sample rate
* @speed_mode: the Speed Mode bits to set in the Mode Control register for
* this ratio
* @mclk: the Ratio Select bits to set in the Mode Control register for this
* ratio
*
* The data for this chart is taken from Table 5 of the CS4270 reference
* manual.
Expand All @@ -121,31 +126,30 @@ struct cs4270_private {
* It is also used by cs4270_set_dai_sysclk() to tell ALSA which sampling
* rates the CS4270 currently supports.
*
* Each element in this array corresponds to the ratios in mclk_ratios[].
* These two arrays need to be in sync.
*
* 'speed_mode' is the corresponding bit pattern to be written to the
* @speed_mode is the corresponding bit pattern to be written to the
* MODE bits of the Mode Control Register
*
* 'mclk' is the corresponding bit pattern to be wirten to the MCLK bits of
* @mclk is the corresponding bit pattern to be wirten to the MCLK bits of
* the Mode Control Register.
*
* In situations where a single ratio is represented by multiple speed
* modes, we favor the slowest speed. E.g, for a ratio of 128, we pick
* double-speed instead of quad-speed. However, the CS4270 errata states
* that Divide-By-1.5 can cause failures, so we avoid that mode where
* that divide-By-1.5 can cause failures, so we avoid that mode where
* possible.
*
* ERRATA: There is an errata for the CS4270 where divide-by-1.5 does not
* work if VD = 3.3V. If this effects you, select the
* Errata: There is an errata for the CS4270 where divide-by-1.5 does not
* work if Vd is 3.3V. If this effects you, select the
* CONFIG_SND_SOC_CS4270_VD33_ERRATA Kconfig option, and the driver will
* never select any sample rates that require divide-by-1.5.
*/
static struct {
struct cs4270_mode_ratios {
unsigned int ratio;
u8 speed_mode;
u8 mclk;
} cs4270_mode_ratios[] = {
};

static struct cs4270_mode_ratios[] = {
{64, CS4270_MODE_4X, CS4270_MODE_DIV1},
#ifndef CONFIG_SND_SOC_CS4270_VD33_ERRATA
{96, CS4270_MODE_4X, CS4270_MODE_DIV15},
Expand All @@ -162,34 +166,27 @@ static struct {
/* The number of MCLK/LRCK ratios supported by the CS4270 */
#define NUM_MCLK_RATIOS ARRAY_SIZE(cs4270_mode_ratios)

/*
* Determine the CS4270 samples rates.
/**
* cs4270_set_dai_sysclk - determine the CS4270 samples rates.
* @codec_dai: the codec DAI
* @clk_id: the clock ID (ignored)
* @freq: the MCLK input frequency
* @dir: the clock direction (ignored)
*
* 'freq' is the input frequency to MCLK. The other parameters are ignored.
* This function is used to tell the codec driver what the input MCLK
* frequency is.
*
* The value of MCLK is used to determine which sample rates are supported
* by the CS4270. The ratio of MCLK / Fs must be equal to one of nine
* support values: 64, 96, 128, 192, 256, 384, 512, 768, and 1024.
* supported values - 64, 96, 128, 192, 256, 384, 512, 768, and 1024.
*
* This function calculates the nine ratios and determines which ones match
* a standard sample rate. If there's a match, then it is added to the list
* of support sample rates.
* of supported sample rates.
*
* This function must be called by the machine driver's 'startup' function,
* otherwise the list of supported sample rates will not be available in
* time for ALSA.
*
* Note that in stand-alone mode, the sample rate is determined by input
* pins M0, M1, MDIV1, and MDIV2. Also in stand-alone mode, divide-by-3
* is not a programmable option. However, divide-by-3 is not an available
* option in stand-alone mode. This cases two problems: a ratio of 768 is
* not available (it requires divide-by-3) and B) ratios 192 and 384 can
* only be selected with divide-by-1.5, but there is an errate that make
* this selection difficult.
*
* In addition, there is no mechanism for communicating with the machine
* driver what the input settings can be. This would need to be implemented
* for stand-alone mode to work.
*/
static int cs4270_set_dai_sysclk(struct snd_soc_dai *codec_dai,
int clk_id, unsigned int freq, int dir)
Expand Down Expand Up @@ -230,8 +227,10 @@ static int cs4270_set_dai_sysclk(struct snd_soc_dai *codec_dai,
return 0;
}

/*
* Configure the codec for the selected audio format
/**
* cs4270_set_dai_fmt - configure the codec for the selected audio format
* @codec_dai: the codec DAI
* @format: a SND_SOC_DAIFMT_x value indicating the data format
*
* This function takes a bitmask of SND_SOC_DAIFMT_x bits and programs the
* codec accordingly.
Expand Down Expand Up @@ -261,8 +260,16 @@ static int cs4270_set_dai_fmt(struct snd_soc_dai *codec_dai,
return ret;
}

/*
* Pre-fill the CS4270 register cache.
/**
* cs4270_fill_cache - pre-fill the CS4270 register cache.
* @codec: the codec for this CS4270
*
* This function fills in the CS4270 register cache by reading the register
* values from the hardware.
*
* This CS4270 registers are cached to avoid excessive I2C I/O operations.
* After the initial read to pre-fill the cache, the CS4270 never updates
* the register values, so we won't have a cache coherency problem.
*
* We use the auto-increment feature of the CS4270 to read all registers in
* one shot.
Expand All @@ -285,12 +292,17 @@ static int cs4270_fill_cache(struct snd_soc_codec *codec)
return 0;
}

/*
* Read from the CS4270 register cache.
/**
* cs4270_read_reg_cache - read from the CS4270 register cache.
* @codec: the codec for this CS4270
* @reg: the register to read
*
* This function returns the value for a given register. It reads only from
* the register cache, not the hardware itself.
*
* This CS4270 registers are cached to avoid excessive I2C I/O operations.
* After the initial read to pre-fill the cache, the CS4270 never updates
* the register values, so we won't have a cache coherncy problem.
* the register values, so we won't have a cache coherency problem.
*/
static unsigned int cs4270_read_reg_cache(struct snd_soc_codec *codec,
unsigned int reg)
Expand All @@ -303,8 +315,11 @@ static unsigned int cs4270_read_reg_cache(struct snd_soc_codec *codec,
return cache[reg - CS4270_FIRSTREG];
}

/*
* Write to a CS4270 register via the I2C bus.
/**
* cs4270_i2c_write - write to a CS4270 register via the I2C bus.
* @codec: the codec for this CS4270
* @reg: the register to write
* @value: the value to write to the register
*
* This function writes the given value to the given CS4270 register, and
* also updates the register cache.
Expand Down Expand Up @@ -336,11 +351,17 @@ static int cs4270_i2c_write(struct snd_soc_codec *codec, unsigned int reg,
return 0;
}

/*
* Program the CS4270 with the given hardware parameters.
/**
* cs4270_hw_params - program the CS4270 with the given hardware parameters.
* @substream: the audio stream
* @params: the hardware parameters to set
* @dai: the SOC DAI (ignored)
*
* The .ops functions are used to provide board-specific data, like
* input frequencies, to this driver. This function takes that information,
* This function programs the hardware with the values provided.
* Specifically, the sample rate and the data format.
*
* The .ops functions are used to provide board-specific data, like input
* frequencies, to this driver. This function takes that information,
* combines it with the hardware parameters provided, and programs the
* hardware accordingly.
*/
Expand Down Expand Up @@ -455,8 +476,10 @@ static int cs4270_hw_params(struct snd_pcm_substream *substream,
}

#ifdef CONFIG_SND_SOC_CS4270_HWMUTE
/*
* Set the CS4270 external mute
/**
* cs4270_mute - enable/disable the CS4270 external mute
* @dai: the SOC DAI
* @mute: 0 = disable mute, 1 = enable mute
*
* This function toggles the mute bits in the MUTE register. The CS4270's
* mute capability is intended for external muting circuitry, so if the
Expand Down Expand Up @@ -490,7 +513,7 @@ static const struct snd_kcontrol_new cs4270_snd_controls[] = {
};

/*
* Global variable to store codec for the ASoC probe function.
* cs4270_codec - global variable to store codec for the ASoC probe function
*
* If struct i2c_driver had a private_data field, we wouldn't need to use
* cs4270_codec. This is the only way to pass the codec structure from
Expand Down Expand Up @@ -527,8 +550,12 @@ struct snd_soc_dai cs4270_dai = {
};
EXPORT_SYMBOL_GPL(cs4270_dai);

/*
* ASoC probe function
/**
* cs4270_probe - ASoC probe function
* @pdev: platform device
*
* This function is called when ASoC has all the pieces it needs to
* instantiate a sound driver.
*/
static int cs4270_probe(struct platform_device *pdev)
{
Expand Down Expand Up @@ -582,6 +609,12 @@ static int cs4270_probe(struct platform_device *pdev)
return ret;
}

/**
* cs4270_remove - ASoC remove function
* @pdev: platform device
*
* This function is the counterpart to cs4270_probe().
*/
static int cs4270_remove(struct platform_device *pdev)
{
struct snd_soc_device *socdev = platform_get_drvdata(pdev);
Expand All @@ -591,14 +624,13 @@ static int cs4270_remove(struct platform_device *pdev)
return 0;
};

/*
* Initialize the I2C interface of the CS4270
*
* This function is called for whenever the I2C subsystem finds a device
* at a particular address.
/**
* cs4270_i2c_probe - initialize the I2C interface of the CS4270
* @i2c_client: the I2C client object
* @id: the I2C device ID (ignored)
*
* Note: snd_soc_new_pcms() must be called before this function can be called,
* because of snd_ctl_add().
* This function is called whenever the I2C subsystem finds a device that
* matches the device ID given via a prior call to i2c_add_driver().
*/
static int cs4270_i2c_probe(struct i2c_client *i2c_client,
const struct i2c_device_id *id)
Expand Down Expand Up @@ -690,6 +722,12 @@ static int cs4270_i2c_probe(struct i2c_client *i2c_client,
return ret;
}

/**
* cs4270_i2c_remove - remove an I2C device
* @i2c_client: the I2C client object
*
* This function is the counterpart to cs4270_i2c_probe().
*/
static int cs4270_i2c_remove(struct i2c_client *i2c_client)
{
struct cs4270_private *cs4270 = i2c_get_clientdata(i2c_client);
Expand All @@ -699,12 +737,21 @@ static int cs4270_i2c_remove(struct i2c_client *i2c_client)
return 0;
}

/*
* cs4270_id - I2C device IDs supported by this driver
*/
static struct i2c_device_id cs4270_id[] = {
{"cs4270", 0},
{}
};
MODULE_DEVICE_TABLE(i2c, cs4270_id);

/*
* cs4270_i2c_driver - I2C device identification
*
* This structure tells the I2C subsystem how to identify and support a
* given I2C device type.
*/
static struct i2c_driver cs4270_i2c_driver = {
.driver = {
.name = "cs4270",
Expand Down

0 comments on commit ff7bf02

Please sign in to comment.