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