/[openvortex]/alsa/alsa-kernel/Documentation/DocBook/writing-an-alsa-driver.tmpl
ViewVC logotype

Diff of /alsa/alsa-kernel/Documentation/DocBook/writing-an-alsa-driver.tmpl

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by vizard, Sat May 31 02:35:09 2003 UTC revision 1.3 by vizard, Mon Aug 11 00:06:37 2003 UTC
# Line 239  Line 239 
239      <section id="file-tree-drivers-directory">      <section id="file-tree-drivers-directory">
240        <title>drivers directory</title>        <title>drivers directory</title>
241        <para>        <para>
242          This directory contains the non-architecture-specific          This directory contains the codes shared among different drivers
243        codes. For example, the dummy pcm driver and the serial MIDI        on the different architectures.  They are hence supposed not to be
244          architecture-specific.
245          For example, the dummy pcm driver and the serial MIDI
246        driver are found in this directory. In the sub-directories,        driver are found in this directory. In the sub-directories,
247        there are the codes for components which are independent from        there are the codes for components which are independent from
248        bus and cpu architectures.        bus and cpu architectures.
# Line 254  Line 256 
256        </section>        </section>
257    
258        <section id="file-tree-drivers-directory-opl3">        <section id="file-tree-drivers-directory-opl3">
259          <title>drivers/opl3</title>          <title>drivers/opl3 and opl4</title>
260          <para>          <para>
261            The OPL3 FM-synth stuff is found here.            The OPL3 and OPL4 FM-synth stuff is found here.
262          </para>          </para>
263        </section>        </section>
264      </section>      </section>
# Line 268  Line 270 
270        </para>        </para>
271    
272        <para>        <para>
273          Although there is a standard i2c layer on Linux, ALSA uses its          Although there is a standard i2c layer on Linux, ALSA has its
274        own i2c codes for some cards, because the soundcard needs only a        own i2c codes for some cards, because the soundcard needs only a
275        simple operation and the standard API is too complicated for        simple operation and the standard i2c API is too complicated for
276        such a purpose.        such a purpose.
277        </para>        </para>
278    
# Line 298  Line 300 
300        <title>pci directory</title>        <title>pci directory</title>
301        <para>        <para>
302          This and its sub-directories hold the top-level card modules          This and its sub-directories hold the top-level card modules
303        for PCI soundcards.        for PCI soundcards and the codes specific to the PCI BUS.
304        </para>        </para>
305    
306        <para>        <para>
# Line 320  Line 322 
322        <title>arm, ppc, and sparc directories</title>        <title>arm, ppc, and sparc directories</title>
323        <para>        <para>
324          These are for the top-level card modules which are          These are for the top-level card modules which are
325        architecture specific.        specific to each given architecture.
326        </para>        </para>
327      </section>      </section>
328    
# Line 2906  struct _snd_pcm_runtime { Line 2908  struct _snd_pcm_runtime {
2908          </para>          </para>
2909    
2910          <para>          <para>
2911            This callback may be called multiple times, too.            This function is always called before the close callback is called.
2912              Also, the callback may be called multiple times, too.
2913            Keep track whether the resource was already released.            Keep track whether the resource was already released.
2914          </para>          </para>
2915        </section>        </section>
# Line 3007  struct _snd_pcm_runtime { Line 3010  struct _snd_pcm_runtime {
3010          </para>          </para>
3011    
3012          <para>          <para>
3013            When the pcm supports the suspend/resume operation,            When the pcm supports the suspend/resume operation
3014            (i.e. <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set),
3015          <constant>SUSPEND</constant> and <constant>RESUME</constant>          <constant>SUSPEND</constant> and <constant>RESUME</constant>
3016          commands must be handled, too. Obviously it does suspend and          commands must be handled, too.
3017          resume of the pcm substream. Usually, the          These commands are issued when the power-management status is
3018          <constant>SUSPEND</constant> is identical with          changed.  Obviously, the <constant>SUSPEND</constant> and
3019          <constant>STOP</constant> command and the          <constant>RESUME</constant>
3020          <constant>RESUME</constant> is identical with          do suspend and resume of the pcm substream, and usually, they
3021          <constant>START</constant> command.          are identical with <constant>STOP</constant> and
3022            <constant>START</constant> commands, respectively.
3023          </para>          </para>
3024    
3025          <para>          <para>
# Line 3280  struct _snd_pcm_runtime { Line 3285  struct _snd_pcm_runtime {
3285        <function>udelay()</function> or <function>mdelay()</function>.        <function>udelay()</function> or <function>mdelay()</function>.
3286        </para>        </para>
3287    
       <para>  
       This atomicity problem appears also in the initialization of the  
       hardware when the power-management is supported.  The functions  
       for suspending and resuming the chip must be atomic, i.e. no  
       mutex nor sleep can be used in them.  
       </para>  
   
