ALSA: memalloc: Allow NULL device for SNDRV_DMA_TYPE_CONTINUOUS type
[sfrench/cifs-2.6.git] / Documentation / sound / kernel-api / writing-an-alsa-driver.rst
1 ======================
2 Writing an ALSA Driver
3 ======================
4
5 :Author: Takashi Iwai <tiwai@suse.de>
6
7 Preface
8 =======
9
10 This document describes how to write an `ALSA (Advanced Linux Sound
11 Architecture) <http://www.alsa-project.org/>`__ driver. The document
12 focuses mainly on PCI soundcards. In the case of other device types, the
13 API might be different, too. However, at least the ALSA kernel API is
14 consistent, and therefore it would be still a bit help for writing them.
15
16 This document targets people who already have enough C language skills
17 and have basic linux kernel programming knowledge. This document doesn't
18 explain the general topic of linux kernel coding and doesn't cover
19 low-level driver implementation details. It only describes the standard
20 way to write a PCI sound driver on ALSA.
21
22 This document is still a draft version. Any feedback and corrections,
23 please!!
24
25 File Tree Structure
26 ===================
27
28 General
29 -------
30
31 The file tree structure of ALSA driver is depicted below.
32
33 ::
34
35             sound
36                     /core
37                             /oss
38                             /seq
39                                     /oss
40                     /include
41                     /drivers
42                             /mpu401
43                             /opl3
44                     /i2c
45                     /synth
46                             /emux
47                     /pci
48                             /(cards)
49                     /isa
50                             /(cards)
51                     /arm
52                     /ppc
53                     /sparc
54                     /usb
55                     /pcmcia /(cards)
56                     /soc
57                     /oss
58
59
60 core directory
61 --------------
62
63 This directory contains the middle layer which is the heart of ALSA
64 drivers. In this directory, the native ALSA modules are stored. The
65 sub-directories contain different modules and are dependent upon the
66 kernel config.
67
68 core/oss
69 ~~~~~~~~
70
71 The codes for PCM and mixer OSS emulation modules are stored in this
72 directory. The rawmidi OSS emulation is included in the ALSA rawmidi
73 code since it's quite small. The sequencer code is stored in
74 ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
75
76 core/seq
77 ~~~~~~~~
78
79 This directory and its sub-directories are for the ALSA sequencer. This
80 directory contains the sequencer core and primary sequencer modules such
81 like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
82 ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
83
84 core/seq/oss
85 ~~~~~~~~~~~~
86
87 This contains the OSS sequencer emulation codes.
88
89 include directory
90 -----------------
91
92 This is the place for the public header files of ALSA drivers, which are
93 to be exported to user-space, or included by several files at different
94 directories. Basically, the private header files should not be placed in
95 this directory, but you may still find files there, due to historical
96 reasons :)
97
98 drivers directory
99 -----------------
100
101 This directory contains code shared among different drivers on different
102 architectures. They are hence supposed not to be architecture-specific.
103 For example, the dummy pcm driver and the serial MIDI driver are found
104 in this directory. In the sub-directories, there is code for components
105 which are independent from bus and cpu architectures.
106
107 drivers/mpu401
108 ~~~~~~~~~~~~~~
109
110 The MPU401 and MPU401-UART modules are stored here.
111
112 drivers/opl3 and opl4
113 ~~~~~~~~~~~~~~~~~~~~~
114
115 The OPL3 and OPL4 FM-synth stuff is found here.
116
117 i2c directory
118 -------------
119
120 This contains the ALSA i2c components.
121
122 Although there is a standard i2c layer on Linux, ALSA has its own i2c
123 code for some cards, because the soundcard needs only a simple operation
124 and the standard i2c API is too complicated for such a purpose.
125
126 synth directory
127 ---------------
128
129 This contains the synth middle-level modules.
130
131 So far, there is only Emu8000/Emu10k1 synth driver under the
132 ``synth/emux`` sub-directory.
133
134 pci directory
135 -------------
136
137 This directory and its sub-directories hold the top-level card modules
138 for PCI soundcards and the code specific to the PCI BUS.
139
140 The drivers compiled from a single file are stored directly in the pci
141 directory, while the drivers with several source files are stored on
142 their own sub-directory (e.g. emu10k1, ice1712).
143
144 isa directory
145 -------------
146
147 This directory and its sub-directories hold the top-level card modules
148 for ISA soundcards.
149
150 arm, ppc, and sparc directories
151 -------------------------------
152
153 They are used for top-level card modules which are specific to one of
154 these architectures.
155
156 usb directory
157 -------------
158
159 This directory contains the USB-audio driver. In the latest version, the
160 USB MIDI driver is integrated in the usb-audio driver.
161
162 pcmcia directory
163 ----------------
164
165 The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
166 be in the pci directory, because their API is identical to that of
167 standard PCI cards.
168
169 soc directory
170 -------------
171
172 This directory contains the codes for ASoC (ALSA System on Chip)
173 layer including ASoC core, codec and machine drivers.
174
175 oss directory
176 -------------
177
178 Here contains OSS/Lite codes.
179 All codes have been deprecated except for dmasound on m68k as of
180 writing this.
181
182
183 Basic Flow for PCI Drivers
184 ==========================
185
186 Outline
187 -------
188
189 The minimum flow for PCI soundcards is as follows:
190
191 -  define the PCI ID table (see the section `PCI Entries`_).
192
193 -  create ``probe`` callback.
194
195 -  create ``remove`` callback.
196
197 -  create a :c:type:`struct pci_driver <pci_driver>` structure
198    containing the three pointers above.
199
200 -  create an ``init`` function just calling the
201    :c:func:`pci_register_driver()` to register the pci_driver
202    table defined above.
203
204 -  create an ``exit`` function to call the
205    :c:func:`pci_unregister_driver()` function.
206
207 Full Code Example
208 -----------------
209
210 The code example is shown below. Some parts are kept unimplemented at
211 this moment but will be filled in the next sections. The numbers in the
212 comment lines of the :c:func:`snd_mychip_probe()` function refer
213 to details explained in the following section.
214
215 ::
216
217       #include <linux/init.h>
218       #include <linux/pci.h>
219       #include <linux/slab.h>
220       #include <sound/core.h>
221       #include <sound/initval.h>
222
223       /* module parameters (see "Module Parameters") */
224       /* SNDRV_CARDS: maximum number of cards supported by this module */
225       static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
226       static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
227       static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
228
229       /* definition of the chip-specific record */
230       struct mychip {
231               struct snd_card *card;
232               /* the rest of the implementation will be in section
233                * "PCI Resource Management"
234                */
235       };
236
237       /* chip-specific destructor
238        * (see "PCI Resource Management")
239        */
240       static int snd_mychip_free(struct mychip *chip)
241       {
242               .... /* will be implemented later... */
243       }
244
245       /* component-destructor
246        * (see "Management of Cards and Components")
247        */
248       static int snd_mychip_dev_free(struct snd_device *device)
249       {
250               return snd_mychip_free(device->device_data);
251       }
252
253       /* chip-specific constructor
254        * (see "Management of Cards and Components")
255        */
256       static int snd_mychip_create(struct snd_card *card,
257                                    struct pci_dev *pci,
258                                    struct mychip **rchip)
259       {
260               struct mychip *chip;
261               int err;
262               static struct snd_device_ops ops = {
263                      .dev_free = snd_mychip_dev_free,
264               };
265
266               *rchip = NULL;
267
268               /* check PCI availability here
269                * (see "PCI Resource Management")
270                */
271               ....
272
273               /* allocate a chip-specific data with zero filled */
274               chip = kzalloc(sizeof(*chip), GFP_KERNEL);
275               if (chip == NULL)
276                       return -ENOMEM;
277
278               chip->card = card;
279
280               /* rest of initialization here; will be implemented
281                * later, see "PCI Resource Management"
282                */
283               ....
284
285               err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
286               if (err < 0) {
287                       snd_mychip_free(chip);
288                       return err;
289               }
290
291               *rchip = chip;
292               return 0;
293       }
294
295       /* constructor -- see "Driver Constructor" sub-section */
296       static int snd_mychip_probe(struct pci_dev *pci,
297                                   const struct pci_device_id *pci_id)
298       {
299               static int dev;
300               struct snd_card *card;
301               struct mychip *chip;
302               int err;
303
304               /* (1) */
305               if (dev >= SNDRV_CARDS)
306                       return -ENODEV;
307               if (!enable[dev]) {
308                       dev++;
309                       return -ENOENT;
310               }
311
312               /* (2) */
313               err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
314                                  0, &card);
315               if (err < 0)
316                       return err;
317
318               /* (3) */
319               err = snd_mychip_create(card, pci, &chip);
320               if (err < 0)
321                       goto error;
322
323               /* (4) */
324               strcpy(card->driver, "My Chip");
325               strcpy(card->shortname, "My Own Chip 123");
326               sprintf(card->longname, "%s at 0x%lx irq %i",
327                       card->shortname, chip->port, chip->irq);
328
329               /* (5) */
330               .... /* implemented later */
331
332               /* (6) */
333               err = snd_card_register(card);
334               if (err < 0)
335                       goto error;
336
337               /* (7) */
338               pci_set_drvdata(pci, card);
339               dev++;
340               return 0;
341
342       error:
343               snd_card_free(card);
344               return err;
345       }
346
347       /* destructor -- see the "Destructor" sub-section */
348       static void snd_mychip_remove(struct pci_dev *pci)
349       {
350               snd_card_free(pci_get_drvdata(pci));
351       }
352
353
354
355 Driver Constructor
356 ------------------
357
358 The real constructor of PCI drivers is the ``probe`` callback. The
359 ``probe`` callback and other component-constructors which are called
360 from the ``probe`` callback cannot be used with the ``__init`` prefix
361 because any PCI device could be a hotplug device.
362
363 In the ``probe`` callback, the following scheme is often used.
364
365 1) Check and increment the device index.
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
367
368 ::
369
370   static int dev;
371   ....
372   if (dev >= SNDRV_CARDS)
373           return -ENODEV;
374   if (!enable[dev]) {
375           dev++;
376           return -ENOENT;
377   }
378
379
380 where ``enable[dev]`` is the module option.
381
382 Each time the ``probe`` callback is called, check the availability of
383 the device. If not available, simply increment the device index and
384 returns. dev will be incremented also later (`step 7
385 <#set-the-pci-driver-data-and-return-zero>`__).
386
387 2) Create a card instance
388 ~~~~~~~~~~~~~~~~~~~~~~~~~
389
390 ::
391
392   struct snd_card *card;
393   int err;
394   ....
395   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
396                      0, &card);
397
398
399 The details will be explained in the section `Management of Cards and
400 Components`_.
401
402 3) Create a main component
403 ~~~~~~~~~~~~~~~~~~~~~~~~~~
404
405 In this part, the PCI resources are allocated.
406
407 ::
408
409   struct mychip *chip;
410   ....
411   err = snd_mychip_create(card, pci, &chip);
412   if (err < 0)
413           goto error;
414
415 The details will be explained in the section `PCI Resource
416 Management`_.
417
418 When something goes wrong, the probe function needs to deal with the
419 error.  In this example, we have a single error handling path placed
420 at the end of the function.
421
422 ::
423
424   error:
425           snd_card_free(card);
426           return err;
427
428 Since each component can be properly freed, the single
429 :c:func:`snd_card_free()` call should suffice in most cases.
430
431
432 4) Set the driver ID and name strings.
433 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
434
435 ::
436
437   strcpy(card->driver, "My Chip");
438   strcpy(card->shortname, "My Own Chip 123");
439   sprintf(card->longname, "%s at 0x%lx irq %i",
440           card->shortname, chip->port, chip->irq);
441
442 The driver field holds the minimal ID string of the chip. This is used
443 by alsa-lib's configurator, so keep it simple but unique. Even the
444 same driver can have different driver IDs to distinguish the
445 functionality of each chip type.
446
447 The shortname field is a string shown as more verbose name. The longname
448 field contains the information shown in ``/proc/asound/cards``.
449
450 5) Create other components, such as mixer, MIDI, etc.
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452
453 Here you define the basic components such as `PCM <#PCM-Interface>`__,
454 mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
455 `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
456 Also, if you want a `proc file <#Proc-Interface>`__, define it here,
457 too.
458
459 6) Register the card instance.
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461
462 ::
463
464   err = snd_card_register(card);
465   if (err < 0)
466           goto error;
467
468 Will be explained in the section `Management of Cards and
469 Components`_, too.
470
471 7) Set the PCI driver data and return zero.
472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
473
474 ::
475
476   pci_set_drvdata(pci, card);
477   dev++;
478   return 0;
479
480 In the above, the card record is stored. This pointer is used in the
481 remove callback and power-management callbacks, too.
482
483 Destructor
484 ----------
485
486 The destructor, remove callback, simply releases the card instance. Then
487 the ALSA middle layer will release all the attached components
488 automatically.
489
490 It would be typically just :c:func:`calling snd_card_free()`:
491
492 ::
493
494   static void snd_mychip_remove(struct pci_dev *pci)
495   {
496           snd_card_free(pci_get_drvdata(pci));
497   }
498
499
500 The above code assumes that the card pointer is set to the PCI driver
501 data.
502
503 Header Files
504 ------------
505
506 For the above example, at least the following include files are
507 necessary.
508
509 ::
510
511   #include <linux/init.h>
512   #include <linux/pci.h>
513   #include <linux/slab.h>
514   #include <sound/core.h>
515   #include <sound/initval.h>
516
517 where the last one is necessary only when module options are defined
518 in the source file. If the code is split into several files, the files
519 without module options don't need them.
520
521 In addition to these headers, you'll need ``<linux/interrupt.h>`` for
522 interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
523 :c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
524 to include ``<linux/delay.h>`` too.
525
526 The ALSA interfaces like the PCM and control APIs are defined in other
527 ``<sound/xxx.h>`` header files. They have to be included after
528 ``<sound/core.h>``.
529
530 Management of Cards and Components
531 ==================================
532
533 Card Instance
534 -------------
535
536 For each soundcard, a “card” record must be allocated.
537
538 A card record is the headquarters of the soundcard. It manages the whole
539 list of devices (components) on the soundcard, such as PCM, mixers,
540 MIDI, synthesizer, and so on. Also, the card record holds the ID and the
541 name strings of the card, manages the root of proc files, and controls
542 the power-management states and hotplug disconnections. The component
543 list on the card record is used to manage the correct release of
544 resources at destruction.
545
546 As mentioned above, to create a card instance, call
547 :c:func:`snd_card_new()`.
548
549 ::
550
551   struct snd_card *card;
552   int err;
553   err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
554
555
556 The function takes six arguments: the parent device pointer, the
557 card-index number, the id string, the module pointer (usually
558 ``THIS_MODULE``), the size of extra-data space, and the pointer to
559 return the card instance. The extra_size argument is used to allocate
560 card->private_data for the chip-specific data. Note that these data are
561 allocated by :c:func:`snd_card_new()`.
562
563 The first argument, the pointer of struct :c:type:`struct device
564 <device>`, specifies the parent device. For PCI devices, typically
565 ``&pci->`` is passed there.
566
567 Components
568 ----------
569
570 After the card is created, you can attach the components (devices) to
571 the card instance. In an ALSA driver, a component is represented as a
572 :c:type:`struct snd_device <snd_device>` object. A component
573 can be a PCM instance, a control interface, a raw MIDI interface, etc.
574 Each such instance has one component entry.
575
576 A component can be created via :c:func:`snd_device_new()`
577 function.
578
579 ::
580
581   snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
582
583 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
584 data pointer, and the callback pointers (``&ops``). The device-level
585 defines the type of components and the order of registration and
586 de-registration. For most components, the device-level is already
587 defined. For a user-defined component, you can use
588 ``SNDRV_DEV_LOWLEVEL``.
589
590 This function itself doesn't allocate the data space. The data must be
591 allocated manually beforehand, and its pointer is passed as the
592 argument. This pointer (``chip`` in the above example) is used as the
593 identifier for the instance.
594
595 Each pre-defined ALSA component such as ac97 and pcm calls
596 :c:func:`snd_device_new()` inside its constructor. The destructor
597 for each component is defined in the callback pointers. Hence, you don't
598 need to take care of calling a destructor for such a component.
599
600 If you wish to create your own component, you need to set the destructor
601 function to the dev_free callback in the ``ops``, so that it can be
602 released automatically via :c:func:`snd_card_free()`. The next
603 example will show an implementation of chip-specific data.
604
605 Chip-Specific Data
606 ------------------
607
608 Chip-specific information, e.g. the I/O port address, its resource
609 pointer, or the irq number, is stored in the chip-specific record.
610
611 ::
612
613   struct mychip {
614           ....
615   };
616
617
618 In general, there are two ways of allocating the chip record.
619
620 1. Allocating via :c:func:`snd_card_new()`.
621 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622
623 As mentioned above, you can pass the extra-data-length to the 5th
624 argument of :c:func:`snd_card_new()`, i.e.
625
626 ::
627
628   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
629                      sizeof(struct mychip), &card);
630
631 :c:type:`struct mychip <mychip>` is the type of the chip record.
632
633 In return, the allocated record can be accessed as
634
635 ::
636
637   struct mychip *chip = card->private_data;
638
639 With this method, you don't have to allocate twice. The record is
640 released together with the card instance.
641
642 2. Allocating an extra device.
643 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
644
645 After allocating a card instance via :c:func:`snd_card_new()`
646 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
647
648 ::
649
650   struct snd_card *card;
651   struct mychip *chip;
652   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
653                      0, &card);
654   .....
655   chip = kzalloc(sizeof(*chip), GFP_KERNEL);
656
657 The chip record should have the field to hold the card pointer at least,
658
659 ::
660
661   struct mychip {
662           struct snd_card *card;
663           ....
664   };
665
666
667 Then, set the card pointer in the returned chip instance.
668
669 ::
670
671   chip->card = card;
672
673 Next, initialize the fields, and register this chip record as a
674 low-level device with a specified ``ops``,
675
676 ::
677
678   static struct snd_device_ops ops = {
679           .dev_free =        snd_mychip_dev_free,
680   };
681   ....
682   snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
683
684 :c:func:`snd_mychip_dev_free()` is the device-destructor
685 function, which will call the real destructor.
686
687 ::
688
689   static int snd_mychip_dev_free(struct snd_device *device)
690   {
691           return snd_mychip_free(device->device_data);
692   }
693
694 where :c:func:`snd_mychip_free()` is the real destructor.
695
696 The demerit of this method is the obviously more amount of codes.
697 The merit is, however, you can trigger the own callback at registering
698 and disconnecting the card via setting in snd_device_ops.
699 About the registering and disconnecting the card, see the subsections
700 below.
701
702
703 Registration and Release
704 ------------------------
705
706 After all components are assigned, register the card instance by calling
707 :c:func:`snd_card_register()`. Access to the device files is
708 enabled at this point. That is, before
709 :c:func:`snd_card_register()` is called, the components are safely
710 inaccessible from external side. If this call fails, exit the probe
711 function after releasing the card via :c:func:`snd_card_free()`.
712
713 For releasing the card instance, you can call simply
714 :c:func:`snd_card_free()`. As mentioned earlier, all components
715 are released automatically by this call.
716
717 For a device which allows hotplugging, you can use
718 :c:func:`snd_card_free_when_closed()`. This one will postpone
719 the destruction until all devices are closed.
720
721 PCI Resource Management
722 =======================
723
724 Full Code Example
725 -----------------
726
727 In this section, we'll complete the chip-specific constructor,
728 destructor and PCI entries. Example code is shown first, below.
729
730 ::
731
732       struct mychip {
733               struct snd_card *card;
734               struct pci_dev *pci;
735
736               unsigned long port;
737               int irq;
738       };
739
740       static int snd_mychip_free(struct mychip *chip)
741       {
742               /* disable hardware here if any */
743               .... /* (not implemented in this document) */
744
745               /* release the irq */
746               if (chip->irq >= 0)
747                       free_irq(chip->irq, chip);
748               /* release the I/O ports & memory */
749               pci_release_regions(chip->pci);
750               /* disable the PCI entry */
751               pci_disable_device(chip->pci);
752               /* release the data */
753               kfree(chip);
754               return 0;
755       }
756
757       /* chip-specific constructor */
758       static int snd_mychip_create(struct snd_card *card,
759                                    struct pci_dev *pci,
760                                    struct mychip **rchip)
761       {
762               struct mychip *chip;
763               int err;
764               static struct snd_device_ops ops = {
765                      .dev_free = snd_mychip_dev_free,
766               };
767
768               *rchip = NULL;
769
770               /* initialize the PCI entry */
771               err = pci_enable_device(pci);
772               if (err < 0)
773                       return err;
774               /* check PCI availability (28bit DMA) */
775               if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
776                   pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
777                       printk(KERN_ERR "error to set 28bit mask DMA\n");
778                       pci_disable_device(pci);
779                       return -ENXIO;
780               }
781
782               chip = kzalloc(sizeof(*chip), GFP_KERNEL);
783               if (chip == NULL) {
784                       pci_disable_device(pci);
785                       return -ENOMEM;
786               }
787
788               /* initialize the stuff */
789               chip->card = card;
790               chip->pci = pci;
791               chip->irq = -1;
792
793               /* (1) PCI resource allocation */
794               err = pci_request_regions(pci, "My Chip");
795               if (err < 0) {
796                       kfree(chip);
797                       pci_disable_device(pci);
798                       return err;
799               }
800               chip->port = pci_resource_start(pci, 0);
801               if (request_irq(pci->irq, snd_mychip_interrupt,
802                               IRQF_SHARED, KBUILD_MODNAME, chip)) {
803                       printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
804                       snd_mychip_free(chip);
805                       return -EBUSY;
806               }
807               chip->irq = pci->irq;
808
809               /* (2) initialization of the chip hardware */
810               .... /*   (not implemented in this document) */
811
812               err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
813               if (err < 0) {
814                       snd_mychip_free(chip);
815                       return err;
816               }
817
818               *rchip = chip;
819               return 0;
820       }
821
822       /* PCI IDs */
823       static struct pci_device_id snd_mychip_ids[] = {
824               { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
825                 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
826               ....
827               { 0, }
828       };
829       MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
830
831       /* pci_driver definition */
832       static struct pci_driver driver = {
833               .name = KBUILD_MODNAME,
834               .id_table = snd_mychip_ids,
835               .probe = snd_mychip_probe,
836               .remove = snd_mychip_remove,
837       };
838
839       /* module initialization */
840       static int __init alsa_card_mychip_init(void)
841       {
842               return pci_register_driver(&driver);
843       }
844
845       /* module clean up */
846       static void __exit alsa_card_mychip_exit(void)
847       {
848               pci_unregister_driver(&driver);
849       }
850
851       module_init(alsa_card_mychip_init)
852       module_exit(alsa_card_mychip_exit)
853
854       EXPORT_NO_SYMBOLS; /* for old kernels only */
855
856 Some Hafta's
857 ------------
858
859 The allocation of PCI resources is done in the ``probe`` function, and
860 usually an extra :c:func:`xxx_create()` function is written for this
861 purpose.
862
863 In the case of PCI devices, you first have to call the
864 :c:func:`pci_enable_device()` function before allocating
865 resources. Also, you need to set the proper PCI DMA mask to limit the
866 accessed I/O range. In some cases, you might need to call
867 :c:func:`pci_set_master()` function, too.
868
869 Suppose the 28bit mask, and the code to be added would be like:
870
871 ::
872
873   err = pci_enable_device(pci);
874   if (err < 0)
875           return err;
876   if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
877       pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
878           printk(KERN_ERR "error to set 28bit mask DMA\n");
879           pci_disable_device(pci);
880           return -ENXIO;
881   }
882   
883
884 Resource Allocation
885 -------------------
886
887 The allocation of I/O ports and irqs is done via standard kernel
888 functions.  These resources must be released in the destructor
889 function (see below).
890
891 Now assume that the PCI device has an I/O port with 8 bytes and an
892 interrupt. Then :c:type:`struct mychip <mychip>` will have the
893 following fields:
894
895 ::
896
897   struct mychip {
898           struct snd_card *card;
899
900           unsigned long port;
901           int irq;
902   };
903
904
905 For an I/O port (and also a memory region), you need to have the
906 resource pointer for the standard resource management. For an irq, you
907 have to keep only the irq number (integer). But you need to initialize
908 this number as -1 before actual allocation, since irq 0 is valid. The
909 port address and its resource pointer can be initialized as null by
910 :c:func:`kzalloc()` automatically, so you don't have to take care of
911 resetting them.
912
913 The allocation of an I/O port is done like this:
914
915 ::
916
917   err = pci_request_regions(pci, "My Chip");
918   if (err < 0) { 
919           kfree(chip);
920           pci_disable_device(pci);
921           return err;
922   }
923   chip->port = pci_resource_start(pci, 0);
924
925 It will reserve the I/O port region of 8 bytes of the given PCI device.
926 The returned value, ``chip->res_port``, is allocated via
927 :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
928 must be released via :c:func:`kfree()`, but there is a problem with
929 this. This issue will be explained later.
930
931 The allocation of an interrupt source is done like this:
932
933 ::
934
935   if (request_irq(pci->irq, snd_mychip_interrupt,
936                   IRQF_SHARED, KBUILD_MODNAME, chip)) {
937           printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
938           snd_mychip_free(chip);
939           return -EBUSY;
940   }
941   chip->irq = pci->irq;
942
943 where :c:func:`snd_mychip_interrupt()` is the interrupt handler
944 defined `later <#pcm-interface-interrupt-handler>`__. Note that
945 ``chip->irq`` should be defined only when :c:func:`request_irq()`
946 succeeded.
947
948 On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
949 as the interrupt flag of :c:func:`request_irq()`.
950
951 The last argument of :c:func:`request_irq()` is the data pointer
952 passed to the interrupt handler. Usually, the chip-specific record is
953 used for that, but you can use what you like, too.
954
955 I won't give details about the interrupt handler at this point, but at
956 least its appearance can be explained now. The interrupt handler looks
957 usually like the following:
958
959 ::
960
961   static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
962   {
963           struct mychip *chip = dev_id;
964           ....
965           return IRQ_HANDLED;
966   }
967
968
969 Now let's write the corresponding destructor for the resources above.
970 The role of destructor is simple: disable the hardware (if already
971 activated) and release the resources. So far, we have no hardware part,
972 so the disabling code is not written here.
973
974 To release the resources, the “check-and-release” method is a safer way.
975 For the interrupt, do like this:
976
977 ::
978
979   if (chip->irq >= 0)
980           free_irq(chip->irq, chip);
981
982 Since the irq number can start from 0, you should initialize
983 ``chip->irq`` with a negative value (e.g. -1), so that you can check
984 the validity of the irq number as above.
985
986 When you requested I/O ports or memory regions via
987 :c:func:`pci_request_region()` or
988 :c:func:`pci_request_regions()` like in this example, release the
989 resource(s) using the corresponding function,
990 :c:func:`pci_release_region()` or
991 :c:func:`pci_release_regions()`.
992
993 ::
994
995   pci_release_regions(chip->pci);
996
997 When you requested manually via :c:func:`request_region()` or
998 :c:func:`request_mem_region()`, you can release it via
999 :c:func:`release_resource()`. Suppose that you keep the resource
1000 pointer returned from :c:func:`request_region()` in
1001 chip->res_port, the release procedure looks like:
1002
1003 ::
1004
1005   release_and_free_resource(chip->res_port);
1006
1007 Don't forget to call :c:func:`pci_disable_device()` before the
1008 end.
1009
1010 And finally, release the chip-specific record.
1011
1012 ::
1013
1014   kfree(chip);
1015
1016 We didn't implement the hardware disabling part in the above. If you
1017 need to do this, please note that the destructor may be called even
1018 before the initialization of the chip is completed. It would be better
1019 to have a flag to skip hardware disabling if the hardware was not
1020 initialized yet.
1021
1022 When the chip-data is assigned to the card using
1023 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1024 destructor is called at the last. That is, it is assured that all other
1025 components like PCMs and controls have already been released. You don't
1026 have to stop PCMs, etc. explicitly, but just call low-level hardware
1027 stopping.
1028
1029 The management of a memory-mapped region is almost as same as the
1030 management of an I/O port. You'll need three fields like the
1031 following:
1032
1033 ::
1034
1035   struct mychip {
1036           ....
1037           unsigned long iobase_phys;
1038           void __iomem *iobase_virt;
1039   };
1040
1041 and the allocation would be like below:
1042
1043 ::
1044
1045   err = pci_request_regions(pci, "My Chip");
1046   if (err < 0) {
1047           kfree(chip);
1048           return err;
1049   }
1050   chip->iobase_phys = pci_resource_start(pci, 0);
1051   chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
1052                                       pci_resource_len(pci, 0));
1053
1054 and the corresponding destructor would be:
1055
1056 ::
1057
1058   static int snd_mychip_free(struct mychip *chip)
1059   {
1060           ....
1061           if (chip->iobase_virt)
1062                   iounmap(chip->iobase_virt);
1063           ....
1064           pci_release_regions(chip->pci);
1065           ....
1066   }
1067
1068 Of course, a modern way with :c:func:`pci_iomap()` will make things a
1069 bit easier, too.
1070
1071 ::
1072
1073   err = pci_request_regions(pci, "My Chip");
1074   if (err < 0) {
1075           kfree(chip);
1076           return err;
1077   }
1078   chip->iobase_virt = pci_iomap(pci, 0, 0);
1079
1080 which is paired with :c:func:`pci_iounmap()` at destructor.
1081
1082
1083 PCI Entries
1084 -----------
1085
1086 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1087 :c:type:`struct pci_device_id <pci_device_id>` table for
1088 this chipset. It's a table of PCI vendor/device ID number, and some
1089 masks.
1090
1091 For example,
1092
1093 ::
1094
1095   static struct pci_device_id snd_mychip_ids[] = {
1096           { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1097             PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1098           ....
1099           { 0, }
1100   };
1101   MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1102
1103 The first and second fields of the :c:type:`struct pci_device_id
1104 <pci_device_id>` structure are the vendor and device IDs. If you
1105 have no reason to filter the matching devices, you can leave the
1106 remaining fields as above. The last field of the :c:type:`struct
1107 pci_device_id <pci_device_id>` struct contains private data
1108 for this entry. You can specify any value here, for example, to define
1109 specific operations for supported device IDs. Such an example is found
1110 in the intel8x0 driver.
1111
1112 The last entry of this list is the terminator. You must specify this
1113 all-zero entry.
1114
1115 Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1116 record:
1117
1118 ::
1119
1120   static struct pci_driver driver = {
1121           .name = KBUILD_MODNAME,
1122           .id_table = snd_mychip_ids,
1123           .probe = snd_mychip_probe,
1124           .remove = snd_mychip_remove,
1125   };
1126
1127 The ``probe`` and ``remove`` functions have already been defined in
1128 the previous sections. The ``name`` field is the name string of this
1129 device. Note that you must not use a slash “/” in this string.
1130
1131 And at last, the module entries:
1132
1133 ::
1134
1135   static int __init alsa_card_mychip_init(void)
1136   {
1137           return pci_register_driver(&driver);
1138   }
1139
1140   static void __exit alsa_card_mychip_exit(void)
1141   {
1142           pci_unregister_driver(&driver);
1143   }
1144
1145   module_init(alsa_card_mychip_init)
1146   module_exit(alsa_card_mychip_exit)
1147
1148 Note that these module entries are tagged with ``__init`` and ``__exit``
1149 prefixes.
1150
1151 That's all!
1152
1153 PCM Interface
1154 =============
1155
1156 General
1157 -------
1158
1159 The PCM middle layer of ALSA is quite powerful and it is only necessary
1160 for each driver to implement the low-level functions to access its
1161 hardware.
1162
1163 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1164 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1165 access to some functions related with hw_param.
1166
1167 Each card device can have up to four pcm instances. A pcm instance
1168 corresponds to a pcm device file. The limitation of number of instances
1169 comes only from the available bit size of the Linux's device numbers.
1170 Once when 64bit device number is used, we'll have more pcm instances
1171 available.
1172
1173 A pcm instance consists of pcm playback and capture streams, and each
1174 pcm stream consists of one or more pcm substreams. Some soundcards
1175 support multiple playback functions. For example, emu10k1 has a PCM
1176 playback of 32 stereo substreams. In this case, at each open, a free
1177 substream is (usually) automatically chosen and opened. Meanwhile, when
1178 only one substream exists and it was already opened, the successful open
1179 will either block or error with ``EAGAIN`` according to the file open
1180 mode. But you don't have to care about such details in your driver. The
1181 PCM middle layer will take care of such work.
1182
1183 Full Code Example
1184 -----------------
1185
1186 The example code below does not include any hardware access routines but
1187 shows only the skeleton, how to build up the PCM interfaces.
1188
1189 ::
1190
1191       #include <sound/pcm.h>
1192       ....
1193
1194       /* hardware definition */
1195       static struct snd_pcm_hardware snd_mychip_playback_hw = {
1196               .info = (SNDRV_PCM_INFO_MMAP |
1197                        SNDRV_PCM_INFO_INTERLEAVED |
1198                        SNDRV_PCM_INFO_BLOCK_TRANSFER |
1199                        SNDRV_PCM_INFO_MMAP_VALID),
1200               .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1201               .rates =            SNDRV_PCM_RATE_8000_48000,
1202               .rate_min =         8000,
1203               .rate_max =         48000,
1204               .channels_min =     2,
1205               .channels_max =     2,
1206               .buffer_bytes_max = 32768,
1207               .period_bytes_min = 4096,
1208               .period_bytes_max = 32768,
1209               .periods_min =      1,
1210               .periods_max =      1024,
1211       };
1212
1213       /* hardware definition */
1214       static struct snd_pcm_hardware snd_mychip_capture_hw = {
1215               .info = (SNDRV_PCM_INFO_MMAP |
1216                        SNDRV_PCM_INFO_INTERLEAVED |
1217                        SNDRV_PCM_INFO_BLOCK_TRANSFER |
1218                        SNDRV_PCM_INFO_MMAP_VALID),
1219               .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1220               .rates =            SNDRV_PCM_RATE_8000_48000,
1221               .rate_min =         8000,
1222               .rate_max =         48000,
1223               .channels_min =     2,
1224               .channels_max =     2,
1225               .buffer_bytes_max = 32768,
1226               .period_bytes_min = 4096,
1227               .period_bytes_max = 32768,
1228               .periods_min =      1,
1229               .periods_max =      1024,
1230       };
1231
1232       /* open callback */
1233       static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1234       {
1235               struct mychip *chip = snd_pcm_substream_chip(substream);
1236               struct snd_pcm_runtime *runtime = substream->runtime;
1237
1238               runtime->hw = snd_mychip_playback_hw;
1239               /* more hardware-initialization will be done here */
1240               ....
1241               return 0;
1242       }
1243
1244       /* close callback */
1245       static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1246       {
1247               struct mychip *chip = snd_pcm_substream_chip(substream);
1248               /* the hardware-specific codes will be here */
1249               ....
1250               return 0;
1251
1252       }
1253
1254       /* open callback */
1255       static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1256       {
1257               struct mychip *chip = snd_pcm_substream_chip(substream);
1258               struct snd_pcm_runtime *runtime = substream->runtime;
1259
1260               runtime->hw = snd_mychip_capture_hw;
1261               /* more hardware-initialization will be done here */
1262               ....
1263               return 0;
1264       }
1265
1266       /* close callback */
1267       static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1268       {
1269               struct mychip *chip = snd_pcm_substream_chip(substream);
1270               /* the hardware-specific codes will be here */
1271               ....
1272               return 0;
1273
1274       }
1275
1276       /* hw_params callback */
1277       static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1278                                    struct snd_pcm_hw_params *hw_params)
1279       {
1280               return snd_pcm_lib_malloc_pages(substream,
1281                                          params_buffer_bytes(hw_params));
1282       }
1283
1284       /* hw_free callback */
1285       static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1286       {
1287               return snd_pcm_lib_free_pages(substream);
1288       }
1289
1290       /* prepare callback */
1291       static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1292       {
1293               struct mychip *chip = snd_pcm_substream_chip(substream);
1294               struct snd_pcm_runtime *runtime = substream->runtime;
1295
1296               /* set up the hardware with the current configuration
1297                * for example...
1298                */
1299               mychip_set_sample_format(chip, runtime->format);
1300               mychip_set_sample_rate(chip, runtime->rate);
1301               mychip_set_channels(chip, runtime->channels);
1302               mychip_set_dma_setup(chip, runtime->dma_addr,
1303                                    chip->buffer_size,
1304                                    chip->period_size);
1305               return 0;
1306       }
1307
1308       /* trigger callback */
1309       static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1310                                         int cmd)
1311       {
1312               switch (cmd) {
1313               case SNDRV_PCM_TRIGGER_START:
1314                       /* do something to start the PCM engine */
1315                       ....
1316                       break;
1317               case SNDRV_PCM_TRIGGER_STOP:
1318                       /* do something to stop the PCM engine */
1319                       ....
1320                       break;
1321               default:
1322                       return -EINVAL;
1323               }
1324       }
1325
1326       /* pointer callback */
1327       static snd_pcm_uframes_t
1328       snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1329       {
1330               struct mychip *chip = snd_pcm_substream_chip(substream);
1331               unsigned int current_ptr;
1332
1333               /* get the current hardware pointer */
1334               current_ptr = mychip_get_hw_pointer(chip);
1335               return current_ptr;
1336       }
1337
1338       /* operators */
1339       static struct snd_pcm_ops snd_mychip_playback_ops = {
1340               .open =        snd_mychip_playback_open,
1341               .close =       snd_mychip_playback_close,
1342               .ioctl =       snd_pcm_lib_ioctl,
1343               .hw_params =   snd_mychip_pcm_hw_params,
1344               .hw_free =     snd_mychip_pcm_hw_free,
1345               .prepare =     snd_mychip_pcm_prepare,
1346               .trigger =     snd_mychip_pcm_trigger,
1347               .pointer =     snd_mychip_pcm_pointer,
1348       };
1349
1350       /* operators */
1351       static struct snd_pcm_ops snd_mychip_capture_ops = {
1352               .open =        snd_mychip_capture_open,
1353               .close =       snd_mychip_capture_close,
1354               .ioctl =       snd_pcm_lib_ioctl,
1355               .hw_params =   snd_mychip_pcm_hw_params,
1356               .hw_free =     snd_mychip_pcm_hw_free,
1357               .prepare =     snd_mychip_pcm_prepare,
1358               .trigger =     snd_mychip_pcm_trigger,
1359               .pointer =     snd_mychip_pcm_pointer,
1360       };
1361
1362       /*
1363        *  definitions of capture are omitted here...
1364        */
1365
1366       /* create a pcm device */
1367       static int snd_mychip_new_pcm(struct mychip *chip)
1368       {
1369               struct snd_pcm *pcm;
1370               int err;
1371
1372               err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1373               if (err < 0)
1374                       return err;
1375               pcm->private_data = chip;
1376               strcpy(pcm->name, "My Chip");
1377               chip->pcm = pcm;
1378               /* set operators */
1379               snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1380                               &snd_mychip_playback_ops);
1381               snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1382                               &snd_mychip_capture_ops);
1383               /* pre-allocation of buffers */
1384               /* NOTE: this may fail */
1385               snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1386                                                     snd_dma_pci_data(chip->pci),
1387                                                     64*1024, 64*1024);
1388               return 0;
1389       }
1390
1391
1392 PCM Constructor
1393 ---------------
1394
1395 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1396 function. It would be better to create a constructor for pcm, namely,
1397
1398 ::
1399
1400   static int snd_mychip_new_pcm(struct mychip *chip)
1401   {
1402           struct snd_pcm *pcm;
1403           int err;
1404
1405           err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1406           if (err < 0) 
1407                   return err;
1408           pcm->private_data = chip;
1409           strcpy(pcm->name, "My Chip");
1410           chip->pcm = pcm;
1411           ....
1412           return 0;
1413   }
1414
1415 The :c:func:`snd_pcm_new()` function takes four arguments. The
1416 first argument is the card pointer to which this pcm is assigned, and
1417 the second is the ID string.
1418
1419 The third argument (``index``, 0 in the above) is the index of this new
1420 pcm. It begins from zero. If you create more than one pcm instances,
1421 specify the different numbers in this argument. For example, ``index =
1422 1`` for the second PCM device.
1423
1424 The fourth and fifth arguments are the number of substreams for playback
1425 and capture, respectively. Here 1 is used for both arguments. When no
1426 playback or capture substreams are available, pass 0 to the
1427 corresponding argument.
1428
1429 If a chip supports multiple playbacks or captures, you can specify more
1430 numbers, but they must be handled properly in open/close, etc.
1431 callbacks. When you need to know which substream you are referring to,
1432 then it can be obtained from :c:type:`struct snd_pcm_substream
1433 <snd_pcm_substream>` data passed to each callback as follows:
1434
1435 ::
1436
1437   struct snd_pcm_substream *substream;
1438   int index = substream->number;
1439
1440
1441 After the pcm is created, you need to set operators for each pcm stream.
1442
1443 ::
1444
1445   snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1446                   &snd_mychip_playback_ops);
1447   snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1448                   &snd_mychip_capture_ops);
1449
1450 The operators are defined typically like this:
1451
1452 ::
1453
1454   static struct snd_pcm_ops snd_mychip_playback_ops = {
1455           .open =        snd_mychip_pcm_open,
1456           .close =       snd_mychip_pcm_close,
1457           .ioctl =       snd_pcm_lib_ioctl,
1458           .hw_params =   snd_mychip_pcm_hw_params,
1459           .hw_free =     snd_mychip_pcm_hw_free,
1460           .prepare =     snd_mychip_pcm_prepare,
1461           .trigger =     snd_mychip_pcm_trigger,
1462           .pointer =     snd_mychip_pcm_pointer,
1463   };
1464
1465 All the callbacks are described in the Operators_ subsection.
1466
1467 After setting the operators, you probably will want to pre-allocate the
1468 buffer. For the pre-allocation, simply call the following:
1469
1470 ::
1471
1472   snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
1473                                         snd_dma_pci_data(chip->pci),
1474                                         64*1024, 64*1024);
1475
1476 It will allocate a buffer up to 64kB as default. Buffer management
1477 details will be described in the later section `Buffer and Memory
1478 Management`_.
1479
1480 Additionally, you can set some extra information for this pcm in
1481 ``pcm->info_flags``. The available values are defined as
1482 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1483 hardware definition (described later). When your soundchip supports only
1484 half-duplex, specify like this:
1485
1486 ::
1487
1488   pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1489
1490
1491 ... And the Destructor?
1492 -----------------------
1493
1494 The destructor for a pcm instance is not always necessary. Since the pcm
1495 device will be released by the middle layer code automatically, you
1496 don't have to call the destructor explicitly.
1497
1498 The destructor would be necessary if you created special records
1499 internally and needed to release them. In such a case, set the
1500 destructor function to ``pcm->private_free``:
1501
1502 ::
1503
1504       static void mychip_pcm_free(struct snd_pcm *pcm)
1505       {
1506               struct mychip *chip = snd_pcm_chip(pcm);
1507               /* free your own data */
1508               kfree(chip->my_private_pcm_data);
1509               /* do what you like else */
1510               ....
1511       }
1512
1513       static int snd_mychip_new_pcm(struct mychip *chip)
1514       {
1515               struct snd_pcm *pcm;
1516               ....
1517               /* allocate your own data */
1518               chip->my_private_pcm_data = kmalloc(...);
1519               /* set the destructor */
1520               pcm->private_data = chip;
1521               pcm->private_free = mychip_pcm_free;
1522               ....
1523       }
1524
1525
1526
1527 Runtime Pointer - The Chest of PCM Information
1528 ----------------------------------------------
1529
1530 When the PCM substream is opened, a PCM runtime instance is allocated
1531 and assigned to the substream. This pointer is accessible via
1532 ``substream->runtime``. This runtime pointer holds most information you
1533 need to control the PCM: the copy of hw_params and sw_params
1534 configurations, the buffer pointers, mmap records, spinlocks, etc.
1535
1536 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1537 are the contents of this file:
1538
1539 ::
1540
1541   struct _snd_pcm_runtime {
1542           /* -- Status -- */
1543           struct snd_pcm_substream *trigger_master;
1544           snd_timestamp_t trigger_tstamp;       /* trigger timestamp */
1545           int overrange;
1546           snd_pcm_uframes_t avail_max;
1547           snd_pcm_uframes_t hw_ptr_base;        /* Position at buffer restart */
1548           snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1549   
1550           /* -- HW params -- */
1551           snd_pcm_access_t access;      /* access mode */
1552           snd_pcm_format_t format;      /* SNDRV_PCM_FORMAT_* */
1553           snd_pcm_subformat_t subformat;        /* subformat */
1554           unsigned int rate;            /* rate in Hz */
1555           unsigned int channels;                /* channels */
1556           snd_pcm_uframes_t period_size;        /* period size */
1557           unsigned int periods;         /* periods */
1558           snd_pcm_uframes_t buffer_size;        /* buffer size */
1559           unsigned int tick_time;               /* tick time */
1560           snd_pcm_uframes_t min_align;  /* Min alignment for the format */
1561           size_t byte_align;
1562           unsigned int frame_bits;
1563           unsigned int sample_bits;
1564           unsigned int info;
1565           unsigned int rate_num;
1566           unsigned int rate_den;
1567   
1568           /* -- SW params -- */
1569           struct timespec tstamp_mode;  /* mmap timestamp is updated */
1570           unsigned int period_step;
1571           unsigned int sleep_min;               /* min ticks to sleep */
1572           snd_pcm_uframes_t start_threshold;
1573           snd_pcm_uframes_t stop_threshold;
1574           snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1575                                                   noise is nearest than this */
1576           snd_pcm_uframes_t silence_size;       /* Silence filling size */
1577           snd_pcm_uframes_t boundary;   /* pointers wrap point */
1578   
1579           snd_pcm_uframes_t silenced_start;
1580           snd_pcm_uframes_t silenced_size;
1581   
1582           snd_pcm_sync_id_t sync;               /* hardware synchronization ID */
1583   
1584           /* -- mmap -- */
1585           volatile struct snd_pcm_mmap_status *status;
1586           volatile struct snd_pcm_mmap_control *control;
1587           atomic_t mmap_count;
1588   
1589           /* -- locking / scheduling -- */
1590           spinlock_t lock;
1591           wait_queue_head_t sleep;
1592           struct timer_list tick_timer;
1593           struct fasync_struct *fasync;
1594
1595           /* -- private section -- */
1596           void *private_data;
1597           void (*private_free)(struct snd_pcm_runtime *runtime);
1598   
1599           /* -- hardware description -- */
1600           struct snd_pcm_hardware hw;
1601           struct snd_pcm_hw_constraints hw_constraints;
1602   
1603           /* -- timer -- */
1604           unsigned int timer_resolution;        /* timer resolution */
1605   
1606           /* -- DMA -- */           
1607           unsigned char *dma_area;      /* DMA area */
1608           dma_addr_t dma_addr;          /* physical bus address (not accessible from main CPU) */
1609           size_t dma_bytes;             /* size of DMA area */
1610   
1611           struct snd_dma_buffer *dma_buffer_p;  /* allocated buffer */
1612   
1613   #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1614           /* -- OSS things -- */
1615           struct snd_pcm_oss_runtime oss;
1616   #endif
1617   };
1618
1619
1620 For the operators (callbacks) of each sound driver, most of these
1621 records are supposed to be read-only. Only the PCM middle-layer changes
1622 / updates them. The exceptions are the hardware description (hw) DMA
1623 buffer information and the private data. Besides, if you use the
1624 standard buffer allocation method via
1625 :c:func:`snd_pcm_lib_malloc_pages()`, you don't need to set the
1626 DMA buffer information by yourself.
1627
1628 In the sections below, important records are explained.
1629
1630 Hardware Description
1631 ~~~~~~~~~~~~~~~~~~~~
1632
1633 The hardware descriptor (:c:type:`struct snd_pcm_hardware
1634 <snd_pcm_hardware>`) contains the definitions of the fundamental
1635 hardware configuration. Above all, you'll need to define this in the
1636 `PCM open callback`_. Note that the runtime instance holds the copy of
1637 the descriptor, not the pointer to the existing descriptor. That is,
1638 in the open callback, you can modify the copied descriptor
1639 (``runtime->hw``) as you need. For example, if the maximum number of
1640 channels is 1 only on some chip models, you can still use the same
1641 hardware descriptor and change the channels_max later:
1642
1643 ::
1644
1645           struct snd_pcm_runtime *runtime = substream->runtime;
1646           ...
1647           runtime->hw = snd_mychip_playback_hw; /* common definition */
1648           if (chip->model == VERY_OLD_ONE)
1649                   runtime->hw.channels_max = 1;
1650
1651 Typically, you'll have a hardware descriptor as below:
1652
1653 ::
1654
1655   static struct snd_pcm_hardware snd_mychip_playback_hw = {
1656           .info = (SNDRV_PCM_INFO_MMAP |
1657                    SNDRV_PCM_INFO_INTERLEAVED |
1658                    SNDRV_PCM_INFO_BLOCK_TRANSFER |
1659                    SNDRV_PCM_INFO_MMAP_VALID),
1660           .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1661           .rates =            SNDRV_PCM_RATE_8000_48000,
1662           .rate_min =         8000,
1663           .rate_max =         48000,
1664           .channels_min =     2,
1665           .channels_max =     2,
1666           .buffer_bytes_max = 32768,
1667           .period_bytes_min = 4096,
1668           .period_bytes_max = 32768,
1669           .periods_min =      1,
1670           .periods_max =      1024,
1671   };
1672
1673 -  The ``info`` field contains the type and capabilities of this
1674    pcm. The bit flags are defined in ``<sound/asound.h>`` as
1675    ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1676    the mmap is supported and which interleaved format is
1677    supported. When the hardware supports mmap, add the
1678    ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1679    interleaved or the non-interleaved formats,
1680    ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1681    flag must be set, respectively. If both are supported, you can set
1682    both, too.
1683
1684    In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1685    specified for the OSS mmap mode. Usually both are set. Of course,
1686    ``MMAP_VALID`` is set only if the mmap is really supported.
1687
1688    The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1689    ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1690    supports the “pause” operation, while the ``RESUME`` bit means that
1691    the pcm supports the full “suspend/resume” operation. If the
1692    ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1693    the corresponding (pause push/release) commands. The suspend/resume
1694    trigger commands can be defined even without the ``RESUME``
1695    flag. See `Power Management`_ section for details.
1696
1697    When the PCM substreams can be synchronized (typically,
1698    synchronized start/stop of a playback and a capture streams), you
1699    can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1700    need to check the linked-list of PCM substreams in the trigger
1701    callback. This will be described in the later section.
1702
1703 -  ``formats`` field contains the bit-flags of supported formats
1704    (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1705    format, give all or'ed bits. In the example above, the signed 16bit
1706    little-endian format is specified.
1707
1708 -  ``rates`` field contains the bit-flags of supported rates
1709    (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1710    pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1711    provided only for typical rates. If your chip supports
1712    unconventional rates, you need to add the ``KNOT`` bit and set up
1713    the hardware constraint manually (explained later).
1714
1715 -  ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1716    rate. This should correspond somehow to ``rates`` bits.
1717
1718 -  ``channel_min`` and ``channel_max`` define, as you might already
1719    expected, the minimum and maximum number of channels.
1720
1721 -  ``buffer_bytes_max`` defines the maximum buffer size in
1722    bytes. There is no ``buffer_bytes_min`` field, since it can be
1723    calculated from the minimum period size and the minimum number of
1724    periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1725    maximum size of the period in bytes. ``periods_max`` and
1726    ``periods_min`` define the maximum and minimum number of periods in
1727    the buffer.
1728
1729    The “period” is a term that corresponds to a fragment in the OSS
1730    world. The period defines the size at which a PCM interrupt is
1731    generated. This size strongly depends on the hardware. Generally,
1732    the smaller period size will give you more interrupts, that is,
1733    more controls. In the case of capture, this size defines the input
1734    latency. On the other hand, the whole buffer size defines the
1735    output latency for the playback direction.
1736
1737 -  There is also a field ``fifo_size``. This specifies the size of the
1738    hardware FIFO, but currently it is neither used in the driver nor
1739    in the alsa-lib. So, you can ignore this field.
1740
1741 PCM Configurations
1742 ~~~~~~~~~~~~~~~~~~
1743
1744 Ok, let's go back again to the PCM runtime records. The most
1745 frequently referred records in the runtime instance are the PCM
1746 configurations. The PCM configurations are stored in the runtime
1747 instance after the application sends ``hw_params`` data via
1748 alsa-lib. There are many fields copied from hw_params and sw_params
1749 structs. For example, ``format`` holds the format type chosen by the
1750 application. This field contains the enum value
1751 ``SNDRV_PCM_FORMAT_XXX``.
1752
1753 One thing to be noted is that the configured buffer and period sizes
1754 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1755 channels \* samples-size``. For conversion between frames and bytes,
1756 you can use the :c:func:`frames_to_bytes()` and
1757 :c:func:`bytes_to_frames()` helper functions.
1758
1759 ::
1760
1761   period_bytes = frames_to_bytes(runtime, runtime->period_size);
1762
1763 Also, many software parameters (sw_params) are stored in frames, too.
1764 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1765 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1766 frames as signed integer.
1767
1768 DMA Buffer Information
1769 ~~~~~~~~~~~~~~~~~~~~~~
1770
1771 The DMA buffer is defined by the following four fields, ``dma_area``,
1772 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1773 holds the buffer pointer (the logical address). You can call
1774 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1775 the physical address of the buffer. This field is specified only when
1776 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1777 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1778
1779 If you use a standard ALSA function,
1780 :c:func:`snd_pcm_lib_malloc_pages()`, for allocating the buffer,
1781 these fields are set by the ALSA middle layer, and you should *not*
1782 change them by yourself. You can read them but not write them. On the
1783 other hand, if you want to allocate the buffer by yourself, you'll
1784 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1785 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1786 your driver doesn't support mmap, this field is not
1787 necessary. ``dma_addr`` is also optional. You can use dma_private as
1788 you like, too.
1789
1790 Running Status
1791 ~~~~~~~~~~~~~~
1792
1793 The running status can be referred via ``runtime->status``. This is
1794 the pointer to the :c:type:`struct snd_pcm_mmap_status
1795 <snd_pcm_mmap_status>` record. For example, you can get the current
1796 DMA hardware pointer via ``runtime->status->hw_ptr``.
1797
1798 The DMA application pointer can be referred via ``runtime->control``,
1799 which points to the :c:type:`struct snd_pcm_mmap_control
1800 <snd_pcm_mmap_control>` record. However, accessing directly to
1801 this value is not recommended.
1802
1803 Private Data
1804 ~~~~~~~~~~~~
1805
1806 You can allocate a record for the substream and store it in
1807 ``runtime->private_data``. Usually, this is done in the `PCM open
1808 callback`_. Don't mix this with ``pcm->private_data``. The
1809 ``pcm->private_data`` usually points to the chip instance assigned
1810 statically at the creation of PCM, while the ``runtime->private_data``
1811 points to a dynamic data structure created at the PCM open
1812 callback.
1813
1814 ::
1815
1816   static int snd_xxx_open(struct snd_pcm_substream *substream)
1817   {
1818           struct my_pcm_data *data;
1819           ....
1820           data = kmalloc(sizeof(*data), GFP_KERNEL);
1821           substream->runtime->private_data = data;
1822           ....
1823   }
1824
1825
1826 The allocated object must be released in the `close callback`_.
1827
1828 Operators
1829 ---------
1830
1831 OK, now let me give details about each pcm callback (``ops``). In
1832 general, every callback must return 0 if successful, or a negative
1833 error number such as ``-EINVAL``. To choose an appropriate error
1834 number, it is advised to check what value other parts of the kernel
1835 return when the same kind of request fails.
1836
1837 The callback function takes at least the argument with :c:type:`struct
1838 snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1839 record from the given substream instance, you can use the following
1840 macro.
1841
1842 ::
1843
1844   int xxx() {
1845           struct mychip *chip = snd_pcm_substream_chip(substream);
1846           ....
1847   }
1848
1849 The macro reads ``substream->private_data``, which is a copy of
1850 ``pcm->private_data``. You can override the former if you need to
1851 assign different data records per PCM substream. For example, the
1852 cmi8330 driver assigns different ``private_data`` for playback and
1853 capture directions, because it uses two different codecs (SB- and
1854 AD-compatible) for different directions.
1855
1856 PCM open callback
1857 ~~~~~~~~~~~~~~~~~
1858
1859 ::
1860
1861   static int snd_xxx_open(struct snd_pcm_substream *substream);
1862
1863 This is called when a pcm substream is opened.
1864
1865 At least, here you have to initialize the ``runtime->hw``
1866 record. Typically, this is done by like this:
1867
1868 ::
1869
1870   static int snd_xxx_open(struct snd_pcm_substream *substream)
1871   {
1872           struct mychip *chip = snd_pcm_substream_chip(substream);
1873           struct snd_pcm_runtime *runtime = substream->runtime;
1874
1875           runtime->hw = snd_mychip_playback_hw;
1876           return 0;
1877   }
1878
1879 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1880 description.
1881
1882 You can allocate a private data in this callback, as described in
1883 `Private Data`_ section.
1884
1885 If the hardware configuration needs more constraints, set the hardware
1886 constraints here, too. See Constraints_ for more details.
1887
1888 close callback
1889 ~~~~~~~~~~~~~~
1890
1891 ::
1892
1893   static int snd_xxx_close(struct snd_pcm_substream *substream);
1894
1895
1896 Obviously, this is called when a pcm substream is closed.
1897
1898 Any private instance for a pcm substream allocated in the ``open``
1899 callback will be released here.
1900
1901 ::
1902
1903   static int snd_xxx_close(struct snd_pcm_substream *substream)
1904   {
1905           ....
1906           kfree(substream->runtime->private_data);
1907           ....
1908   }
1909
1910 ioctl callback
1911 ~~~~~~~~~~~~~~
1912
1913 This is used for any special call to pcm ioctls. But usually you can
1914 pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`.
1915
1916 hw_params callback
1917 ~~~~~~~~~~~~~~~~~~~
1918
1919 ::
1920
1921   static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1922                                struct snd_pcm_hw_params *hw_params);
1923
1924 This is called when the hardware parameter (``hw_params``) is set up
1925 by the application, that is, once when the buffer size, the period
1926 size, the format, etc. are defined for the pcm substream.
1927
1928 Many hardware setups should be done in this callback, including the
1929 allocation of buffers.
1930
1931 Parameters to be initialized are retrieved by
1932 :c:func:`params_xxx()` macros. To allocate buffer, you can call a
1933 helper function,
1934
1935 ::
1936
1937   snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1938
1939 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1940 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1941 for more details.
1942
1943 Note that this and ``prepare`` callbacks may be called multiple times
1944 per initialization. For example, the OSS emulation may call these
1945 callbacks at each change via its ioctl.
1946
1947 Thus, you need to be careful not to allocate the same buffers many
1948 times, which will lead to memory leaks! Calling the helper function
1949 above many times is OK. It will release the previous buffer
1950 automatically when it was already allocated.
1951
1952 Another note is that this callback is non-atomic (schedulable) as
1953 default, i.e. when no ``nonatomic`` flag set. This is important,
1954 because the ``trigger`` callback is atomic (non-schedulable). That is,
1955 mutexes or any schedule-related functions are not available in
1956 ``trigger`` callback. Please see the subsection Atomicity_ for
1957 details.
1958
1959 hw_free callback
1960 ~~~~~~~~~~~~~~~~~
1961
1962 ::
1963
1964   static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1965
1966 This is called to release the resources allocated via
1967 ``hw_params``. For example, releasing the buffer via
1968 :c:func:`snd_pcm_lib_malloc_pages()` is done by calling the
1969 following:
1970
1971 ::
1972
1973   snd_pcm_lib_free_pages(substream);
1974
1975 This function is always called before the close callback is called.
1976 Also, the callback may be called multiple times, too. Keep track
1977 whether the resource was already released.
1978
1979 prepare callback
1980 ~~~~~~~~~~~~~~~~
1981
1982 ::
1983
1984   static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1985
1986 This callback is called when the pcm is “prepared”. You can set the
1987 format type, sample rate, etc. here. The difference from ``hw_params``
1988 is that the ``prepare`` callback will be called each time
1989 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
1990 underruns, etc.
1991
1992 Note that this callback is now non-atomic. You can use
1993 schedule-related functions safely in this callback.
1994
1995 In this and the following callbacks, you can refer to the values via
1996 the runtime record, ``substream->runtime``. For example, to get the
1997 current rate, format or channels, access to ``runtime->rate``,
1998 ``runtime->format`` or ``runtime->channels``, respectively. The
1999 physical address of the allocated buffer is set to
2000 ``runtime->dma_area``. The buffer and period sizes are in
2001 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2002
2003 Be careful that this callback will be called many times at each setup,
2004 too.
2005
2006 trigger callback
2007 ~~~~~~~~~~~~~~~~
2008
2009 ::
2010
2011   static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2012
2013 This is called when the pcm is started, stopped or paused.
2014
2015 Which action is specified in the second argument,
2016 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2017 and ``STOP`` commands must be defined in this callback.
2018
2019 ::
2020
2021   switch (cmd) {
2022   case SNDRV_PCM_TRIGGER_START:
2023           /* do something to start the PCM engine */
2024           break;
2025   case SNDRV_PCM_TRIGGER_STOP:
2026           /* do something to stop the PCM engine */
2027           break;
2028   default:
2029           return -EINVAL;
2030   }
2031
2032 When the pcm supports the pause operation (given in the info field of
2033 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2034 must be handled here, too. The former is the command to pause the pcm,
2035 and the latter to restart the pcm again.
2036
2037 When the pcm supports the suspend/resume operation, regardless of full
2038 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2039 commands must be handled, too. These commands are issued when the
2040 power-management status is changed. Obviously, the ``SUSPEND`` and
2041 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2042 they are identical to the ``STOP`` and ``START`` commands, respectively.
2043 See the `Power Management`_ section for details.
2044
2045 As mentioned, this callback is atomic as default unless ``nonatomic``
2046 flag set, and you cannot call functions which may sleep. The
2047 ``trigger`` callback should be as minimal as possible, just really
2048 triggering the DMA. The other stuff should be initialized
2049 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2050
2051 pointer callback
2052 ~~~~~~~~~~~~~~~~
2053
2054 ::
2055
2056   static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2057
2058 This callback is called when the PCM middle layer inquires the current
2059 hardware position on the buffer. The position must be returned in
2060 frames, ranging from 0 to ``buffer_size - 1``. 
2061
2062 This is called usually from the buffer-update routine in the pcm
2063 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2064 is called in the interrupt routine. Then the pcm middle layer updates
2065 the position and calculates the available space, and wakes up the
2066 sleeping poll threads, etc.
2067
2068 This callback is also atomic as default.
2069
2070 copy_user, copy_kernel and fill_silence ops
2071 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2072
2073 These callbacks are not mandatory, and can be omitted in most cases.
2074 These callbacks are used when the hardware buffer cannot be in the
2075 normal memory space. Some chips have their own buffer on the hardware
2076 which is not mappable. In such a case, you have to transfer the data
2077 manually from the memory buffer to the hardware buffer. Or, if the
2078 buffer is non-contiguous on both physical and virtual memory spaces,
2079 these callbacks must be defined, too.
2080
2081 If these two callbacks are defined, copy and set-silence operations
2082 are done by them. The detailed will be described in the later section
2083 `Buffer and Memory Management`_.
2084
2085 ack callback
2086 ~~~~~~~~~~~~
2087
2088 This callback is also not mandatory. This callback is called when the
2089 ``appl_ptr`` is updated in read or write operations. Some drivers like
2090 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2091 internal buffer, and this callback is useful only for such a purpose.
2092
2093 This callback is atomic as default.
2094
2095 page callback
2096 ~~~~~~~~~~~~~
2097
2098 This callback is optional too. This callback is used mainly for
2099 non-contiguous buffers. The mmap calls this callback to get the page
2100 address. Some examples will be explained in the later section `Buffer
2101 and Memory Management`_, too.
2102
2103 mmap calllback
2104 ~~~~~~~~~~~~~~
2105
2106 This is another optional callback for controlling mmap behavior.
2107 Once when defined, PCM core calls this callback when a page is
2108 memory-mapped instead of dealing via the standard helper.
2109 If you need special handling (due to some architecture or
2110 device-specific issues), implement everything here as you like.
2111
2112
2113 PCM Interrupt Handler
2114 ---------------------
2115
2116 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2117 interrupt handler in the sound driver is to update the buffer position
2118 and to tell the PCM middle layer when the buffer position goes across
2119 the prescribed period size. To inform this, call the
2120 :c:func:`snd_pcm_period_elapsed()` function.
2121
2122 There are several types of sound chips to generate the interrupts.
2123
2124 Interrupts at the period (fragment) boundary
2125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2126
2127 This is the most frequently found type: the hardware generates an
2128 interrupt at each period boundary. In this case, you can call
2129 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2130
2131 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2132 its argument. Thus, you need to keep the substream pointer accessible
2133 from the chip instance. For example, define ``substream`` field in the
2134 chip record to hold the current running substream pointer, and set the
2135 pointer value at ``open`` callback (and reset at ``close`` callback).
2136
2137 If you acquire a spinlock in the interrupt handler, and the lock is used
2138 in other pcm callbacks, too, then you have to release the lock before
2139 calling :c:func:`snd_pcm_period_elapsed()`, because
2140 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2141 inside.
2142
2143 Typical code would be like:
2144
2145 ::
2146
2147
2148       static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2149       {
2150               struct mychip *chip = dev_id;
2151               spin_lock(&chip->lock);
2152               ....
2153               if (pcm_irq_invoked(chip)) {
2154                       /* call updater, unlock before it */
2155                       spin_unlock(&chip->lock);
2156                       snd_pcm_period_elapsed(chip->substream);
2157                       spin_lock(&chip->lock);
2158                       /* acknowledge the interrupt if necessary */
2159               }
2160               ....
2161               spin_unlock(&chip->lock);
2162               return IRQ_HANDLED;
2163       }
2164
2165
2166
2167 High frequency timer interrupts
2168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2169
2170 This happens when the hardware doesn't generate interrupts at the period
2171 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2172 or ymfpci drivers). In this case, you need to check the current hardware
2173 position and accumulate the processed sample length at each interrupt.
2174 When the accumulated size exceeds the period size, call
2175 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2176
2177 Typical code would be like the following.
2178
2179 ::
2180
2181
2182       static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2183       {
2184               struct mychip *chip = dev_id;
2185               spin_lock(&chip->lock);
2186               ....
2187               if (pcm_irq_invoked(chip)) {
2188                       unsigned int last_ptr, size;
2189                       /* get the current hardware pointer (in frames) */
2190                       last_ptr = get_hw_ptr(chip);
2191                       /* calculate the processed frames since the
2192                        * last update
2193                        */
2194                       if (last_ptr < chip->last_ptr)
2195                               size = runtime->buffer_size + last_ptr
2196                                        - chip->last_ptr;
2197                       else
2198                               size = last_ptr - chip->last_ptr;
2199                       /* remember the last updated point */
2200                       chip->last_ptr = last_ptr;
2201                       /* accumulate the size */
2202                       chip->size += size;
2203                       /* over the period boundary? */
2204                       if (chip->size >= runtime->period_size) {
2205                               /* reset the accumulator */
2206                               chip->size %= runtime->period_size;
2207                               /* call updater */
2208                               spin_unlock(&chip->lock);
2209                               snd_pcm_period_elapsed(substream);
2210                               spin_lock(&chip->lock);
2211                       }
2212                       /* acknowledge the interrupt if necessary */
2213               }
2214               ....
2215               spin_unlock(&chip->lock);
2216               return IRQ_HANDLED;
2217       }
2218
2219
2220
2221 On calling :c:func:`snd_pcm_period_elapsed()`
2222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2223
2224 In both cases, even if more than one period are elapsed, you don't have
2225 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2226 once. And the pcm layer will check the current hardware pointer and
2227 update to the latest status.
2228
2229 Atomicity
2230 ---------
2231
2232 One of the most important (and thus difficult to debug) problems in
2233 kernel programming are race conditions. In the Linux kernel, they are
2234 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2235 race condition can happen in an interrupt handler, it has to be managed
2236 atomically, and you have to use a spinlock to protect the critical
2237 session. If the critical section is not in interrupt handler code and if
2238 taking a relatively long time to execute is acceptable, you should use
2239 mutexes or semaphores instead.
2240
2241 As already seen, some pcm callbacks are atomic and some are not. For
2242 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2243 callback is atomic. This means, the latter is called already in a
2244 spinlock held by the PCM middle layer. Please take this atomicity into
2245 account when you choose a locking scheme in the callbacks.
2246
2247 In the atomic callbacks, you cannot use functions which may call
2248 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2249 mutexes can sleep, and hence they cannot be used inside the atomic
2250 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2251 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2252
2253 All three atomic callbacks (trigger, pointer, and ack) are called with
2254 local interrupts disabled.
2255
2256 The recent changes in PCM core code, however, allow all PCM operations
2257 to be non-atomic. This assumes that the all caller sides are in
2258 non-atomic contexts. For example, the function
2259 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2260 interrupt handler. But, if you set up the driver to use a threaded
2261 interrupt handler, this call can be in non-atomic context, too. In such
2262 a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm
2263 <snd_pcm>` object after creating it. When this flag is set, mutex
2264 and rwsem are used internally in the PCM core instead of spin and
2265 rwlocks, so that you can call all PCM functions safely in a non-atomic
2266 context.
2267
2268 Constraints
2269 -----------
2270
2271 If your chip supports unconventional sample rates, or only the limited
2272 samples, you need to set a constraint for the condition.
2273
2274 For example, in order to restrict the sample rates in the some supported
2275 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2276 call this function in the open callback.
2277
2278 ::
2279
2280       static unsigned int rates[] =
2281               {4000, 10000, 22050, 44100};
2282       static struct snd_pcm_hw_constraint_list constraints_rates = {
2283               .count = ARRAY_SIZE(rates),
2284               .list = rates,
2285               .mask = 0,
2286       };
2287
2288       static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2289       {
2290               int err;
2291               ....
2292               err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2293                                                SNDRV_PCM_HW_PARAM_RATE,
2294                                                &constraints_rates);
2295               if (err < 0)
2296                       return err;
2297               ....
2298       }
2299
2300
2301
2302 There are many different constraints. Look at ``sound/pcm.h`` for a
2303 complete list. You can even define your own constraint rules. For
2304 example, let's suppose my_chip can manage a substream of 1 channel if
2305 and only if the format is ``S16_LE``, otherwise it supports any format
2306 specified in the :c:type:`struct snd_pcm_hardware
2307 <snd_pcm_hardware>` structure (or in any other
2308 constraint_list). You can build a rule like this:
2309
2310 ::
2311
2312       static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2313                                             struct snd_pcm_hw_rule *rule)
2314       {
2315               struct snd_interval *c = hw_param_interval(params,
2316                             SNDRV_PCM_HW_PARAM_CHANNELS);
2317               struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2318               struct snd_interval ch;
2319
2320               snd_interval_any(&ch);
2321               if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2322                       ch.min = ch.max = 1;
2323                       ch.integer = 1;
2324                       return snd_interval_refine(c, &ch);
2325               }
2326               return 0;
2327       }
2328
2329
2330 Then you need to call this function to add your rule:
2331
2332 ::
2333
2334   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2335                       hw_rule_channels_by_format, NULL,
2336                       SNDRV_PCM_HW_PARAM_FORMAT, -1);
2337
2338 The rule function is called when an application sets the PCM format, and
2339 it refines the number of channels accordingly. But an application may
2340 set the number of channels before setting the format. Thus you also need
2341 to define the inverse rule:
2342
2343 ::
2344
2345       static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2346                                             struct snd_pcm_hw_rule *rule)
2347       {
2348               struct snd_interval *c = hw_param_interval(params,
2349                     SNDRV_PCM_HW_PARAM_CHANNELS);
2350               struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2351               struct snd_mask fmt;
2352
2353               snd_mask_any(&fmt);    /* Init the struct */
2354               if (c->min < 2) {
2355                       fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2356                       return snd_mask_refine(f, &fmt);
2357               }
2358               return 0;
2359       }
2360
2361
2362 ... and in the open callback:
2363
2364 ::
2365
2366   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2367                       hw_rule_format_by_channels, NULL,
2368                       SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2369
2370 One typical usage of the hw constraints is to align the buffer size
2371 with the period size.  As default, ALSA PCM core doesn't enforce the
2372 buffer size to be aligned with the period size.  For example, it'd be
2373 possible to have a combination like 256 period bytes with 999 buffer
2374 bytes.
2375
2376 Many device chips, however, require the buffer to be a multiple of
2377 periods.  In such a case, call
2378 :c:func:`snd_pcm_hw_constraint_integer()` for
2379 ``SNDRV_PCM_HW_PARAM_PERIODS``.
2380
2381 ::
2382
2383   snd_pcm_hw_constraint_integer(substream->runtime,
2384                                 SNDRV_PCM_HW_PARAM_PERIODS);
2385
2386 This assures that the number of periods is integer, hence the buffer
2387 size is aligned with the period size.
2388
2389 The hw constraint is a very much powerful mechanism to define the
2390 preferred PCM configuration, and there are relevant helpers.
2391 I won't give more details here, rather I would like to say, “Luke, use
2392 the source.”
2393
2394 Control Interface
2395 =================
2396
2397 General
2398 -------
2399
2400 The control interface is used widely for many switches, sliders, etc.
2401 which are accessed from user-space. Its most important use is the mixer
2402 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2403 implemented on the control kernel API.
2404
2405 ALSA has a well-defined AC97 control module. If your chip supports only
2406 the AC97 and nothing else, you can skip this section.
2407
2408 The control API is defined in ``<sound/control.h>``. Include this file
2409 if you want to add your own controls.
2410
2411 Definition of Controls
2412 ----------------------
2413
2414 To create a new control, you need to define the following three
2415 callbacks: ``info``, ``get`` and ``put``. Then, define a
2416 :c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as:
2417
2418 ::
2419
2420
2421       static struct snd_kcontrol_new my_control = {
2422               .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2423               .name = "PCM Playback Switch",
2424               .index = 0,
2425               .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2426               .private_value = 0xffff,
2427               .info = my_control_info,
2428               .get = my_control_get,
2429               .put = my_control_put
2430       };
2431
2432
2433 The ``iface`` field specifies the control type,
2434 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2435 for global controls that are not logically part of the mixer. If the
2436 control is closely associated with some specific device on the sound
2437 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2438 and specify the device number with the ``device`` and ``subdevice``
2439 fields.
2440
2441 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2442 control name is very important, because its role is classified from
2443 its name. There are pre-defined standard control names. The details
2444 are described in the `Control Names`_ subsection.
2445
2446 The ``index`` field holds the index number of this control. If there
2447 are several different controls with the same name, they can be
2448 distinguished by the index number. This is the case when several
2449 codecs exist on the card. If the index is zero, you can omit the
2450 definition above. 
2451
2452 The ``access`` field contains the access type of this control. Give
2453 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2454 there. The details will be explained in the `Access Flags`_
2455 subsection.
2456
2457 The ``private_value`` field contains an arbitrary long integer value
2458 for this record. When using the generic ``info``, ``get`` and ``put``
2459 callbacks, you can pass a value through this field. If several small
2460 numbers are necessary, you can combine them in bitwise. Or, it's
2461 possible to give a pointer (casted to unsigned long) of some record to
2462 this field, too. 
2463
2464 The ``tlv`` field can be used to provide metadata about the control;
2465 see the `Metadata`_ subsection.
2466
2467 The other three are `Control Callbacks`_.
2468
2469 Control Names
2470 -------------
2471
2472 There are some standards to define the control names. A control is
2473 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2474
2475 The first, ``SOURCE``, specifies the source of the control, and is a
2476 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2477 pre-defined sources.
2478
2479 The second, ``DIRECTION``, is one of the following strings according to
2480 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2481 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2482 capture directions.
2483
2484 The third, ``FUNCTION``, is one of the following strings according to
2485 the function of the control: “Switch”, “Volume” and “Route”.
2486
2487 The example of control names are, thus, “Master Capture Switch” or “PCM
2488 Playback Volume”.
2489
2490 There are some exceptions:
2491
2492 Global capture and playback
2493 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2494
2495 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2496 global capture (input) source, switch and volume. Similarly, “Playback
2497 Switch” and “Playback Volume” are used for the global output gain switch
2498 and volume.
2499
2500 Tone-controls
2501 ~~~~~~~~~~~~~
2502
2503 tone-control switch and volumes are specified like “Tone Control - XXX”,
2504 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2505 Center”.
2506
2507 3D controls
2508 ~~~~~~~~~~~
2509
2510 3D-control switches and volumes are specified like “3D Control - XXX”,
2511 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2512
2513 Mic boost
2514 ~~~~~~~~~
2515
2516 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2517
2518 More precise information can be found in
2519 ``Documentation/sound/designs/control-names.rst``.
2520
2521 Access Flags
2522 ------------
2523
2524 The access flag is the bitmask which specifies the access type of the
2525 given control. The default access type is
2526 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2527 allowed to this control. When the access flag is omitted (i.e. = 0), it
2528 is considered as ``READWRITE`` access as default.
2529
2530 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2531 instead. In this case, you don't have to define the ``put`` callback.
2532 Similarly, when the control is write-only (although it's a rare case),
2533 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2534 callback.
2535
2536 If the control value changes frequently (e.g. the VU meter),
2537 ``VOLATILE`` flag should be given. This means that the control may be
2538 changed without `Change notification`_. Applications should poll such
2539 a control constantly.
2540
2541 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2542 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2543
2544 Control Callbacks
2545 -----------------
2546
2547 info callback
2548 ~~~~~~~~~~~~~
2549
2550 The ``info`` callback is used to get detailed information on this
2551 control. This must store the values of the given :c:type:`struct
2552 snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2553 for a boolean control with a single element:
2554
2555 ::
2556
2557
2558       static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2559                               struct snd_ctl_elem_info *uinfo)
2560       {
2561               uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2562               uinfo->count = 1;
2563               uinfo->value.integer.min = 0;
2564               uinfo->value.integer.max = 1;
2565               return 0;
2566       }
2567
2568
2569
2570 The ``type`` field specifies the type of the control. There are
2571 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2572 ``INTEGER64``. The ``count`` field specifies the number of elements in
2573 this control. For example, a stereo volume would have count = 2. The
2574 ``value`` field is a union, and the values stored are depending on the
2575 type. The boolean and integer types are identical.
2576
2577 The enumerated type is a bit different from others. You'll need to set
2578 the string for the currently given item index.
2579
2580 ::
2581
2582   static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2583                           struct snd_ctl_elem_info *uinfo)
2584   {
2585           static char *texts[4] = {
2586                   "First", "Second", "Third", "Fourth"
2587           };
2588           uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2589           uinfo->count = 1;
2590           uinfo->value.enumerated.items = 4;
2591           if (uinfo->value.enumerated.item > 3)
2592                   uinfo->value.enumerated.item = 3;
2593           strcpy(uinfo->value.enumerated.name,
2594                  texts[uinfo->value.enumerated.item]);
2595           return 0;
2596   }
2597
2598 The above callback can be simplified with a helper function,
2599 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2600 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2601 it's a matter of taste.)
2602
2603 ::
2604
2605   static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2606                           struct snd_ctl_elem_info *uinfo)
2607   {
2608           static char *texts[4] = {
2609                   "First", "Second", "Third", "Fourth"
2610           };
2611           return snd_ctl_enum_info(uinfo, 1, 4, texts);
2612   }
2613
2614
2615 Some common info callbacks are available for your convenience:
2616 :c:func:`snd_ctl_boolean_mono_info()` and
2617 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2618 is an info callback for a mono channel boolean item, just like
2619 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2620 stereo channel boolean item.
2621
2622 get callback
2623 ~~~~~~~~~~~~
2624
2625 This callback is used to read the current value of the control and to
2626 return to user-space.
2627
2628 For example,
2629
2630 ::
2631
2632
2633       static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2634                                struct snd_ctl_elem_value *ucontrol)
2635       {
2636               struct mychip *chip = snd_kcontrol_chip(kcontrol);
2637               ucontrol->value.integer.value[0] = get_some_value(chip);
2638               return 0;
2639       }
2640
2641
2642
2643 The ``value`` field depends on the type of control as well as on the
2644 info callback. For example, the sb driver uses this field to store the
2645 register offset, the bit-shift and the bit-mask. The ``private_value``
2646 field is set as follows:
2647
2648 ::
2649
2650   .private_value = reg | (shift << 16) | (mask << 24)
2651
2652 and is retrieved in callbacks like
2653
2654 ::
2655
2656   static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2657                                     struct snd_ctl_elem_value *ucontrol)
2658   {
2659           int reg = kcontrol->private_value & 0xff;
2660           int shift = (kcontrol->private_value >> 16) & 0xff;
2661           int mask = (kcontrol->private_value >> 24) & 0xff;
2662           ....
2663   }
2664
2665 In the ``get`` callback, you have to fill all the elements if the
2666 control has more than one elements, i.e. ``count > 1``. In the example
2667 above, we filled only one element (``value.integer.value[0]``) since
2668 it's assumed as ``count = 1``.
2669
2670 put callback
2671 ~~~~~~~~~~~~
2672
2673 This callback is used to write a value from user-space.
2674
2675 For example,
2676
2677 ::
2678
2679
2680       static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2681                                struct snd_ctl_elem_value *ucontrol)
2682       {
2683               struct mychip *chip = snd_kcontrol_chip(kcontrol);
2684               int changed = 0;
2685               if (chip->current_value !=
2686                    ucontrol->value.integer.value[0]) {
2687                       change_current_value(chip,
2688                                   ucontrol->value.integer.value[0]);
2689                       changed = 1;
2690               }
2691               return changed;
2692       }
2693
2694
2695
2696 As seen above, you have to return 1 if the value is changed. If the
2697 value is not changed, return 0 instead. If any fatal error happens,
2698 return a negative error code as usual.
2699
2700 As in the ``get`` callback, when the control has more than one
2701 elements, all elements must be evaluated in this callback, too.
2702
2703 Callbacks are not atomic
2704 ~~~~~~~~~~~~~~~~~~~~~~~~
2705
2706 All these three callbacks are basically not atomic.
2707
2708 Control Constructor
2709 -------------------
2710
2711 When everything is ready, finally we can create a new control. To create
2712 a control, there are two functions to be called,
2713 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2714
2715 In the simplest way, you can do like this:
2716
2717 ::
2718
2719   err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2720   if (err < 0)
2721           return err;
2722
2723 where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2724 <snd_kcontrol_new>` object defined above, and chip is the object
2725 pointer to be passed to kcontrol->private_data which can be referred
2726 to in callbacks.
2727
2728 :c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2729 snd_kcontrol <snd_kcontrol>` instance, and
2730 :c:func:`snd_ctl_add()` assigns the given control component to the
2731 card.
2732
2733 Change Notification
2734 -------------------
2735
2736 If you need to change and update a control in the interrupt routine, you
2737 can call :c:func:`snd_ctl_notify()`. For example,
2738
2739 ::
2740
2741   snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2742
2743 This function takes the card pointer, the event-mask, and the control id
2744 pointer for the notification. The event-mask specifies the types of
2745 notification, for example, in the above example, the change of control
2746 values is notified. The id pointer is the pointer of :c:type:`struct
2747 snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2748 find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2749 interrupts.
2750
2751 Metadata
2752 --------
2753
2754 To provide information about the dB values of a mixer control, use on of
2755 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2756 variable containing this information, set the ``tlv.p`` field to point to
2757 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2758 in the ``access`` field; like this:
2759
2760 ::
2761
2762   static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2763
2764   static struct snd_kcontrol_new my_control = {
2765           ...
2766           .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2767                     SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2768           ...
2769           .tlv.p = db_scale_my_control,
2770   };
2771
2772
2773 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2774 about a mixer control where each step in the control's value changes the
2775 dB value by a constant dB amount. The first parameter is the name of the
2776 variable to be defined. The second parameter is the minimum value, in
2777 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2778 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2779 the control.
2780
2781 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2782 about a mixer control where the control's value affects the output
2783 linearly. The first parameter is the name of the variable to be defined.
2784 The second parameter is the minimum value, in units of 0.01 dB. The
2785 third parameter is the maximum value, in units of 0.01 dB. If the
2786 minimum value mutes the control, set the second parameter to
2787 ``TLV_DB_GAIN_MUTE``.
2788
2789 API for AC97 Codec
2790 ==================
2791
2792 General
2793 -------
2794
2795 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2796 write much code to control it. Only low-level control routines are
2797 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2798
2799 Full Code Example
2800 -----------------
2801
2802 ::
2803
2804       struct mychip {
2805               ....
2806               struct snd_ac97 *ac97;
2807               ....
2808       };
2809
2810       static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2811                                                  unsigned short reg)
2812       {
2813               struct mychip *chip = ac97->private_data;
2814               ....
2815               /* read a register value here from the codec */
2816               return the_register_value;
2817       }
2818
2819       static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2820                                        unsigned short reg, unsigned short val)
2821       {
2822               struct mychip *chip = ac97->private_data;
2823               ....
2824               /* write the given register value to the codec */
2825       }
2826
2827       static int snd_mychip_ac97(struct mychip *chip)
2828       {
2829               struct snd_ac97_bus *bus;
2830               struct snd_ac97_template ac97;
2831               int err;
2832               static struct snd_ac97_bus_ops ops = {
2833                       .write = snd_mychip_ac97_write,
2834                       .read = snd_mychip_ac97_read,
2835               };
2836
2837               err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2838               if (err < 0)
2839                       return err;
2840               memset(&ac97, 0, sizeof(ac97));
2841               ac97.private_data = chip;
2842               return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2843       }
2844
2845
2846 AC97 Constructor
2847 ----------------
2848
2849 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2850 with an ``ac97_bus_ops_t`` record with callback functions.
2851
2852 ::
2853
2854   struct snd_ac97_bus *bus;
2855   static struct snd_ac97_bus_ops ops = {
2856         .write = snd_mychip_ac97_write,
2857         .read = snd_mychip_ac97_read,
2858   };
2859
2860   snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2861
2862 The bus record is shared among all belonging ac97 instances.
2863
2864 And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2865 snd_ac97_template <snd_ac97_template>` record together with
2866 the bus pointer created above.
2867
2868 ::
2869
2870   struct snd_ac97_template ac97;
2871   int err;
2872
2873   memset(&ac97, 0, sizeof(ac97));
2874   ac97.private_data = chip;
2875   snd_ac97_mixer(bus, &ac97, &chip->ac97);
2876
2877 where chip->ac97 is a pointer to a newly created ``ac97_t``
2878 instance. In this case, the chip pointer is set as the private data,
2879 so that the read/write callback functions can refer to this chip
2880 instance. This instance is not necessarily stored in the chip
2881 record. If you need to change the register values from the driver, or
2882 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2883 the corresponding functions.
2884
2885 AC97 Callbacks
2886 --------------
2887
2888 The standard callbacks are ``read`` and ``write``. Obviously they
2889 correspond to the functions for read and write accesses to the
2890 hardware low-level codes.
2891
2892 The ``read`` callback returns the register value specified in the
2893 argument.
2894
2895 ::
2896
2897   static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2898                                              unsigned short reg)
2899   {
2900           struct mychip *chip = ac97->private_data;
2901           ....
2902           return the_register_value;
2903   }
2904
2905 Here, the chip can be cast from ``ac97->private_data``.
2906
2907 Meanwhile, the ``write`` callback is used to set the register
2908 value
2909
2910 ::
2911
2912   static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2913                        unsigned short reg, unsigned short val)
2914
2915
2916 These callbacks are non-atomic like the control API callbacks.
2917
2918 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2919
2920 The ``reset`` callback is used to reset the codec. If the chip
2921 requires a special kind of reset, you can define this callback.
2922
2923 The ``wait`` callback is used to add some waiting time in the standard
2924 initialization of the codec. If the chip requires the extra waiting
2925 time, define this callback.
2926
2927 The ``init`` callback is used for additional initialization of the
2928 codec.
2929
2930 Updating Registers in The Driver
2931 --------------------------------
2932
2933 If you need to access to the codec from the driver, you can call the
2934 following functions: :c:func:`snd_ac97_write()`,
2935 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2936 :c:func:`snd_ac97_update_bits()`.
2937
2938 Both :c:func:`snd_ac97_write()` and
2939 :c:func:`snd_ac97_update()` functions are used to set a value to
2940 the given register (``AC97_XXX``). The difference between them is that
2941 :c:func:`snd_ac97_update()` doesn't write a value if the given
2942 value has been already set, while :c:func:`snd_ac97_write()`
2943 always rewrites the value.
2944
2945 ::
2946
2947   snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2948   snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2949
2950 :c:func:`snd_ac97_read()` is used to read the value of the given
2951 register. For example,
2952
2953 ::
2954
2955   value = snd_ac97_read(ac97, AC97_MASTER);
2956
2957 :c:func:`snd_ac97_update_bits()` is used to update some bits in
2958 the given register.
2959
2960 ::
2961
2962   snd_ac97_update_bits(ac97, reg, mask, value);
2963
2964 Also, there is a function to change the sample rate (of a given register
2965 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2966 codec: :c:func:`snd_ac97_set_rate()`.
2967
2968 ::
2969
2970   snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2971
2972
2973 The following registers are available to set the rate:
2974 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2975 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2976 specified, the register is not really changed but the corresponding
2977 IEC958 status bits will be updated.
2978
2979 Clock Adjustment
2980 ----------------
2981
2982 In some chips, the clock of the codec isn't 48000 but using a PCI clock
2983 (to save a quartz!). In this case, change the field ``bus->clock`` to
2984 the corresponding value. For example, intel8x0 and es1968 drivers have
2985 their own function to read from the clock.
2986
2987 Proc Files
2988 ----------
2989
2990 The ALSA AC97 interface will create a proc file such as
2991 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2992 can refer to these files to see the current status and registers of
2993 the codec.
2994
2995 Multiple Codecs
2996 ---------------
2997
2998 When there are several codecs on the same card, you need to call
2999 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
3000 greater. The ``num`` field specifies the codec number.
3001
3002 If you set up multiple codecs, you either need to write different
3003 callbacks for each codec or check ``ac97->num`` in the callback
3004 routines.
3005
3006 MIDI (MPU401-UART) Interface
3007 ============================
3008
3009 General
3010 -------
3011
3012 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3013 soundcard supports the standard MPU401-UART interface, most likely you
3014 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3015 ``<sound/mpu401.h>``.
3016
3017 Some soundchips have a similar but slightly different implementation of
3018 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3019
3020 MIDI Constructor
3021 ----------------
3022
3023 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3024
3025 ::
3026
3027   struct snd_rawmidi *rmidi;
3028   snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3029                       irq, &rmidi);
3030
3031
3032 The first argument is the card pointer, and the second is the index of
3033 this component. You can create up to 8 rawmidi devices.
3034
3035 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3036 it's not a special one, you can use ``MPU401_HW_MPU401``.
3037
3038 The 4th argument is the I/O port address. Many backward-compatible
3039 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3040 PCI I/O region. It depends on the chip design.
3041
3042 The 5th argument is a bitflag for additional information. When the I/O
3043 port address above is part of the PCI I/O region, the MPU401 I/O port
3044 might have been already allocated (reserved) by the driver itself. In
3045 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3046 mpu401-uart layer will allocate the I/O ports by itself.
3047
3048 When the controller supports only the input or output MIDI stream, pass
3049 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3050 respectively. Then the rawmidi instance is created as a single stream.
3051
3052 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3053 (via readb and writeb) instead of iob and outb. In this case, you have
3054 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3055
3056 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3057 the default interrupt handler. The driver needs to call
3058 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3059 processing the output stream in the irq handler.
3060
3061 If the MPU-401 interface shares its interrupt with the other logical
3062 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3063 `below <#MIDI-Interrupt-Handler>`__).
3064
3065 Usually, the port address corresponds to the command port and port + 1
3066 corresponds to the data port. If not, you may change the ``cport``
3067 field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3068 However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
3069 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3070 need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401
3071 <snd_mpu401>` explicitly,
3072
3073 ::
3074
3075   struct snd_mpu401 *mpu;
3076   mpu = rmidi->private_data;
3077
3078 and reset the ``cport`` as you like:
3079
3080 ::
3081
3082   mpu->cport = my_own_control_port;
3083
3084 The 6th argument specifies the ISA irq number that will be allocated. If
3085 no interrupt is to be allocated (because your code is already allocating
3086 a shared interrupt, or because the device does not use interrupts), pass
3087 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3088 will be used instead.
3089
3090 MIDI Interrupt Handler
3091 ----------------------
3092
3093 When the interrupt is allocated in
3094 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3095 handler is automatically used, hence you don't have anything else to do
3096 than creating the mpu401 stuff. Otherwise, you have to set
3097 ``MPU401_INFO_IRQ_HOOK``, and call
3098 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3099 interrupt handler when it has determined that a UART interrupt has
3100 occurred.
3101
3102 In this case, you need to pass the private_data of the returned rawmidi
3103 object from :c:func:`snd_mpu401_uart_new()` as the second
3104 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3105
3106 ::
3107
3108   snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3109
3110
3111 RawMIDI Interface
3112 =================
3113
3114 Overview
3115 --------
3116
3117 The raw MIDI interface is used for hardware MIDI ports that can be
3118 accessed as a byte stream. It is not used for synthesizer chips that do
3119 not directly understand MIDI.
3120
3121 ALSA handles file and buffer management. All you have to do is to write
3122 some code to move data between the buffer and the hardware.
3123
3124 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3125
3126 RawMIDI Constructor
3127 -------------------
3128
3129 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3130 function:
3131
3132 ::
3133
3134   struct snd_rawmidi *rmidi;
3135   err = snd_rawmidi_new(chip-&g