linux音頻alsa驅動分析之三 解碼器

ASoC Codec Driver
ASoC解碼器驅動
=================

The codec driver is generic and hardware independent code that configures the
codec to provide audio capture and playback. It should contain no code that is
specific to the target platform or machine. All platform and machine specific
code should be added to the platform and machine drivers respectively.
解碼器驅動是通用、硬件無關的代碼，它配置解碼器以支持音頻捕獲與回放。它不應包含任何與目標平臺或機器相關的代碼。平臺或機器相關代碼應該分別加 入到平臺和機器驅動中去。


Each codec driver *must* provide the following features:-
各解碼器驅動必須提供如下特性：

1) Codec DAI and PCM configuration
2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs
3) Mixers and audio controls
4) Codec audio operations
1）解碼器數字音頻接口和PCM配置。
2）解碼器控制IO－使用I2C，3總線（SPI）或兩個都有。
3）混音器和音頻控制。
4）解碼器音頻操作。


Optionally, codec drivers can also provide:-
解碼器驅動可以選擇性提供：

5) DAPM description.
6) DAPM event handler.
7) DAC Digital mute control.
5）動態音頻電源管理描述。
6）動態音頻電源管理事件控制。
7）數模轉換數字消音控制。


Its probably best to use this guide in conjunction with the existing codec
driver code in sound/soc/codecs/
大家也許最好聯同己存在於sound/soc/codecs/中的驅動代碼一起來使用這個指導書。


ASoC Codec driver breakdown
ASoC 解碼器解析
===========================

1 - Codec DAI and PCM configuration
1－解碼器數字音頻接口和PCM配置
-----------------------------------
Each codec driver must have a struct snd_soc_codec_dai to define its DAI and
PCM capabilities and operations. This struct is exported so that it can be
registered with the core by your machine driver.
各解碼器驅動必須有一個snd_soc_codec_dai數據結構，它用來定義DAI和PCM提供的功能和操作。這個數據結構要導出，好讓你的機器驅動程序將它註冊到ALSA核心中去。

e.g.
例如：
struct snd_soc_codec_dai wm8731_dai = {
    .name = "WM8731",
    /* playback capabilities */
    .playback = {
        .stream_name = "Playback",
        .channels_min = 1,
        .channels_max = 2,
        .rates = WM8731_RATES,
        .formats = WM8731_FORMATS,},
    /* capture capabilities */
    .capture = {
        .stream_name = "Capture",
        .channels_min = 1,
        .channels_max = 2,
        .rates = WM8731_RATES,
        .formats = WM8731_FORMATS,},
    /* pcm operations - see section 4 below */
    .ops = {
        .prepare = wm8731_pcm_prepare,
        .hw_params = wm8731_hw_params,
        .shutdown = wm8731_shutdown,
    },
    /* DAI operations - see DAI.txt */
    .dai_ops = {
        .digital_mute = wm8731_mute,
        .set_sysclk = wm8731_set_dai_sysclk,
        .set_fmt = wm8731_set_dai_fmt,
    }
};
EXPORT_SYMBOL_GPL(wm8731_dai);


2 - Codec control IO
2－解碼器控制IO
--------------------
The codec can usually be controlled via an I2C or SPI style interface
(AC97 combines control with data in the DAI). The codec drivers provide
functions to read and write the codec registers along with supplying a
register cache:-
解碼器通常可以通過I2C或SPI類型的接器進行控制（AC97 的數字音頻接口中把數據和控制結合在了一起）。解碼器驅動提供讀寫解碼器寄存器和供應寄存器緩存的功能。

    /* IO control data and register cache */
    void *control_data; /* codec control (i2c/3wire) data */
    void *reg_cache;

Codec read/write should do any data formatting and call the hardware
read write below to perform the IO. These functions are called by the
core and ALSA when performing DAPM or changing the mixer:-
解碼器讀寫要可以作用於任何格式，調用底層硬件的讀寫功能操作IO。
ALSA核或ALSA在動態音頻電源管理或改變混音器時會調用這些函數。

    unsigned int (*read)(struct snd_soc_codec *, unsigned int);
    int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);