3288      </section>      </section>
3289      <section id="pcm-interface-constraints">      <section id="pcm-interface-constraints">
3290        <title>Constraints</title>        <title>Constraints</title>
# Line 3331  struct _snd_pcm_runtime { Line 3329  struct _snd_pcm_runtime {
3329        </para>        </para>
3330    
3331        <para>        <para>
3332          There are many different constraints. You can even define your          There are many different constraints.
3333        own constraint rules. I won't explain the details here, rather I          Look in <filename>sound/asound.h</filename> for a complete list.
3334        would like to say, <quote>Luke, use the source.</quote>          You can even define your own constraint rules.
3335            For example, let's suppose my_chip can manage a substream of 1 channel
3336            if and only if the format is S16_LE, otherwise it supports any format
3337            specified in the <type>snd_pcm_hardware_t</type> stucture (or in any
3338            other constraint_list). You can build a rule like this:
3339    
3340            <example>
3341              <title>Example of Hardware Constraints for Channels</title>
3342              <programlisting>
3343    <![CDATA[
3344      static int hw_rule_format_by_channels(snd_pcm_hw_params_t *params,
3345                                            snd_pcm_hw_rule_t *rule)
3346      {
3347              snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
3348              snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3349              snd_mask_t fmt;
3350    
3351              snd_mask_any(&fmt);    // Init the struct
3352              if (c->min < 2) {
3353                      fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
3354                      return snd_mask_refine(f, &fmt);
3355              }
3356              return 0;
3357      }
3358    ]]>
3359              </programlisting>
3360            </example>
3361          </para>
3362    
3363          <para>
3364            Then you need to call this function to add your rule:
3365    
3366           <informalexample>
3367             <programlisting>
3368    <![CDATA[
3369      snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3370                          hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3371                          -1);
3372    ]]>
3373              </programlisting>
3374            </informalexample>
3375          </para>
3376    
3377          <para>
3378            The rule function is called when an application sets the number of
3379            channels. But an application can set the format before the number of
3380            channels. Thus you also need to define the inverse rule:
3381    
3382           <example>
3383             <title>Example of Hardware Constraints for Channels</title>
3384             <programlisting>
3385    <![CDATA[
3386      static int hw_rule_channels_by_format(snd_pcm_hw_params_t *params,
3387                                            snd_pcm_hw_rule_t *rule)
3388      {
3389              snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS);
3390              snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
3391              snd_interval_t ch;
3392    
3393              snd_interval_any(&ch);
3394              if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
3395                      ch.min = ch.max = 1;
3396                      ch.integer = 1;
3397                      return snd_interval_refine(c, &ch);
3398              }
3399              return 0;
3400      }
3401    ]]>
3402              </programlisting>
3403            </example>
3404          </para>
3405    
3406          <para>
3407          ...and in the open callback:
3408           <informalexample>
3409             <programlisting>
3410    <![CDATA[
3411      snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
3412                          hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
3413                          -1);
3414    ]]>
3415              </programlisting>
3416            </informalexample>
3417          </para>
3418    
3419          <para>
3420            I won't explain more details here, rather I
3421            would like to say, <quote>Luke, use the source.</quote>
3422        </para>        </para>
3423      </section>      </section>
3424    
# Line 3989  struct _snd_pcm_runtime { Line 4074  struct _snd_pcm_runtime {
4074        </para>        </para>
4075    
4076        <para>        <para>
4077        These callbacks are non-atomic like the callbacks of control API        These callbacks are non-atomic like the callbacks of control API.
       unless they are called during suspend/resume phase.  
4078        </para>        </para>
4079    
4080        <para>        <para>
# Line 4004  struct _snd_pcm_runtime { Line 4088  struct _snd_pcm_runtime {
4088          The <structfield>reset</structfield> callback is used to reset          The <structfield>reset</structfield> callback is used to reset
4089        the codec. If the chip requires a special way of reset, you can        the codec. If the chip requires a special way of reset, you can
4090        define this callback.        define this callback.
       This callback must be atomic when it's called in the suspend  
       mode.  
4091        </para>        </para>
4092    
4093        <para>        <para>
# Line 5122  struct _snd_pcm_runtime { Line 5204  struct _snd_pcm_runtime {
5204      </para>      </para>
5205    
5206      <para>      <para>
5207          For keeping the readability of 2.5 source code, it's recommended to
5208          separate the above ifdef condition as the patch file in alsa-driver
5209          directory.
5210          See <filename>alsa-driver/pci/ali5451.c</filename> for example.
5211       </para>
5212    
5213        <para>
5214        The scheme of the real suspend job is as following.        The scheme of the real suspend job is as following.
5215    
5216        <orderedlist>        <orderedlist>
# Line 5293  struct _snd_pcm_runtime { Line 5382  struct _snd_pcm_runtime {
5382        </informalexample>        </informalexample>
5383      </para>      </para>
5384    
     <para>  
       Last but not least: Please keep in mind that you cannot call  
     <function>schedule()</function> during the suspend and the resume  
     callbacks. If any delay is necessary, you have to use  
     <function>mdelay()</function> or <function>udelay()</function>  
     instead of <function>schedule_timeout()</function>!  
     Of course, semaphores cannot be used, too, which will invoke sleep  
     inside.  
     </para>  
5385    </chapter>    </chapter>
5386    
5387    
# Line 5756  struct _snd_pcm_runtime { Line 5836  struct _snd_pcm_runtime {
5836      Kevin Conder reformatted the original plain-text to the      Kevin Conder reformatted the original plain-text to the
5837      DocBook format.      DocBook format.
5838      </para>      </para>
5839        <para>
5840        Giuliano Pochini corrected typos and contributed the example codes
5841        in the hardware constraints section.
5842        </para>
5843    </chapter>    </chapter>
5844    
5845    

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26