255b7d3bebd6f7d616b634a253b872d81f6e4363
[linux-2.6-microblaze.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 struct 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 const 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 <7) 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 calling :c:func:`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 device, specifies the parent
564 device. For PCI devices, typically ``&pci->`` is passed there.
565
566 Components
567 ----------
568
569 After the card is created, you can attach the components (devices) to
570 the card instance. In an ALSA driver, a component is represented as a
571 struct snd_device object. A component
572 can be a PCM instance, a control interface, a raw MIDI interface, etc.
573 Each such instance has one component entry.
574
575 A component can be created via :c:func:`snd_device_new()`
576 function.
577
578 ::
579
580   snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
581
582 This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
583 data pointer, and the callback pointers (``&ops``). The device-level
584 defines the type of components and the order of registration and
585 de-registration. For most components, the device-level is already
586 defined. For a user-defined component, you can use
587 ``SNDRV_DEV_LOWLEVEL``.
588
589 This function itself doesn't allocate the data space. The data must be
590 allocated manually beforehand, and its pointer is passed as the
591 argument. This pointer (``chip`` in the above example) is used as the
592 identifier for the instance.
593
594 Each pre-defined ALSA component such as ac97 and pcm calls
595 :c:func:`snd_device_new()` inside its constructor. The destructor
596 for each component is defined in the callback pointers. Hence, you don't
597 need to take care of calling a destructor for such a component.
598
599 If you wish to create your own component, you need to set the destructor
600 function to the dev_free callback in the ``ops``, so that it can be
601 released automatically via :c:func:`snd_card_free()`. The next
602 example will show an implementation of chip-specific data.
603
604 Chip-Specific Data
605 ------------------
606
607 Chip-specific information, e.g. the I/O port address, its resource
608 pointer, or the irq number, is stored in the chip-specific record.
609
610 ::
611
612   struct mychip {
613           ....
614   };
615
616
617 In general, there are two ways of allocating the chip record.
618
619 1. Allocating via :c:func:`snd_card_new()`.
620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
621
622 As mentioned above, you can pass the extra-data-length to the 5th
623 argument of :c:func:`snd_card_new()`, i.e.
624
625 ::
626
627   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
628                      sizeof(struct mychip), &card);
629
630 struct mychip is the type of the chip record.
631
632 In return, the allocated record can be accessed as
633
634 ::
635
636   struct mychip *chip = card->private_data;
637
638 With this method, you don't have to allocate twice. The record is
639 released together with the card instance.
640
641 2. Allocating an extra device.
642 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
643
644 After allocating a card instance via :c:func:`snd_card_new()`
645 (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
646
647 ::
648
649   struct snd_card *card;
650   struct mychip *chip;
651   err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
652                      0, &card);
653   .....
654   chip = kzalloc(sizeof(*chip), GFP_KERNEL);
655
656 The chip record should have the field to hold the card pointer at least,
657
658 ::
659
660   struct mychip {
661           struct snd_card *card;
662           ....
663   };
664
665
666 Then, set the card pointer in the returned chip instance.
667
668 ::
669
670   chip->card = card;
671
672 Next, initialize the fields, and register this chip record as a
673 low-level device with a specified ``ops``,
674
675 ::
676
677   static const struct snd_device_ops ops = {
678           .dev_free =        snd_mychip_dev_free,
679   };
680   ....
681   snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
682
683 :c:func:`snd_mychip_dev_free()` is the device-destructor
684 function, which will call the real destructor.
685
686 ::
687
688   static int snd_mychip_dev_free(struct snd_device *device)
689   {
690           return snd_mychip_free(device->device_data);
691   }
692
693 where :c:func:`snd_mychip_free()` is the real destructor.
694
695 The demerit of this method is the obviously more amount of codes.
696 The merit is, however, you can trigger the own callback at registering
697 and disconnecting the card via setting in snd_device_ops.
698 About the registering and disconnecting the card, see the subsections
699 below.
700
701
702 Registration and Release
703 ------------------------
704
705 After all components are assigned, register the card instance by calling
706 :c:func:`snd_card_register()`. Access to the device files is
707 enabled at this point. That is, before
708 :c:func:`snd_card_register()` is called, the components are safely
709 inaccessible from external side. If this call fails, exit the probe
710 function after releasing the card via :c:func:`snd_card_free()`.
711
712 For releasing the card instance, you can call simply
713 :c:func:`snd_card_free()`. As mentioned earlier, all components
714 are released automatically by this call.
715
716 For a device which allows hotplugging, you can use
717 :c:func:`snd_card_free_when_closed()`. This one will postpone
718 the destruction until all devices are closed.
719
720 PCI Resource Management
721 =======================
722
723 Full Code Example
724 -----------------
725
726 In this section, we'll complete the chip-specific constructor,
727 destructor and PCI entries. Example code is shown first, below.
728
729 ::
730
731       struct mychip {
732               struct snd_card *card;
733               struct pci_dev *pci;
734
735               unsigned long port;
736               int irq;
737       };
738
739       static int snd_mychip_free(struct mychip *chip)
740       {
741               /* disable hardware here if any */
742               .... /* (not implemented in this document) */
743
744               /* release the irq */
745               if (chip->irq >= 0)
746                       free_irq(chip->irq, chip);
747               /* release the I/O ports & memory */
748               pci_release_regions(chip->pci);
749               /* disable the PCI entry */
750               pci_disable_device(chip->pci);
751               /* release the data */
752               kfree(chip);
753               return 0;
754       }
755
756       /* chip-specific constructor */
757       static int snd_mychip_create(struct snd_card *card,
758                                    struct pci_dev *pci,
759                                    struct mychip **rchip)
760       {
761               struct mychip *chip;
762               int err;
763               static const struct snd_device_ops ops = {
764                      .dev_free = snd_mychip_dev_free,
765               };
766
767               *rchip = NULL;
768
769               /* initialize the PCI entry */
770               err = pci_enable_device(pci);
771               if (err < 0)
772                       return err;
773               /* check PCI availability (28bit DMA) */
774               if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
775                   pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
776                       printk(KERN_ERR "error to set 28bit mask DMA\n");
777                       pci_disable_device(pci);
778                       return -ENXIO;
779               }
780
781               chip = kzalloc(sizeof(*chip), GFP_KERNEL);
782               if (chip == NULL) {
783                       pci_disable_device(pci);
784                       return -ENOMEM;
785               }
786
787               /* initialize the stuff */
788               chip->card = card;
789               chip->pci = pci;
790               chip->irq = -1;
791
792               /* (1) PCI resource allocation */
793               err = pci_request_regions(pci, "My Chip");
794               if (err < 0) {
795                       kfree(chip);
796                       pci_disable_device(pci);
797                       return err;
798               }
799               chip->port = pci_resource_start(pci, 0);
800               if (request_irq(pci->irq, snd_mychip_interrupt,
801                               IRQF_SHARED, KBUILD_MODNAME, chip)) {
802                       printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
803                       snd_mychip_free(chip);
804                       return -EBUSY;
805               }
806               chip->irq = pci->irq;
807               card->sync_irq = chip->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 struct 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 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 After requesting the IRQ, you can passed it to ``card->sync_irq``
969 field:
970 ::
971
972           card->irq = chip->irq;
973
974 This allows PCM core automatically performing
975 :c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
976 See the later section `sync_stop callback`_ for details.
977
978 Now let's write the corresponding destructor for the resources above.
979 The role of destructor is simple: disable the hardware (if already
980 activated) and release the resources. So far, we have no hardware part,
981 so the disabling code is not written here.
982
983 To release the resources, the “check-and-release” method is a safer way.
984 For the interrupt, do like this:
985
986 ::
987
988   if (chip->irq >= 0)
989           free_irq(chip->irq, chip);
990
991 Since the irq number can start from 0, you should initialize
992 ``chip->irq`` with a negative value (e.g. -1), so that you can check
993 the validity of the irq number as above.
994
995 When you requested I/O ports or memory regions via
996 :c:func:`pci_request_region()` or
997 :c:func:`pci_request_regions()` like in this example, release the
998 resource(s) using the corresponding function,
999 :c:func:`pci_release_region()` or
1000 :c:func:`pci_release_regions()`.
1001
1002 ::
1003
1004   pci_release_regions(chip->pci);
1005
1006 When you requested manually via :c:func:`request_region()` or
1007 :c:func:`request_mem_region()`, you can release it via
1008 :c:func:`release_resource()`. Suppose that you keep the resource
1009 pointer returned from :c:func:`request_region()` in
1010 chip->res_port, the release procedure looks like:
1011
1012 ::
1013
1014   release_and_free_resource(chip->res_port);
1015
1016 Don't forget to call :c:func:`pci_disable_device()` before the
1017 end.
1018
1019 And finally, release the chip-specific record.
1020
1021 ::
1022
1023   kfree(chip);
1024
1025 We didn't implement the hardware disabling part in the above. If you
1026 need to do this, please note that the destructor may be called even
1027 before the initialization of the chip is completed. It would be better
1028 to have a flag to skip hardware disabling if the hardware was not
1029 initialized yet.
1030
1031 When the chip-data is assigned to the card using
1032 :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1033 destructor is called at the last. That is, it is assured that all other
1034 components like PCMs and controls have already been released. You don't
1035 have to stop PCMs, etc. explicitly, but just call low-level hardware
1036 stopping.
1037
1038 The management of a memory-mapped region is almost as same as the
1039 management of an I/O port. You'll need three fields like the
1040 following:
1041
1042 ::
1043
1044   struct mychip {
1045           ....
1046           unsigned long iobase_phys;
1047           void __iomem *iobase_virt;
1048   };
1049
1050 and the allocation would be like below:
1051
1052 ::
1053
1054   err = pci_request_regions(pci, "My Chip");
1055   if (err < 0) {
1056           kfree(chip);
1057           return err;
1058   }
1059   chip->iobase_phys = pci_resource_start(pci, 0);
1060   chip->iobase_virt = ioremap(chip->iobase_phys,
1061                                       pci_resource_len(pci, 0));
1062
1063 and the corresponding destructor would be:
1064
1065 ::
1066
1067   static int snd_mychip_free(struct mychip *chip)
1068   {
1069           ....
1070           if (chip->iobase_virt)
1071                   iounmap(chip->iobase_virt);
1072           ....
1073           pci_release_regions(chip->pci);
1074           ....
1075   }
1076
1077 Of course, a modern way with :c:func:`pci_iomap()` will make things a
1078 bit easier, too.
1079
1080 ::
1081
1082   err = pci_request_regions(pci, "My Chip");
1083   if (err < 0) {
1084           kfree(chip);
1085           return err;
1086   }
1087   chip->iobase_virt = pci_iomap(pci, 0, 0);
1088
1089 which is paired with :c:func:`pci_iounmap()` at destructor.
1090
1091
1092 PCI Entries
1093 -----------
1094
1095 So far, so good. Let's finish the missing PCI stuff. At first, we need a
1096 struct pci_device_id table for
1097 this chipset. It's a table of PCI vendor/device ID number, and some
1098 masks.
1099
1100 For example,
1101
1102 ::
1103
1104   static struct pci_device_id snd_mychip_ids[] = {
1105           { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1106             PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1107           ....
1108           { 0, }
1109   };
1110   MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1111
1112 The first and second fields of the struct pci_device_id are the vendor
1113 and device IDs. If you have no reason to filter the matching devices, you can
1114 leave the remaining fields as above. The last field of the
1115 struct pci_device_id contains private data for this entry. You can specify
1116 any value here, for example, to define specific operations for supported
1117 device IDs. Such an example is found in the intel8x0 driver.
1118
1119 The last entry of this list is the terminator. You must specify this
1120 all-zero entry.
1121
1122 Then, prepare the struct pci_driver
1123 record:
1124
1125 ::
1126
1127   static struct pci_driver driver = {
1128           .name = KBUILD_MODNAME,
1129           .id_table = snd_mychip_ids,
1130           .probe = snd_mychip_probe,
1131           .remove = snd_mychip_remove,
1132   };
1133
1134 The ``probe`` and ``remove`` functions have already been defined in
1135 the previous sections. The ``name`` field is the name string of this
1136 device. Note that you must not use a slash “/” in this string.
1137
1138 And at last, the module entries:
1139
1140 ::
1141
1142   static int __init alsa_card_mychip_init(void)
1143   {
1144           return pci_register_driver(&driver);
1145   }
1146
1147   static void __exit alsa_card_mychip_exit(void)
1148   {
1149           pci_unregister_driver(&driver);
1150   }
1151
1152   module_init(alsa_card_mychip_init)
1153   module_exit(alsa_card_mychip_exit)
1154
1155 Note that these module entries are tagged with ``__init`` and ``__exit``
1156 prefixes.
1157
1158 That's all!
1159
1160 PCM Interface
1161 =============
1162
1163 General
1164 -------
1165
1166 The PCM middle layer of ALSA is quite powerful and it is only necessary
1167 for each driver to implement the low-level functions to access its
1168 hardware.
1169
1170 For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1171 first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1172 access to some functions related with hw_param.
1173
1174 Each card device can have up to four pcm instances. A pcm instance
1175 corresponds to a pcm device file. The limitation of number of instances
1176 comes only from the available bit size of the Linux's device numbers.
1177 Once when 64bit device number is used, we'll have more pcm instances
1178 available.
1179
1180 A pcm instance consists of pcm playback and capture streams, and each
1181 pcm stream consists of one or more pcm substreams. Some soundcards
1182 support multiple playback functions. For example, emu10k1 has a PCM
1183 playback of 32 stereo substreams. In this case, at each open, a free
1184 substream is (usually) automatically chosen and opened. Meanwhile, when
1185 only one substream exists and it was already opened, the successful open
1186 will either block or error with ``EAGAIN`` according to the file open
1187 mode. But you don't have to care about such details in your driver. The
1188 PCM middle layer will take care of such work.
1189
1190 Full Code Example
1191 -----------------
1192
1193 The example code below does not include any hardware access routines but
1194 shows only the skeleton, how to build up the PCM interfaces.
1195
1196 ::
1197
1198       #include <sound/pcm.h>
1199       ....
1200
1201       /* hardware definition */
1202       static struct snd_pcm_hardware snd_mychip_playback_hw = {
1203               .info = (SNDRV_PCM_INFO_MMAP |
1204                        SNDRV_PCM_INFO_INTERLEAVED |
1205                        SNDRV_PCM_INFO_BLOCK_TRANSFER |
1206                        SNDRV_PCM_INFO_MMAP_VALID),
1207               .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1208               .rates =            SNDRV_PCM_RATE_8000_48000,
1209               .rate_min =         8000,
1210               .rate_max =         48000,
1211               .channels_min =     2,
1212               .channels_max =     2,
1213               .buffer_bytes_max = 32768,
1214               .period_bytes_min = 4096,
1215               .period_bytes_max = 32768,
1216               .periods_min =      1,
1217               .periods_max =      1024,
1218       };
1219
1220       /* hardware definition */
1221       static struct snd_pcm_hardware snd_mychip_capture_hw = {
1222               .info = (SNDRV_PCM_INFO_MMAP |
1223                        SNDRV_PCM_INFO_INTERLEAVED |
1224                        SNDRV_PCM_INFO_BLOCK_TRANSFER |
1225                        SNDRV_PCM_INFO_MMAP_VALID),
1226               .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1227               .rates =            SNDRV_PCM_RATE_8000_48000,
1228               .rate_min =         8000,
1229               .rate_max =         48000,
1230               .channels_min =     2,
1231               .channels_max =     2,
1232               .buffer_bytes_max = 32768,
1233               .period_bytes_min = 4096,
1234               .period_bytes_max = 32768,
1235               .periods_min =      1,
1236               .periods_max =      1024,
1237       };
1238
1239       /* open callback */
1240       static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1241       {
1242               struct mychip *chip = snd_pcm_substream_chip(substream);
1243               struct snd_pcm_runtime *runtime = substream->runtime;
1244
1245               runtime->hw = snd_mychip_playback_hw;
1246               /* more hardware-initialization will be done here */
1247               ....
1248               return 0;
1249       }
1250
1251       /* close callback */
1252       static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1253       {
1254               struct mychip *chip = snd_pcm_substream_chip(substream);
1255               /* the hardware-specific codes will be here */
1256               ....
1257               return 0;
1258
1259       }
1260
1261       /* open callback */
1262       static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1263       {
1264               struct mychip *chip = snd_pcm_substream_chip(substream);
1265               struct snd_pcm_runtime *runtime = substream->runtime;
1266
1267               runtime->hw = snd_mychip_capture_hw;
1268               /* more hardware-initialization will be done here */
1269               ....
1270               return 0;
1271       }
1272
1273       /* close callback */
1274       static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1275       {
1276               struct mychip *chip = snd_pcm_substream_chip(substream);
1277               /* the hardware-specific codes will be here */
1278               ....
1279               return 0;
1280       }
1281
1282       /* hw_params callback */
1283       static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1284                                    struct snd_pcm_hw_params *hw_params)
1285       {
1286               /* the hardware-specific codes will be here */
1287               ....
1288               return 0;
1289       }
1290
1291       /* hw_free callback */
1292       static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1293       {
1294               /* the hardware-specific codes will be here */
1295               ....
1296               return 0;
1297       }
1298
1299       /* prepare callback */
1300       static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1301       {
1302               struct mychip *chip = snd_pcm_substream_chip(substream);
1303               struct snd_pcm_runtime *runtime = substream->runtime;
1304
1305               /* set up the hardware with the current configuration
1306                * for example...
1307                */
1308               mychip_set_sample_format(chip, runtime->format);
1309               mychip_set_sample_rate(chip, runtime->rate);
1310               mychip_set_channels(chip, runtime->channels);
1311               mychip_set_dma_setup(chip, runtime->dma_addr,
1312                                    chip->buffer_size,
1313                                    chip->period_size);
1314               return 0;
1315       }
1316
1317       /* trigger callback */
1318       static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1319                                         int cmd)
1320       {
1321               switch (cmd) {
1322               case SNDRV_PCM_TRIGGER_START:
1323                       /* do something to start the PCM engine */
1324                       ....
1325                       break;
1326               case SNDRV_PCM_TRIGGER_STOP:
1327                       /* do something to stop the PCM engine */
1328                       ....
1329                       break;
1330               default:
1331                       return -EINVAL;
1332               }
1333       }
1334
1335       /* pointer callback */
1336       static snd_pcm_uframes_t
1337       snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1338       {
1339               struct mychip *chip = snd_pcm_substream_chip(substream);
1340               unsigned int current_ptr;
1341
1342               /* get the current hardware pointer */
1343               current_ptr = mychip_get_hw_pointer(chip);
1344               return current_ptr;
1345       }
1346
1347       /* operators */
1348       static struct snd_pcm_ops snd_mychip_playback_ops = {
1349               .open =        snd_mychip_playback_open,
1350               .close =       snd_mychip_playback_close,
1351               .hw_params =   snd_mychip_pcm_hw_params,
1352               .hw_free =     snd_mychip_pcm_hw_free,
1353               .prepare =     snd_mychip_pcm_prepare,
1354               .trigger =     snd_mychip_pcm_trigger,
1355               .pointer =     snd_mychip_pcm_pointer,
1356       };
1357
1358       /* operators */
1359       static struct snd_pcm_ops snd_mychip_capture_ops = {
1360               .open =        snd_mychip_capture_open,
1361               .close =       snd_mychip_capture_close,
1362               .hw_params =   snd_mychip_pcm_hw_params,
1363               .hw_free =     snd_mychip_pcm_hw_free,
1364               .prepare =     snd_mychip_pcm_prepare,
1365               .trigger =     snd_mychip_pcm_trigger,
1366               .pointer =     snd_mychip_pcm_pointer,
1367       };
1368
1369       /*
1370        *  definitions of capture are omitted here...
1371        */
1372
1373       /* create a pcm device */
1374       static int snd_mychip_new_pcm(struct mychip *chip)
1375       {
1376               struct snd_pcm *pcm;
1377               int err;
1378
1379               err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1380               if (err < 0)
1381                       return err;
1382               pcm->private_data = chip;
1383               strcpy(pcm->name, "My Chip");
1384               chip->pcm = pcm;
1385               /* set operators */
1386               snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1387                               &snd_mychip_playback_ops);
1388               snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1389                               &snd_mychip_capture_ops);
1390               /* pre-allocation of buffers */
1391               /* NOTE: this may fail */
1392               snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1393                                              &chip->pci->dev,
1394                                              64*1024, 64*1024);
1395               return 0;
1396       }
1397
1398
1399 PCM Constructor
1400 ---------------
1401
1402 A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1403 function. It would be better to create a constructor for pcm, namely,
1404
1405 ::
1406
1407   static int snd_mychip_new_pcm(struct mychip *chip)
1408   {
1409           struct snd_pcm *pcm;
1410           int err;
1411
1412           err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1413           if (err < 0) 
1414                   return err;
1415           pcm->private_data = chip;
1416           strcpy(pcm->name, "My Chip");
1417           chip->pcm = pcm;
1418           ....
1419           return 0;
1420   }
1421
1422 The :c:func:`snd_pcm_new()` function takes four arguments. The
1423 first argument is the card pointer to which this pcm is assigned, and
1424 the second is the ID string.
1425
1426 The third argument (``index``, 0 in the above) is the index of this new
1427 pcm. It begins from zero. If you create more than one pcm instances,
1428 specify the different numbers in this argument. For example, ``index =
1429 1`` for the second PCM device.
1430
1431 The fourth and fifth arguments are the number of substreams for playback
1432 and capture, respectively. Here 1 is used for both arguments. When no
1433 playback or capture substreams are available, pass 0 to the
1434 corresponding argument.
1435
1436 If a chip supports multiple playbacks or captures, you can specify more
1437 numbers, but they must be handled properly in open/close, etc.
1438 callbacks. When you need to know which substream you are referring to,
1439 then it can be obtained from struct snd_pcm_substream data passed to each
1440 callback as follows:
1441
1442 ::
1443
1444   struct snd_pcm_substream *substream;
1445   int index = substream->number;
1446
1447
1448 After the pcm is created, you need to set operators for each pcm stream.
1449
1450 ::
1451
1452   snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1453                   &snd_mychip_playback_ops);
1454   snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1455                   &snd_mychip_capture_ops);
1456
1457 The operators are defined typically like this:
1458
1459 ::
1460
1461   static struct snd_pcm_ops snd_mychip_playback_ops = {
1462           .open =        snd_mychip_pcm_open,
1463           .close =       snd_mychip_pcm_close,
1464           .hw_params =   snd_mychip_pcm_hw_params,
1465           .hw_free =     snd_mychip_pcm_hw_free,
1466           .prepare =     snd_mychip_pcm_prepare,
1467           .trigger =     snd_mychip_pcm_trigger,
1468           .pointer =     snd_mychip_pcm_pointer,
1469   };
1470
1471 All the callbacks are described in the Operators_ subsection.
1472
1473 After setting the operators, you probably will want to pre-allocate the
1474 buffer and set up the managed allocation mode.
1475 For that, simply call the following:
1476
1477 ::
1478
1479   snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1480                                  &chip->pci->dev,
1481                                  64*1024, 64*1024);
1482
1483 It will allocate a buffer up to 64kB as default. Buffer management
1484 details will be described in the later section `Buffer and Memory
1485 Management`_.
1486
1487 Additionally, you can set some extra information for this pcm in
1488 ``pcm->info_flags``. The available values are defined as
1489 ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1490 hardware definition (described later). When your soundchip supports only
1491 half-duplex, specify like this:
1492
1493 ::
1494
1495   pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1496
1497
1498 ... And the Destructor?
1499 -----------------------
1500
1501 The destructor for a pcm instance is not always necessary. Since the pcm
1502 device will be released by the middle layer code automatically, you
1503 don't have to call the destructor explicitly.
1504
1505 The destructor would be necessary if you created special records
1506 internally and needed to release them. In such a case, set the
1507 destructor function to ``pcm->private_free``:
1508
1509 ::
1510
1511       static void mychip_pcm_free(struct snd_pcm *pcm)
1512       {
1513               struct mychip *chip = snd_pcm_chip(pcm);
1514               /* free your own data */
1515               kfree(chip->my_private_pcm_data);
1516               /* do what you like else */
1517               ....
1518       }
1519
1520       static int snd_mychip_new_pcm(struct mychip *chip)
1521       {
1522               struct snd_pcm *pcm;
1523               ....
1524               /* allocate your own data */
1525               chip->my_private_pcm_data = kmalloc(...);
1526               /* set the destructor */
1527               pcm->private_data = chip;
1528               pcm->private_free = mychip_pcm_free;
1529               ....
1530       }
1531
1532
1533
1534 Runtime Pointer - The Chest of PCM Information
1535 ----------------------------------------------
1536
1537 When the PCM substream is opened, a PCM runtime instance is allocated
1538 and assigned to the substream. This pointer is accessible via
1539 ``substream->runtime``. This runtime pointer holds most information you
1540 need to control the PCM: the copy of hw_params and sw_params
1541 configurations, the buffer pointers, mmap records, spinlocks, etc.
1542
1543 The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1544 are the contents of this file:
1545
1546 ::
1547
1548   struct _snd_pcm_runtime {
1549           /* -- Status -- */
1550           struct snd_pcm_substream *trigger_master;
1551           snd_timestamp_t trigger_tstamp;       /* trigger timestamp */
1552           int overrange;
1553           snd_pcm_uframes_t avail_max;
1554           snd_pcm_uframes_t hw_ptr_base;        /* Position at buffer restart */
1555           snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1556   
1557           /* -- HW params -- */
1558           snd_pcm_access_t access;      /* access mode */
1559           snd_pcm_format_t format;      /* SNDRV_PCM_FORMAT_* */
1560           snd_pcm_subformat_t subformat;        /* subformat */
1561           unsigned int rate;            /* rate in Hz */
1562           unsigned int channels;                /* channels */
1563           snd_pcm_uframes_t period_size;        /* period size */
1564           unsigned int periods;         /* periods */
1565           snd_pcm_uframes_t buffer_size;        /* buffer size */
1566           unsigned int tick_time;               /* tick time */
1567           snd_pcm_uframes_t min_align;  /* Min alignment for the format */
1568           size_t byte_align;
1569           unsigned int frame_bits;
1570           unsigned int sample_bits;
1571           unsigned int info;
1572           unsigned int rate_num;
1573           unsigned int rate_den;
1574   
1575           /* -- SW params -- */
1576           struct timespec tstamp_mode;  /* mmap timestamp is updated */
1577           unsigned int period_step;
1578           unsigned int sleep_min;               /* min ticks to sleep */
1579           snd_pcm_uframes_t start_threshold;
1580           snd_pcm_uframes_t stop_threshold;
1581           snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
1582                                                   noise is nearest than this */
1583           snd_pcm_uframes_t silence_size;       /* Silence filling size */
1584           snd_pcm_uframes_t boundary;   /* pointers wrap point */
1585   
1586           snd_pcm_uframes_t silenced_start;
1587           snd_pcm_uframes_t silenced_size;
1588   
1589           snd_pcm_sync_id_t sync;               /* hardware synchronization ID */
1590   
1591           /* -- mmap -- */
1592           volatile struct snd_pcm_mmap_status *status;
1593           volatile struct snd_pcm_mmap_control *control;
1594           atomic_t mmap_count;
1595   
1596           /* -- locking / scheduling -- */
1597           spinlock_t lock;
1598           wait_queue_head_t sleep;
1599           struct timer_list tick_timer;
1600           struct fasync_struct *fasync;
1601
1602           /* -- private section -- */
1603           void *private_data;
1604           void (*private_free)(struct snd_pcm_runtime *runtime);
1605   
1606           /* -- hardware description -- */
1607           struct snd_pcm_hardware hw;
1608           struct snd_pcm_hw_constraints hw_constraints;
1609   
1610           /* -- timer -- */
1611           unsigned int timer_resolution;        /* timer resolution */
1612   
1613           /* -- DMA -- */           
1614           unsigned char *dma_area;      /* DMA area */
1615           dma_addr_t dma_addr;          /* physical bus address (not accessible from main CPU) */
1616           size_t dma_bytes;             /* size of DMA area */
1617   
1618           struct snd_dma_buffer *dma_buffer_p;  /* allocated buffer */
1619   
1620   #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1621           /* -- OSS things -- */
1622           struct snd_pcm_oss_runtime oss;
1623   #endif
1624   };
1625
1626
1627 For the operators (callbacks) of each sound driver, most of these
1628 records are supposed to be read-only. Only the PCM middle-layer changes
1629 / updates them. The exceptions are the hardware description (hw) DMA
1630 buffer information and the private data. Besides, if you use the
1631 standard managed buffer allocation mode, you don't need to set the
1632 DMA buffer information by yourself.
1633
1634 In the sections below, important records are explained.
1635
1636 Hardware Description
1637 ~~~~~~~~~~~~~~~~~~~~
1638
1639 The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
1640 the fundamental hardware configuration. Above all, you'll need to define this
1641 in the `PCM open callback`_. Note that the runtime instance holds the copy of
1642 the descriptor, not the pointer to the existing descriptor. That is,
1643 in the open callback, you can modify the copied descriptor
1644 (``runtime->hw``) as you need. For example, if the maximum number of
1645 channels is 1 only on some chip models, you can still use the same
1646 hardware descriptor and change the channels_max later:
1647
1648 ::
1649
1650           struct snd_pcm_runtime *runtime = substream->runtime;
1651           ...
1652           runtime->hw = snd_mychip_playback_hw; /* common definition */
1653           if (chip->model == VERY_OLD_ONE)
1654                   runtime->hw.channels_max = 1;
1655
1656 Typically, you'll have a hardware descriptor as below:
1657
1658 ::
1659
1660   static struct snd_pcm_hardware snd_mychip_playback_hw = {
1661           .info = (SNDRV_PCM_INFO_MMAP |
1662                    SNDRV_PCM_INFO_INTERLEAVED |
1663                    SNDRV_PCM_INFO_BLOCK_TRANSFER |
1664                    SNDRV_PCM_INFO_MMAP_VALID),
1665           .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1666           .rates =            SNDRV_PCM_RATE_8000_48000,
1667           .rate_min =         8000,
1668           .rate_max =         48000,
1669           .channels_min =     2,
1670           .channels_max =     2,
1671           .buffer_bytes_max = 32768,
1672           .period_bytes_min = 4096,
1673           .period_bytes_max = 32768,
1674           .periods_min =      1,
1675           .periods_max =      1024,
1676   };
1677
1678 -  The ``info`` field contains the type and capabilities of this
1679    pcm. The bit flags are defined in ``<sound/asound.h>`` as
1680    ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1681    the mmap is supported and which interleaved format is
1682    supported. When the hardware supports mmap, add the
1683    ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1684    interleaved or the non-interleaved formats,
1685    ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1686    flag must be set, respectively. If both are supported, you can set
1687    both, too.
1688
1689    In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1690    specified for the OSS mmap mode. Usually both are set. Of course,
1691    ``MMAP_VALID`` is set only if the mmap is really supported.
1692
1693    The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1694    ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
1695    supports the “pause” operation, while the ``RESUME`` bit means that
1696    the pcm supports the full “suspend/resume” operation. If the
1697    ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1698    the corresponding (pause push/release) commands. The suspend/resume
1699    trigger commands can be defined even without the ``RESUME``
1700    flag. See `Power Management`_ section for details.
1701
1702    When the PCM substreams can be synchronized (typically,
1703    synchronized start/stop of a playback and a capture streams), you
1704    can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1705    need to check the linked-list of PCM substreams in the trigger
1706    callback. This will be described in the later section.
1707
1708 -  ``formats`` field contains the bit-flags of supported formats
1709    (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1710    format, give all or'ed bits. In the example above, the signed 16bit
1711    little-endian format is specified.
1712
1713 -  ``rates`` field contains the bit-flags of supported rates
1714    (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1715    pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
1716    provided only for typical rates. If your chip supports
1717    unconventional rates, you need to add the ``KNOT`` bit and set up
1718    the hardware constraint manually (explained later).
1719
1720 -  ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1721    rate. This should correspond somehow to ``rates`` bits.
1722
1723 -  ``channel_min`` and ``channel_max`` define, as you might already
1724    expected, the minimum and maximum number of channels.
1725
1726 -  ``buffer_bytes_max`` defines the maximum buffer size in
1727    bytes. There is no ``buffer_bytes_min`` field, since it can be
1728    calculated from the minimum period size and the minimum number of
1729    periods. Meanwhile, ``period_bytes_min`` and define the minimum and
1730    maximum size of the period in bytes. ``periods_max`` and
1731    ``periods_min`` define the maximum and minimum number of periods in
1732    the buffer.
1733
1734    The “period” is a term that corresponds to a fragment in the OSS
1735    world. The period defines the size at which a PCM interrupt is
1736    generated. This size strongly depends on the hardware. Generally,
1737    the smaller period size will give you more interrupts, that is,
1738    more controls. In the case of capture, this size defines the input
1739    latency. On the other hand, the whole buffer size defines the
1740    output latency for the playback direction.
1741
1742 -  There is also a field ``fifo_size``. This specifies the size of the
1743    hardware FIFO, but currently it is neither used in the driver nor
1744    in the alsa-lib. So, you can ignore this field.
1745
1746 PCM Configurations
1747 ~~~~~~~~~~~~~~~~~~
1748
1749 Ok, let's go back again to the PCM runtime records. The most
1750 frequently referred records in the runtime instance are the PCM
1751 configurations. The PCM configurations are stored in the runtime
1752 instance after the application sends ``hw_params`` data via
1753 alsa-lib. There are many fields copied from hw_params and sw_params
1754 structs. For example, ``format`` holds the format type chosen by the
1755 application. This field contains the enum value
1756 ``SNDRV_PCM_FORMAT_XXX``.
1757
1758 One thing to be noted is that the configured buffer and period sizes
1759 are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1760 channels \* samples-size``. For conversion between frames and bytes,
1761 you can use the :c:func:`frames_to_bytes()` and
1762 :c:func:`bytes_to_frames()` helper functions.
1763
1764 ::
1765
1766   period_bytes = frames_to_bytes(runtime, runtime->period_size);
1767
1768 Also, many software parameters (sw_params) are stored in frames, too.
1769 Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1770 frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1771 frames as signed integer.
1772
1773 DMA Buffer Information
1774 ~~~~~~~~~~~~~~~~~~~~~~
1775
1776 The DMA buffer is defined by the following four fields, ``dma_area``,
1777 ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1778 holds the buffer pointer (the logical address). You can call
1779 :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1780 the physical address of the buffer. This field is specified only when
1781 the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1782 in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1783
1784 If you use either the managed buffer allocation mode or the standard
1785 API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1786 these fields are set by the ALSA middle layer, and you should *not*
1787 change them by yourself. You can read them but not write them. On the
1788 other hand, if you want to allocate the buffer by yourself, you'll
1789 need to manage it in hw_params callback. At least, ``dma_bytes`` is
1790 mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1791 your driver doesn't support mmap, this field is not
1792 necessary. ``dma_addr`` is also optional. You can use dma_private as
1793 you like, too.
1794
1795 Running Status
1796 ~~~~~~~~~~~~~~
1797
1798 The running status can be referred via ``runtime->status``. This is
1799 the pointer to the struct snd_pcm_mmap_status record.
1800 For example, you can get the current
1801 DMA hardware pointer via ``runtime->status->hw_ptr``.
1802
1803 The DMA application pointer can be referred via ``runtime->control``,
1804 which points to the struct snd_pcm_mmap_control record.
1805 However, accessing directly to this value is not recommended.
1806
1807 Private Data
1808 ~~~~~~~~~~~~
1809
1810 You can allocate a record for the substream and store it in
1811 ``runtime->private_data``. Usually, this is done in the `PCM open
1812 callback`_. Don't mix this with ``pcm->private_data``. The
1813 ``pcm->private_data`` usually points to the chip instance assigned
1814 statically at the creation of PCM, while the ``runtime->private_data``
1815 points to a dynamic data structure created at the PCM open
1816 callback.
1817
1818 ::
1819
1820   static int snd_xxx_open(struct snd_pcm_substream *substream)
1821   {
1822           struct my_pcm_data *data;
1823           ....
1824           data = kmalloc(sizeof(*data), GFP_KERNEL);
1825           substream->runtime->private_data = data;
1826           ....
1827   }
1828
1829
1830 The allocated object must be released in the `close callback`_.
1831
1832 Operators
1833 ---------
1834
1835 OK, now let me give details about each pcm callback (``ops``). In
1836 general, every callback must return 0 if successful, or a negative
1837 error number such as ``-EINVAL``. To choose an appropriate error
1838 number, it is advised to check what value other parts of the kernel
1839 return when the same kind of request fails.
1840
1841 The callback function takes at least the argument with
1842 struct snd_pcm_substream pointer. To retrieve the chip
1843 record from the given substream instance, you can use the following
1844 macro.
1845
1846 ::
1847
1848   int xxx() {
1849           struct mychip *chip = snd_pcm_substream_chip(substream);
1850           ....
1851   }
1852
1853 The macro reads ``substream->private_data``, which is a copy of
1854 ``pcm->private_data``. You can override the former if you need to
1855 assign different data records per PCM substream. For example, the
1856 cmi8330 driver assigns different ``private_data`` for playback and
1857 capture directions, because it uses two different codecs (SB- and
1858 AD-compatible) for different directions.
1859
1860 PCM open callback
1861 ~~~~~~~~~~~~~~~~~
1862
1863 ::
1864
1865   static int snd_xxx_open(struct snd_pcm_substream *substream);
1866
1867 This is called when a pcm substream is opened.
1868
1869 At least, here you have to initialize the ``runtime->hw``
1870 record. Typically, this is done by like this:
1871
1872 ::
1873
1874   static int snd_xxx_open(struct snd_pcm_substream *substream)
1875   {
1876           struct mychip *chip = snd_pcm_substream_chip(substream);
1877           struct snd_pcm_runtime *runtime = substream->runtime;
1878
1879           runtime->hw = snd_mychip_playback_hw;
1880           return 0;
1881   }
1882
1883 where ``snd_mychip_playback_hw`` is the pre-defined hardware
1884 description.
1885
1886 You can allocate a private data in this callback, as described in
1887 `Private Data`_ section.
1888
1889 If the hardware configuration needs more constraints, set the hardware
1890 constraints here, too. See Constraints_ for more details.
1891
1892 close callback
1893 ~~~~~~~~~~~~~~
1894
1895 ::
1896
1897   static int snd_xxx_close(struct snd_pcm_substream *substream);
1898
1899
1900 Obviously, this is called when a pcm substream is closed.
1901
1902 Any private instance for a pcm substream allocated in the ``open``
1903 callback will be released here.
1904
1905 ::
1906
1907   static int snd_xxx_close(struct snd_pcm_substream *substream)
1908   {
1909           ....
1910           kfree(substream->runtime->private_data);
1911           ....
1912   }
1913
1914 ioctl callback
1915 ~~~~~~~~~~~~~~
1916
1917 This is used for any special call to pcm ioctls. But usually you can
1918 leave it as NULL, then PCM core calls the generic ioctl callback
1919 function :c:func:`snd_pcm_lib_ioctl()`.  If you need to deal with the
1920 unique setup of channel info or reset procedure, you can pass your own
1921 callback function here.
1922
1923 hw_params callback
1924 ~~~~~~~~~~~~~~~~~~~
1925
1926 ::
1927
1928   static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1929                                struct snd_pcm_hw_params *hw_params);
1930
1931 This is called when the hardware parameter (``hw_params``) is set up
1932 by the application, that is, once when the buffer size, the period
1933 size, the format, etc. are defined for the pcm substream.
1934
1935 Many hardware setups should be done in this callback, including the
1936 allocation of buffers.
1937
1938 Parameters to be initialized are retrieved by
1939 :c:func:`params_xxx()` macros.
1940
1941 When you set up the managed buffer allocation mode for the substream,
1942 a buffer is already allocated before this callback gets
1943 called. Alternatively, you can call a helper function below for
1944 allocating the buffer, too.
1945
1946 ::
1947
1948   snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1949
1950 :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1951 DMA buffers have been pre-allocated. See the section `Buffer Types`_
1952 for more details.
1953
1954 Note that this and ``prepare`` callbacks may be called multiple times
1955 per initialization. For example, the OSS emulation may call these
1956 callbacks at each change via its ioctl.
1957
1958 Thus, you need to be careful not to allocate the same buffers many
1959 times, which will lead to memory leaks! Calling the helper function
1960 above many times is OK. It will release the previous buffer
1961 automatically when it was already allocated.
1962
1963 Another note is that this callback is non-atomic (schedulable) as
1964 default, i.e. when no ``nonatomic`` flag set. This is important,
1965 because the ``trigger`` callback is atomic (non-schedulable). That is,
1966 mutexes or any schedule-related functions are not available in
1967 ``trigger`` callback. Please see the subsection Atomicity_ for
1968 details.
1969
1970 hw_free callback
1971 ~~~~~~~~~~~~~~~~~
1972
1973 ::
1974
1975   static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1976
1977 This is called to release the resources allocated via
1978 ``hw_params``.
1979
1980 This function is always called before the close callback is called.
1981 Also, the callback may be called multiple times, too. Keep track
1982 whether the resource was already released.
1983
1984 When you have set up the managed buffer allocation mode for the PCM
1985 substream, the allocated PCM buffer will be automatically released
1986 after this callback gets called.  Otherwise you'll have to release the
1987 buffer manually.  Typically, when the buffer was allocated from the
1988 pre-allocated pool, you can use the standard API function
1989 :c:func:`snd_pcm_lib_malloc_pages()` like:
1990
1991 ::
1992
1993   snd_pcm_lib_free_pages(substream);
1994
1995 prepare callback
1996 ~~~~~~~~~~~~~~~~
1997
1998 ::
1999
2000   static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2001
2002 This callback is called when the pcm is “prepared”. You can set the
2003 format type, sample rate, etc. here. The difference from ``hw_params``
2004 is that the ``prepare`` callback will be called each time
2005 :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2006 underruns, etc.
2007
2008 Note that this callback is now non-atomic. You can use
2009 schedule-related functions safely in this callback.
2010
2011 In this and the following callbacks, you can refer to the values via
2012 the runtime record, ``substream->runtime``. For example, to get the
2013 current rate, format or channels, access to ``runtime->rate``,
2014 ``runtime->format`` or ``runtime->channels``, respectively. The
2015 physical address of the allocated buffer is set to
2016 ``runtime->dma_area``. The buffer and period sizes are in
2017 ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
2018
2019 Be careful that this callback will be called many times at each setup,
2020 too.
2021
2022 trigger callback
2023 ~~~~~~~~~~~~~~~~
2024
2025 ::
2026
2027   static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2028
2029 This is called when the pcm is started, stopped or paused.
2030
2031 Which action is specified in the second argument,
2032 ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2033 and ``STOP`` commands must be defined in this callback.
2034
2035 ::
2036
2037   switch (cmd) {
2038   case SNDRV_PCM_TRIGGER_START:
2039           /* do something to start the PCM engine */
2040           break;
2041   case SNDRV_PCM_TRIGGER_STOP:
2042           /* do something to stop the PCM engine */
2043           break;
2044   default:
2045           return -EINVAL;
2046   }
2047
2048 When the pcm supports the pause operation (given in the info field of
2049 the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2050 must be handled here, too. The former is the command to pause the pcm,
2051 and the latter to restart the pcm again.
2052
2053 When the pcm supports the suspend/resume operation, regardless of full
2054 or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2055 commands must be handled, too. These commands are issued when the
2056 power-management status is changed. Obviously, the ``SUSPEND`` and
2057 ``RESUME`` commands suspend and resume the pcm substream, and usually,
2058 they are identical to the ``STOP`` and ``START`` commands, respectively.
2059 See the `Power Management`_ section for details.
2060
2061 As mentioned, this callback is atomic as default unless ``nonatomic``
2062 flag set, and you cannot call functions which may sleep. The
2063 ``trigger`` callback should be as minimal as possible, just really
2064 triggering the DMA. The other stuff should be initialized
2065 ``hw_params`` and ``prepare`` callbacks properly beforehand.
2066
2067 sync_stop callback
2068 ~~~~~~~~~~~~~~~~~~
2069
2070 ::
2071
2072   static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
2073
2074 This callback is optional, and NULL can be passed.  It's called after
2075 the PCM core stops the stream and changes the stream state
2076 ``prepare``, ``hw_params`` or ``hw_free``.
2077 Since the IRQ handler might be still pending, we need to wait until
2078 the pending task finishes before moving to the next step; otherwise it
2079 might lead to a crash due to resource conflicts or access to the freed
2080 resources.  A typical behavior is to call a synchronization function
2081 like :c:func:`synchronize_irq()` here.
2082
2083 For majority of drivers that need only a call of
2084 :c:func:`synchronize_irq()`, there is a simpler setup, too.
2085 While keeping NULL to ``sync_stop`` PCM callback, the driver can set
2086 ``card->sync_irq`` field to store the valid interrupt number after
2087 requesting an IRQ, instead.   Then PCM core will look call
2088 :c:func:`synchronize_irq()` with the given IRQ appropriately.
2089
2090 If the IRQ handler is released at the card destructor, you don't need
2091 to clear ``card->sync_irq``, as the card itself is being released.
2092 So, usually you'll need to add just a single line for assigning
2093 ``card->sync_irq`` in the driver code unless the driver re-acquires
2094 the IRQ.  When the driver frees and re-acquires the IRQ dynamically
2095 (e.g. for suspend/resume), it needs to clear and re-set
2096 ``card->sync_irq`` again appropriately.
2097
2098 pointer callback
2099 ~~~~~~~~~~~~~~~~
2100
2101 ::
2102
2103   static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2104
2105 This callback is called when the PCM middle layer inquires the current
2106 hardware position on the buffer. The position must be returned in
2107 frames, ranging from 0 to ``buffer_size - 1``. 
2108
2109 This is called usually from the buffer-update routine in the pcm
2110 middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2111 is called in the interrupt routine. Then the pcm middle layer updates
2112 the position and calculates the available space, and wakes up the
2113 sleeping poll threads, etc.
2114
2115 This callback is also atomic as default.
2116
2117 copy_user, copy_kernel and fill_silence ops
2118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2119
2120 These callbacks are not mandatory, and can be omitted in most cases.
2121 These callbacks are used when the hardware buffer cannot be in the
2122 normal memory space. Some chips have their own buffer on the hardware
2123 which is not mappable. In such a case, you have to transfer the data
2124 manually from the memory buffer to the hardware buffer. Or, if the
2125 buffer is non-contiguous on both physical and virtual memory spaces,
2126 these callbacks must be defined, too.
2127
2128 If these two callbacks are defined, copy and set-silence operations
2129 are done by them. The detailed will be described in the later section
2130 `Buffer and Memory Management`_.
2131
2132 ack callback
2133 ~~~~~~~~~~~~
2134
2135 This callback is also not mandatory. This callback is called when the
2136 ``appl_ptr`` is updated in read or write operations. Some drivers like
2137 emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2138 internal buffer, and this callback is useful only for such a purpose.
2139
2140 This callback is atomic as default.
2141
2142 page callback
2143 ~~~~~~~~~~~~~
2144
2145 This callback is optional too. The mmap calls this callback to get the
2146 page fault address.
2147
2148 Since the recent changes, you need no special callback any longer for
2149 the standard SG-buffer or vmalloc-buffer. Hence this callback should
2150 be rarely used.
2151
2152 mmap calllback
2153 ~~~~~~~~~~~~~~
2154
2155 This is another optional callback for controlling mmap behavior.
2156 Once when defined, PCM core calls this callback when a page is
2157 memory-mapped instead of dealing via the standard helper.
2158 If you need special handling (due to some architecture or
2159 device-specific issues), implement everything here as you like.
2160
2161
2162 PCM Interrupt Handler
2163 ---------------------
2164
2165 The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2166 interrupt handler in the sound driver is to update the buffer position
2167 and to tell the PCM middle layer when the buffer position goes across
2168 the prescribed period size. To inform this, call the
2169 :c:func:`snd_pcm_period_elapsed()` function.
2170
2171 There are several types of sound chips to generate the interrupts.
2172
2173 Interrupts at the period (fragment) boundary
2174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2175
2176 This is the most frequently found type: the hardware generates an
2177 interrupt at each period boundary. In this case, you can call
2178 :c:func:`snd_pcm_period_elapsed()` at each interrupt.
2179
2180 :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2181 its argument. Thus, you need to keep the substream pointer accessible
2182 from the chip instance. For example, define ``substream`` field in the
2183 chip record to hold the current running substream pointer, and set the
2184 pointer value at ``open`` callback (and reset at ``close`` callback).
2185
2186 If you acquire a spinlock in the interrupt handler, and the lock is used
2187 in other pcm callbacks, too, then you have to release the lock before
2188 calling :c:func:`snd_pcm_period_elapsed()`, because
2189 :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2190 inside.
2191
2192 Typical code would be like:
2193
2194 ::
2195
2196
2197       static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2198       {
2199               struct mychip *chip = dev_id;
2200               spin_lock(&chip->lock);
2201               ....
2202               if (pcm_irq_invoked(chip)) {
2203                       /* call updater, unlock before it */
2204                       spin_unlock(&chip->lock);
2205                       snd_pcm_period_elapsed(chip->substream);
2206                       spin_lock(&chip->lock);
2207                       /* acknowledge the interrupt if necessary */
2208               }
2209               ....
2210               spin_unlock(&chip->lock);
2211               return IRQ_HANDLED;
2212       }
2213
2214
2215
2216 High frequency timer interrupts
2217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2218
2219 This happens when the hardware doesn't generate interrupts at the period
2220 boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2221 or ymfpci drivers). In this case, you need to check the current hardware
2222 position and accumulate the processed sample length at each interrupt.
2223 When the accumulated size exceeds the period size, call
2224 :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2225
2226 Typical code would be like the following.
2227
2228 ::
2229
2230
2231       static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2232       {
2233               struct mychip *chip = dev_id;
2234               spin_lock(&chip->lock);
2235               ....
2236               if (pcm_irq_invoked(chip)) {
2237                       unsigned int last_ptr, size;
2238                       /* get the current hardware pointer (in frames) */
2239                       last_ptr = get_hw_ptr(chip);
2240                       /* calculate the processed frames since the
2241                        * last update
2242                        */
2243                       if (last_ptr < chip->last_ptr)
2244                               size = runtime->buffer_size + last_ptr
2245                                        - chip->last_ptr;
2246                       else
2247                               size = last_ptr - chip->last_ptr;
2248                       /* remember the last updated point */
2249                       chip->last_ptr = last_ptr;
2250                       /* accumulate the size */
2251                       chip->size += size;
2252                       /* over the period boundary? */
2253                       if (chip->size >= runtime->period_size) {
2254                               /* reset the accumulator */
2255                               chip->size %= runtime->period_size;
2256                               /* call updater */
2257                               spin_unlock(&chip->lock);
2258                               snd_pcm_period_elapsed(substream);
2259                               spin_lock(&chip->lock);
2260                       }
2261                       /* acknowledge the interrupt if necessary */
2262               }
2263               ....
2264               spin_unlock(&chip->lock);
2265               return IRQ_HANDLED;
2266       }
2267
2268
2269
2270 On calling :c:func:`snd_pcm_period_elapsed()`
2271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2272
2273 In both cases, even if more than one period are elapsed, you don't have
2274 to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2275 once. And the pcm layer will check the current hardware pointer and
2276 update to the latest status.
2277
2278 Atomicity
2279 ---------
2280
2281 One of the most important (and thus difficult to debug) problems in
2282 kernel programming are race conditions. In the Linux kernel, they are
2283 usually avoided via spin-locks, mutexes or semaphores. In general, if a
2284 race condition can happen in an interrupt handler, it has to be managed
2285 atomically, and you have to use a spinlock to protect the critical
2286 session. If the critical section is not in interrupt handler code and if
2287 taking a relatively long time to execute is acceptable, you should use
2288 mutexes or semaphores instead.
2289
2290 As already seen, some pcm callbacks are atomic and some are not. For
2291 example, the ``hw_params`` callback is non-atomic, while ``trigger``
2292 callback is atomic. This means, the latter is called already in a
2293 spinlock held by the PCM middle layer. Please take this atomicity into
2294 account when you choose a locking scheme in the callbacks.
2295
2296 In the atomic callbacks, you cannot use functions which may call
2297 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2298 mutexes can sleep, and hence they cannot be used inside the atomic
2299 callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2300 callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2301
2302 All three atomic callbacks (trigger, pointer, and ack) are called with
2303 local interrupts disabled.
2304
2305 The recent changes in PCM core code, however, allow all PCM operations
2306 to be non-atomic. This assumes that the all caller sides are in
2307 non-atomic contexts. For example, the function
2308 :c:func:`snd_pcm_period_elapsed()` is called typically from the
2309 interrupt handler. But, if you set up the driver to use a threaded
2310 interrupt handler, this call can be in non-atomic context, too. In such
2311 a case, you can set ``nonatomic`` filed of struct snd_pcm object
2312 after creating it. When this flag is set, mutex and rwsem are used internally
2313 in the PCM core instead of spin and rwlocks, so that you can call all PCM
2314 functions safely in a non-atomic
2315 context.
2316
2317 Constraints
2318 -----------
2319
2320 If your chip supports unconventional sample rates, or only the limited
2321 samples, you need to set a constraint for the condition.
2322
2323 For example, in order to restrict the sample rates in the some supported
2324 values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2325 call this function in the open callback.
2326
2327 ::
2328
2329       static unsigned int rates[] =
2330               {4000, 10000, 22050, 44100};
2331       static struct snd_pcm_hw_constraint_list constraints_rates = {
2332               .count = ARRAY_SIZE(rates),
2333               .list = rates,
2334               .mask = 0,
2335       };
2336
2337       static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2338       {
2339               int err;
2340               ....
2341               err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2342                                                SNDRV_PCM_HW_PARAM_RATE,
2343                                                &constraints_rates);
2344               if (err < 0)
2345                       return err;
2346               ....
2347       }
2348
2349
2350
2351 There are many different constraints. Look at ``sound/pcm.h`` for a
2352 complete list. You can even define your own constraint rules. For
2353 example, let's suppose my_chip can manage a substream of 1 channel if
2354 and only if the format is ``S16_LE``, otherwise it supports any format
2355 specified in struct snd_pcm_hardware> (or in any other
2356 constraint_list). You can build a rule like this:
2357
2358 ::
2359
2360       static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2361                                             struct snd_pcm_hw_rule *rule)
2362       {
2363               struct snd_interval *c = hw_param_interval(params,
2364                             SNDRV_PCM_HW_PARAM_CHANNELS);
2365               struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2366               struct snd_interval ch;
2367
2368               snd_interval_any(&ch);
2369               if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2370                       ch.min = ch.max = 1;
2371                       ch.integer = 1;
2372                       return snd_interval_refine(c, &ch);
2373               }
2374               return 0;
2375       }
2376
2377
2378 Then you need to call this function to add your rule:
2379
2380 ::
2381
2382   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2383                       hw_rule_channels_by_format, NULL,
2384                       SNDRV_PCM_HW_PARAM_FORMAT, -1);
2385
2386 The rule function is called when an application sets the PCM format, and
2387 it refines the number of channels accordingly. But an application may
2388 set the number of channels before setting the format. Thus you also need
2389 to define the inverse rule:
2390
2391 ::
2392
2393       static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2394                                             struct snd_pcm_hw_rule *rule)
2395       {
2396               struct snd_interval *c = hw_param_interval(params,
2397                     SNDRV_PCM_HW_PARAM_CHANNELS);
2398               struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2399               struct snd_mask fmt;
2400
2401               snd_mask_any(&fmt);    /* Init the struct */
2402               if (c->min < 2) {
2403                       fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2404                       return snd_mask_refine(f, &fmt);
2405               }
2406               return 0;
2407       }
2408
2409
2410 ... and in the open callback:
2411
2412 ::
2413
2414   snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2415                       hw_rule_format_by_channels, NULL,
2416                       SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2417
2418 One typical usage of the hw constraints is to align the buffer size
2419 with the period size.  As default, ALSA PCM core doesn't enforce the
2420 buffer size to be aligned with the period size.  For example, it'd be
2421 possible to have a combination like 256 period bytes with 999 buffer
2422 bytes.
2423
2424 Many device chips, however, require the buffer to be a multiple of
2425 periods.  In such a case, call
2426 :c:func:`snd_pcm_hw_constraint_integer()` for
2427 ``SNDRV_PCM_HW_PARAM_PERIODS``.
2428
2429 ::
2430
2431   snd_pcm_hw_constraint_integer(substream->runtime,
2432                                 SNDRV_PCM_HW_PARAM_PERIODS);
2433
2434 This assures that the number of periods is integer, hence the buffer
2435 size is aligned with the period size.
2436
2437 The hw constraint is a very much powerful mechanism to define the
2438 preferred PCM configuration, and there are relevant helpers.
2439 I won't give more details here, rather I would like to say, “Luke, use
2440 the source.”
2441
2442 Control Interface
2443 =================
2444
2445 General
2446 -------
2447
2448 The control interface is used widely for many switches, sliders, etc.
2449 which are accessed from user-space. Its most important use is the mixer
2450 interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2451 implemented on the control kernel API.
2452
2453 ALSA has a well-defined AC97 control module. If your chip supports only
2454 the AC97 and nothing else, you can skip this section.
2455
2456 The control API is defined in ``<sound/control.h>``. Include this file
2457 if you want to add your own controls.
2458
2459 Definition of Controls
2460 ----------------------
2461
2462 To create a new control, you need to define the following three
2463 callbacks: ``info``, ``get`` and ``put``. Then, define a
2464 struct snd_kcontrol_new record, such as:
2465
2466 ::
2467
2468
2469       static struct snd_kcontrol_new my_control = {
2470               .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2471               .name = "PCM Playback Switch",
2472               .index = 0,
2473               .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2474               .private_value = 0xffff,
2475               .info = my_control_info,
2476               .get = my_control_get,
2477               .put = my_control_put
2478       };
2479
2480
2481 The ``iface`` field specifies the control type,
2482 ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2483 for global controls that are not logically part of the mixer. If the
2484 control is closely associated with some specific device on the sound
2485 card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2486 and specify the device number with the ``device`` and ``subdevice``
2487 fields.
2488
2489 The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2490 control name is very important, because its role is classified from
2491 its name. There are pre-defined standard control names. The details
2492 are described in the `Control Names`_ subsection.
2493
2494 The ``index`` field holds the index number of this control. If there
2495 are several different controls with the same name, they can be
2496 distinguished by the index number. This is the case when several
2497 codecs exist on the card. If the index is zero, you can omit the
2498 definition above. 
2499
2500 The ``access`` field contains the access type of this control. Give
2501 the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2502 there. The details will be explained in the `Access Flags`_
2503 subsection.
2504
2505 The ``private_value`` field contains an arbitrary long integer value
2506 for this record. When using the generic ``info``, ``get`` and ``put``
2507 callbacks, you can pass a value through this field. If several small
2508 numbers are necessary, you can combine them in bitwise. Or, it's
2509 possible to give a pointer (casted to unsigned long) of some record to
2510 this field, too. 
2511
2512 The ``tlv`` field can be used to provide metadata about the control;
2513 see the `Metadata`_ subsection.
2514
2515 The other three are `Control Callbacks`_.
2516
2517 Control Names
2518 -------------
2519
2520 There are some standards to define the control names. A control is
2521 usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2522
2523 The first, ``SOURCE``, specifies the source of the control, and is a
2524 string such as “Master”, “PCM”, “CD” and “Line”. There are many
2525 pre-defined sources.
2526
2527 The second, ``DIRECTION``, is one of the following strings according to
2528 the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2529 and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2530 capture directions.
2531
2532 The third, ``FUNCTION``, is one of the following strings according to
2533 the function of the control: “Switch”, “Volume” and “Route”.
2534
2535 The example of control names are, thus, “Master Capture Switch” or “PCM
2536 Playback Volume”.
2537
2538 There are some exceptions:
2539
2540 Global capture and playback
2541 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2542
2543 “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2544 global capture (input) source, switch and volume. Similarly, “Playback
2545 Switch” and “Playback Volume” are used for the global output gain switch
2546 and volume.
2547
2548 Tone-controls
2549 ~~~~~~~~~~~~~
2550
2551 tone-control switch and volumes are specified like “Tone Control - XXX”,
2552 e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2553 Center”.
2554
2555 3D controls
2556 ~~~~~~~~~~~
2557
2558 3D-control switches and volumes are specified like “3D Control - XXX”,
2559 e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2560
2561 Mic boost
2562 ~~~~~~~~~
2563
2564 Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2565
2566 More precise information can be found in
2567 ``Documentation/sound/designs/control-names.rst``.
2568
2569 Access Flags
2570 ------------
2571
2572 The access flag is the bitmask which specifies the access type of the
2573 given control. The default access type is
2574 ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2575 allowed to this control. When the access flag is omitted (i.e. = 0), it
2576 is considered as ``READWRITE`` access as default.
2577
2578 When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2579 instead. In this case, you don't have to define the ``put`` callback.
2580 Similarly, when the control is write-only (although it's a rare case),
2581 you can use the ``WRITE`` flag instead, and you don't need the ``get``
2582 callback.
2583
2584 If the control value changes frequently (e.g. the VU meter),
2585 ``VOLATILE`` flag should be given. This means that the control may be
2586 changed without `Change notification`_. Applications should poll such
2587 a control constantly.
2588
2589 When the control is inactive, set the ``INACTIVE`` flag, too. There are
2590 ``LOCK`` and ``OWNER`` flags to change the write permissions.
2591
2592 Control Callbacks
2593 -----------------
2594
2595 info callback
2596 ~~~~~~~~~~~~~
2597
2598 The ``info`` callback is used to get detailed information on this
2599 control. This must store the values of the given
2600 struct snd_ctl_elem_info object. For example,
2601 for a boolean control with a single element:
2602
2603 ::
2604
2605
2606       static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2607                               struct snd_ctl_elem_info *uinfo)
2608       {
2609               uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2610               uinfo->count = 1;
2611               uinfo->value.integer.min = 0;
2612               uinfo->value.integer.max = 1;
2613               return 0;
2614       }
2615
2616
2617
2618 The ``type`` field specifies the type of the control. There are
2619 ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2620 ``INTEGER64``. The ``count`` field specifies the number of elements in
2621 this control. For example, a stereo volume would have count = 2. The
2622 ``value`` field is a union, and the values stored are depending on the
2623 type. The boolean and integer types are identical.
2624
2625 The enumerated type is a bit different from others. You'll need to set
2626 the string for the currently given item index.
2627
2628 ::
2629
2630   static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2631                           struct snd_ctl_elem_info *uinfo)
2632   {
2633           static char *texts[4] = {
2634                   "First", "Second", "Third", "Fourth"
2635           };
2636           uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2637           uinfo->count = 1;
2638           uinfo->value.enumerated.items = 4;
2639           if (uinfo->value.enumerated.item > 3)
2640                   uinfo->value.enumerated.item = 3;
2641           strcpy(uinfo->value.enumerated.name,
2642                  texts[uinfo->value.enumerated.item]);
2643           return 0;
2644   }
2645
2646 The above callback can be simplified with a helper function,
2647 :c:func:`snd_ctl_enum_info()`. The final code looks like below.
2648 (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2649 it's a matter of taste.)
2650
2651 ::
2652
2653   static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2654                           struct snd_ctl_elem_info *uinfo)
2655   {
2656           static char *texts[4] = {
2657                   "First", "Second", "Third", "Fourth"
2658           };
2659           return snd_ctl_enum_info(uinfo, 1, 4, texts);
2660   }
2661
2662
2663 Some common info callbacks are available for your convenience:
2664 :c:func:`snd_ctl_boolean_mono_info()` and
2665 :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2666 is an info callback for a mono channel boolean item, just like
2667 :c:func:`snd_myctl_mono_info()` above, and the latter is for a
2668 stereo channel boolean item.
2669
2670 get callback
2671 ~~~~~~~~~~~~
2672
2673 This callback is used to read the current value of the control and to
2674 return to user-space.
2675
2676 For example,
2677
2678 ::
2679
2680
2681       static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2682                                struct snd_ctl_elem_value *ucontrol)
2683       {
2684               struct mychip *chip = snd_kcontrol_chip(kcontrol);
2685               ucontrol->value.integer.value[0] = get_some_value(chip);
2686               return 0;
2687       }
2688
2689
2690
2691 The ``value`` field depends on the type of control as well as on the
2692 info callback. For example, the sb driver uses this field to store the
2693 register offset, the bit-shift and the bit-mask. The ``private_value``
2694 field is set as follows:
2695
2696 ::
2697
2698   .private_value = reg | (shift << 16) | (mask << 24)
2699
2700 and is retrieved in callbacks like
2701
2702 ::
2703
2704   static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2705                                     struct snd_ctl_elem_value *ucontrol)
2706   {
2707           int reg = kcontrol->private_value & 0xff;
2708           int shift = (kcontrol->private_value >> 16) & 0xff;
2709           int mask = (kcontrol->private_value >> 24) & 0xff;
2710           ....
2711   }
2712
2713 In the ``get`` callback, you have to fill all the elements if the
2714 control has more than one elements, i.e. ``count > 1``. In the example
2715 above, we filled only one element (``value.integer.value[0]``) since
2716 it's assumed as ``count = 1``.
2717
2718 put callback
2719 ~~~~~~~~~~~~
2720
2721 This callback is used to write a value from user-space.
2722
2723 For example,
2724
2725 ::
2726
2727
2728       static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2729                                struct snd_ctl_elem_value *ucontrol)
2730       {
2731               struct mychip *chip = snd_kcontrol_chip(kcontrol);
2732               int changed = 0;
2733               if (chip->current_value !=
2734                    ucontrol->value.integer.value[0]) {
2735                       change_current_value(chip,
2736                                   ucontrol->value.integer.value[0]);
2737                       changed = 1;
2738               }
2739               return changed;
2740       }
2741
2742
2743
2744 As seen above, you have to return 1 if the value is changed. If the
2745 value is not changed, return 0 instead. If any fatal error happens,
2746 return a negative error code as usual.
2747
2748 As in the ``get`` callback, when the control has more than one
2749 elements, all elements must be evaluated in this callback, too.
2750
2751 Callbacks are not atomic
2752 ~~~~~~~~~~~~~~~~~~~~~~~~
2753
2754 All these three callbacks are basically not atomic.
2755
2756 Control Constructor
2757 -------------------
2758
2759 When everything is ready, finally we can create a new control. To create
2760 a control, there are two functions to be called,
2761 :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2762
2763 In the simplest way, you can do like this:
2764
2765 ::
2766
2767   err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2768   if (err < 0)
2769           return err;
2770
2771 where ``my_control`` is the struct snd_kcontrol_new object defined above,
2772 and chip is the object pointer to be passed to kcontrol->private_data which
2773 can be referred to in callbacks.
2774
2775 :c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
2776 :c:func:`snd_ctl_add()` assigns the given control component to the
2777 card.
2778
2779 Change Notification
2780 -------------------
2781
2782 If you need to change and update a control in the interrupt routine, you
2783 can call :c:func:`snd_ctl_notify()`. For example,
2784
2785 ::
2786
2787   snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2788
2789 This function takes the card pointer, the event-mask, and the control id
2790 pointer for the notification. The event-mask specifies the types of
2791 notification, for example, in the above example, the change of control
2792 values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
2793 to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2794 for hardware volume interrupts.
2795
2796 Metadata
2797 --------
2798
2799 To provide information about the dB values of a mixer control, use on of
2800 the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2801 variable containing this information, set the ``tlv.p`` field to point to
2802 this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2803 in the ``access`` field; like this:
2804
2805 ::
2806
2807   static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2808
2809   static struct snd_kcontrol_new my_control = {
2810           ...
2811           .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2812                     SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2813           ...
2814           .tlv.p = db_scale_my_control,
2815   };
2816
2817
2818 The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2819 about a mixer control where each step in the control's value changes the
2820 dB value by a constant dB amount. The first parameter is the name of the
2821 variable to be defined. The second parameter is the minimum value, in
2822 units of 0.01 dB. The third parameter is the step size, in units of 0.01
2823 dB. Set the fourth parameter to 1 if the minimum value actually mutes
2824 the control.
2825
2826 The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2827 about a mixer control where the control's value affects the output
2828 linearly. The first parameter is the name of the variable to be defined.
2829 The second parameter is the minimum value, in units of 0.01 dB. The
2830 third parameter is the maximum value, in units of 0.01 dB. If the
2831 minimum value mutes the control, set the second parameter to
2832 ``TLV_DB_GAIN_MUTE``.
2833
2834 API for AC97 Codec
2835 ==================
2836
2837 General
2838 -------
2839
2840 The ALSA AC97 codec layer is a well-defined one, and you don't have to
2841 write much code to control it. Only low-level control routines are
2842 necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2843
2844 Full Code Example
2845 -----------------
2846
2847 ::
2848
2849       struct mychip {
2850               ....
2851               struct snd_ac97 *ac97;
2852               ....
2853       };
2854
2855       static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2856                                                  unsigned short reg)
2857       {
2858               struct mychip *chip = ac97->private_data;
2859               ....
2860               /* read a register value here from the codec */
2861               return the_register_value;
2862       }
2863
2864       static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2865                                        unsigned short reg, unsigned short val)
2866       {
2867               struct mychip *chip = ac97->private_data;
2868               ....
2869               /* write the given register value to the codec */
2870       }
2871
2872       static int snd_mychip_ac97(struct mychip *chip)
2873       {
2874               struct snd_ac97_bus *bus;
2875               struct snd_ac97_template ac97;
2876               int err;
2877               static struct snd_ac97_bus_ops ops = {
2878                       .write = snd_mychip_ac97_write,
2879                       .read = snd_mychip_ac97_read,
2880               };
2881
2882               err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2883               if (err < 0)
2884                       return err;
2885               memset(&ac97, 0, sizeof(ac97));
2886               ac97.private_data = chip;
2887               return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2888       }
2889
2890
2891 AC97 Constructor
2892 ----------------
2893
2894 To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2895 with an ``ac97_bus_ops_t`` record with callback functions.
2896
2897 ::
2898
2899   struct snd_ac97_bus *bus;
2900   static struct snd_ac97_bus_ops ops = {
2901         .write = snd_mychip_ac97_write,
2902         .read = snd_mychip_ac97_read,
2903   };
2904
2905   snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2906
2907 The bus record is shared among all belonging ac97 instances.
2908
2909 And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
2910 record together with the bus pointer created above.
2911
2912 ::
2913
2914   struct snd_ac97_template ac97;
2915   int err;
2916
2917   memset(&ac97, 0, sizeof(ac97));
2918   ac97.private_data = chip;
2919   snd_ac97_mixer(bus, &ac97, &chip->ac97);
2920
2921 where chip->ac97 is a pointer to a newly created ``ac97_t``
2922 instance. In this case, the chip pointer is set as the private data,
2923 so that the read/write callback functions can refer to this chip
2924 instance. This instance is not necessarily stored in the chip
2925 record. If you need to change the register values from the driver, or
2926 need the suspend/resume of ac97 codecs, keep this pointer to pass to
2927 the corresponding functions.
2928
2929 AC97 Callbacks
2930 --------------
2931
2932 The standard callbacks are ``read`` and ``write``. Obviously they
2933 correspond to the functions for read and write accesses to the
2934 hardware low-level codes.
2935
2936 The ``read`` callback returns the register value specified in the
2937 argument.
2938
2939 ::
2940
2941   static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2942                                              unsigned short reg)
2943   {
2944           struct mychip *chip = ac97->private_data;
2945           ....
2946           return the_register_value;
2947   }
2948
2949 Here, the chip can be cast from ``ac97->private_data``.
2950
2951 Meanwhile, the ``write`` callback is used to set the register
2952 value
2953
2954 ::
2955
2956   static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2957                        unsigned short reg, unsigned short val)
2958
2959
2960 These callbacks are non-atomic like the control API callbacks.
2961
2962 There are also other callbacks: ``reset``, ``wait`` and ``init``.
2963
2964 The ``reset`` callback is used to reset the codec. If the chip
2965 requires a special kind of reset, you can define this callback.
2966
2967 The ``wait`` callback is used to add some waiting time in the standard
2968 initialization of the codec. If the chip requires the extra waiting
2969 time, define this callback.
2970
2971 The ``init`` callback is used for additional initialization of the
2972 codec.
2973
2974 Updating Registers in The Driver
2975 --------------------------------
2976
2977 If you need to access to the codec from the driver, you can call the
2978 following functions: :c:func:`snd_ac97_write()`,
2979 :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2980 :c:func:`snd_ac97_update_bits()`.
2981
2982 Both :c:func:`snd_ac97_write()` and
2983 :c:func:`snd_ac97_update()` functions are used to set a value to
2984 the given register (``AC97_XXX``). The difference between them is that
2985 :c:func:`snd_ac97_update()` doesn't write a value if the given
2986 value has been already set, while :c:func:`snd_ac97_write()`
2987 always rewrites the value.
2988
2989 ::
2990
2991   snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2992   snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2993
2994 :c:func:`snd_ac97_read()` is used to read the value of the given
2995 register. For example,
2996
2997 ::
2998
2999   value = snd_ac97_read(ac97, AC97_MASTER);
3000
3001 :c:func:`snd_ac97_update_bits()` is used to update some bits in
3002 the given register.
3003
3004 ::
3005
3006   snd_ac97_update_bits(ac97, reg, mask, value);
3007
3008 Also, there is a function to change the sample rate (of a given register
3009 such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
3010 codec: :c:func:`snd_ac97_set_rate()`.
3011
3012 ::
3013
3014   snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
3015
3016
3017 The following registers are available to set the rate:
3018 ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
3019 ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
3020 specified, the register is not really changed but the corresponding
3021 IEC958 status bits will be updated.
3022
3023 Clock Adjustment
3024 ----------------
3025
3026 In some chips, the clock of the codec isn't 48000 but using a PCI clock
3027 (to save a quartz!). In this case, change the field ``bus->clock`` to
3028 the corresponding value. For example, intel8x0 and es1968 drivers have
3029 their own function to read from the clock.
3030
3031 Proc Files
3032 ----------
3033
3034 The ALSA AC97 interface will create a proc file such as
3035 ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
3036 can refer to these files to see the current status and registers of
3037 the codec.
3038
3039 Multiple Codecs
3040 ---------------
3041
3042 When there are several codecs on the same card, you need to call
3043 :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
3044 greater. The ``num`` field specifies the codec number.
3045
3046 If you set up multiple codecs, you either need to write different
3047 callbacks for each codec or check ``ac97->num`` in the callback
3048 routines.
3049
3050 MIDI (MPU401-UART) Interface
3051 ============================
3052
3053 General
3054 -------
3055
3056 Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3057 soundcard supports the standard MPU401-UART interface, most likely you
3058 can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3059 ``<sound/mpu401.h>``.
3060
3061 Some soundchips have a similar but slightly different implementation of
3062 mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3063
3064 MIDI Constructor
3065 ----------------
3066
3067 To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
3068
3069 ::
3070
3071   struct snd_rawmidi *rmidi;
3072   snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
3073                       irq, &rmidi);
3074
3075
3076 The first argument is the card pointer, and the second is the index of
3077 this component. You can create up to 8 rawmidi devices.
3078
3079 The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3080 it's not a special one, you can use ``MPU401_HW_MPU401``.
3081
3082 The 4th argument is the I/O port address. Many backward-compatible
3083 MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3084 PCI I/O region. It depends on the chip design.
3085
3086 The 5th argument is a bitflag for additional information. When the I/O
3087 port address above is part of the PCI I/O region, the MPU401 I/O port
3088 might have been already allocated (reserved) by the driver itself. In
3089 such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3090 mpu401-uart layer will allocate the I/O ports by itself.
3091
3092 When the controller supports only the input or output MIDI stream, pass
3093 the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3094 respectively. Then the rawmidi instance is created as a single stream.
3095
3096 ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
3097 (via readb and writeb) instead of iob and outb. In this case, you have
3098 to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3099
3100 When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3101 the default interrupt handler. The driver needs to call
3102 :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3103 processing the output stream in the irq handler.
3104
3105 If the MPU-401 interface shares its interrupt with the other logical
3106 devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3107 `below <MIDI Interrupt Handler_>`__).
3108
3109 Usually, the port address corresponds to the command port and port + 1
3110 corresponds to the data port. If not, you may change the ``cport``
3111 field of struct snd_mpu401 manually afterward.
3112 However, struct snd_mpu401 pointer is
3113 not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3114 need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
3115
3116 ::
3117
3118   struct snd_mpu401 *mpu;
3119   mpu = rmidi->private_data;
3120
3121 and reset the ``cport`` as you like:
3122
3123 ::
3124
3125   mpu->cport = my_own_control_port;
3126
3127 The 6th argument specifies the ISA irq number that will be allocated. If
3128 no interrupt is to be allocated (because your code is already allocating
3129 a shared interrupt, or because the device does not use interrupts), pass
3130 -1 instead. For a MPU-401 device without an interrupt, a polling timer
3131 will be used instead.
3132
3133 MIDI Interrupt Handler
3134 ----------------------
3135
3136 When the interrupt is allocated in
3137 :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3138 handler is automatically used, hence you don't have anything else to do
3139 than creating the mpu401 stuff. Otherwise, you have to set
3140 ``MPU401_INFO_IRQ_HOOK``, and call
3141 :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3142 interrupt handler when it has determined that a UART interrupt has
3143 occurred.
3144
3145 In this case, you need to pass the private_data of the returned rawmidi
3146 object from :c:func:`snd_mpu401_uart_new()` as the second
3147 argument of :c:func:`snd_mpu401_uart_interrupt()`.
3148
3149 ::
3150
3151   snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3152
3153
3154 RawMIDI Interface
3155 =================
3156
3157 Overview
3158 --------
3159
3160 The raw MIDI interface is used for hardware MIDI ports that can be
3161 accessed as a byte stream. It is not used for synthesizer chips that do
3162 not directly understand MIDI.
3163
3164 ALSA handles file and buffer management. All you have to do is to write
3165 some code to move data between the buffer and the hardware.
3166
3167 The rawmidi API is defined in ``<sound/rawmidi.h>``.
3168
3169 RawMIDI Constructor
3170 -------------------
3171
3172 To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3173 function:
3174
3175 ::
3176
3177   struct snd_rawmidi *rmidi;
3178   err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3179   if (err < 0)
3180           return err;
3181   rmidi->private_data = chip;
3182   strcpy(rmidi->name, "My MIDI");
3183   rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3184                       SNDRV_RAWMIDI_INFO_INPUT |
3185                       SNDRV_RAWMIDI_INFO_DUPLEX;
3186
3187 The first argument is the card pointer, the second argument is the ID
3188 string.
3189
3190 The third argument is the index of this component. You can create up to
3191 8 rawmidi devices.
3192
3193 The fourth and fifth arguments are the number of output and input
3194 substreams, respectively, of this device (a substream is the equivalent
3195 of a MIDI port).
3196
3197 Set the ``info_flags`` field to specify the capabilities of the