Codec hardware IO functions - usually points to either the I2C, SPI or AC97
read/write:-
解碼器硬件IO函數－通常指向I2C，SPI或AC97的讀寫：


    hw_write_t hw_write;
    hw_read_t hw_read;


3 - Mixers and audio controls
3－混音器和音頻控制
-----------------------------
All the codec mixers and audio controls can be defined using the convenience
macros defined in soc.h.
所有解碼器混音器和音頻控制都可以通過使用soc.h中定義的宏而帶來方便。

    #define SOC_SINGLE(xname, reg, shift, mask, invert)

Defines a single control as follows:-
這個宏可以定義一個單次操作：
  xname = Control name e.g. "Playback Volume"
  reg = codec register
  shift = control bit(s) offset in register
  mask = control bit size(s) e.g. mask of 7 = 3 bits
  invert = the control is inverted

Other macros include:-
其它的宏還有：

    #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)

A stereo control
下面是一個立體聲控制：

    #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)

A stereo control spanning 2 registers
擴用兩個寄存器的立體聲控制如下：

    #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)

Defines an single enumerated control as follows:-
定義一個枚舉控制如下：


   xreg = register
   xshift = control bit(s) offset in register
   xmask = control bit(s) size
   xtexts = pointer to array of strings that describe each setting

   #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)

Defines a stereo enumerated control
上面的宏定義一個立體聲枚舉控制。


4 - Codec Audio Operations
4－解碼器音頻操作
--------------------------
The codec driver also supports the following ALSA operations:-
解碼器驅動還支持下面的ALSA操作：

/* SoC audio ops */
struct snd_soc_ops {
    int (*startup)(struct snd_pcm_substream *);
    void (*shutdown)(struct snd_pcm_substream *);
    int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
    int (*hw_free)(struct snd_pcm_substream *);
    int (*prepare)(struct snd_pcm_substream *);
};

Please refer to the ALSA driver PCM documentation for details.
詳情請參考ALSA驅動PCM文檔：
http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm


5 - DAPM description.
5－動態音頻電源管理
---------------------
The Dynamic Audio Power Management description describes the codec power
components and their relationships and registers to the ASoC core.
Please read dapm.txt for details of building the description.
動態音頻電源管理描述的是解碼器電源組件和它們的關係，和向ASoC核註冊的方法。詳情請閱dapm.txt。

Please also see the examples in other codec drivers.
也請參照其它解碼器的例子。


6 - DAPM event handler
6－動態音頻電源管理事件句柄
----------------------
This function is a callback that handles codec domain PM calls and system
domain PM calls (e.g. suspend and resume). It is used to put the codec
to sleep when not in use.
該功能是一個回調函數，用來處理解碼器域的電源管理調用和系統域的電源管理調用（如掛起和恢復）。它用來在不用時使解碼器進入休眠狀態。

Power states:-
電源狀態：

    SNDRV_CTL_POWER_D0: /* full On */
    /* vref/mid, clk and osc on, active */

    SNDRV_CTL_POWER_D1: /* partial On */
    SNDRV_CTL_POWER_D2: /* partial On */

    SNDRV_CTL_POWER_D3hot: /* Off, with power */
    /* everything off except vref/vmid, inactive */

    SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */


7 - Codec DAC digital mute control
7－解碼器數模轉換消音控制
----------------------------------
Most codecs have a digital mute before the DACs that can be used to
minimise any system noise.  The mute stops any digital data from
entering the DAC.
多數解碼器都有一個數字消音裝置放在數模轉換器前面。它可以用來最小化系統躁聲。消音器不讓任何數字數據進入DAC。

A callback can be created that is called by the core for each codec DAI
when the mute is applied or freed.
消音器使用或釋放時會創造一個回調。ASoC核會爲每個解碼器數字音頻接口調用這個回調函數。


i.e.

static int wm8974_mute(struct snd_soc_codec *codec,
    struct snd_soc_codec_dai *dai, int mute)
{
    u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
    if(mute)
        wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
    else
        wm8974_write(codec, WM8974_DAC, mute_reg);
    return 0;
}