Documentation/sound/soc/machine.rst

   1 ===================
   2 ASoC Machine Driver
   3 ===================
   4
   5 The ASoC machine (or board) driver is the code that glues together all the
   6 component drivers (e.g. codecs, platforms and DAIs). It also describes the
   7 relationships between each component which include audio paths, GPIOs,
   8 interrupts, clocking, jacks and voltage regulators.
   9
  10 The machine driver can contain codec and platform specific code. It registers
  11 the audio subsystem with the kernel as a platform device and is represented by
  12 the following struct:-
  13 ::
  14
  15   /* SoC machine */
  16   struct snd_soc_card {
  17         char *name;
  18
  19         ...
  20
  21         int (*probe)(struct platform_device *pdev);
  22         int (*remove)(struct platform_device *pdev);
  23
  24         /* the pre and post PM functions are used to do any PM work before and
  25          * after the codec and DAIs do any PM work. */
  26         int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
  27         int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
  28         int (*resume_pre)(struct platform_device *pdev);
  29         int (*resume_post)(struct platform_device *pdev);
  30
  31         ...
  32
  33         /* CPU <--> Codec DAI links  */
  34         struct snd_soc_dai_link *dai_link;
  35         int num_links;
  36
  37         ...
  38   };
  39
  40 probe()/remove()
  41 ----------------
  42 probe/remove are optional. Do any machine specific probe here.
  43
  44
  45 suspend()/resume()
  46 ------------------
  47 The machine driver has pre and post versions of suspend and resume to take care
  48 of any machine audio tasks that have to be done before or after the codec, DAIs
  49 and DMA is suspended and resumed. Optional.
  50
  51
  52 Machine DAI Configuration
  53 -------------------------
  54 The machine DAI configuration glues all the codec and CPU DAIs together. It can
  55 also be used to set up the DAI system clock and for any machine related DAI
  56 initialisation e.g. the machine audio map can be connected to the codec audio
  57 map, unconnected codec pins can be set as such.
  58
  59 struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
  60 ::
  61
  62   /* corgi digital audio interface glue - connects codec <--> CPU */
  63   static struct snd_soc_dai_link corgi_dai = {
  64         .name = "WM8731",
  65         .stream_name = "WM8731",
  66         .cpu_dai_name = "pxa-is2-dai",
  67         .codec_dai_name = "wm8731-hifi",
  68         .platform_name = "pxa-pcm-audio",
  69         .codec_name = "wm8713-codec.0-001a",
  70         .init = corgi_wm8731_init,
  71         .ops = &corgi_ops,
  72   };
  73
  74 In the above struct, dai’s are registered using names but you can pass
  75 either dai name or device tree node but not both. Also, names used here
  76 for cpu/codec/platform dais should be globally unique.
  77
  78 Additionaly below example macro can be used to register cpu, codec and
  79 platform dai::
  80
  81   SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp,
  82         DAILINK_COMP_ARRAY(COMP_CPU("samsung-i2s.0")),
  83         DAILINK_COMP_ARRAY(COMP_CODEC("spi0.0", "wm0010-sdi1")),
  84         DAILINK_COMP_ARRAY(COMP_PLATFORM("samsung-i2s.0")));
  85
  86 struct snd_soc_card then sets up the machine with its DAIs. e.g.
  87 ::
  88
  89   /* corgi audio machine driver */
  90   static struct snd_soc_card snd_soc_corgi = {
  91         .name = "Corgi",
  92         .dai_link = &corgi_dai,
  93         .num_links = 1,
  94   };
  95
  96 Following this, ``devm_snd_soc_register_card`` can be used to register
  97 the sound card. During the registration, the individual components
  98 such as the codec, CPU, and platform are probed. If all these components
  99 are successfully probed, the sound card gets registered.
 100
 101 Machine Power Map
 102 -----------------
 103
 104 The machine driver can optionally extend the codec power map and to become an
 105 audio power map of the audio subsystem. This allows for automatic power up/down
 106 of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
 107 sockets in the machine init function.
 108
 109
 110 Machine Controls
 111 ----------------
 112
 113 Machine specific audio mixer controls can be added in the DAI init function.
 114
 115
 116 Clocking Controls
 117 -----------------
 118
 119 As previously noted, clock configuration is handled within the machine driver.
 120 For details on the clock APIs that the machine driver can utilize for
 121 setup, please refer to Documentation/sound/soc/clocking.rst. However, the
 122 callback needs to be registered by the CPU/Codec/Platform drivers to configure
 123 the clocks that is needed for the corresponding device operation.