1======================
2Writing an ALSA Driver
3======================
4
5:Author: Takashi Iwai <tiwai@suse.de>
6
7Preface
8=======
9
10This document describes how to write an `ALSA (Advanced Linux Sound
11Architecture) <http://www.alsa-project.org/>`__ driver. The document
12focuses mainly on PCI soundcards. In the case of other device types, the
13API might be different, too. However, at least the ALSA kernel API is
14consistent, and therefore it would be still a bit help for writing them.
15
16This document targets people who already have enough C language skills
17and have basic linux kernel programming knowledge. This document doesn't
18explain the general topic of linux kernel coding and doesn't cover
19low-level driver implementation details. It only describes the standard
20way to write a PCI sound driver on ALSA.
21
22This document is still a draft version. Any feedback and corrections,
23please!!
24
25File Tree Structure
26===================
27
28General
29-------
30
31The 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
60core directory
61--------------
62
63This directory contains the middle layer which is the heart of ALSA
64drivers. In this directory, the native ALSA modules are stored. The
65sub-directories contain different modules and are dependent upon the
66kernel config.
67
68core/oss
69~~~~~~~~
70
71The codes for PCM and mixer OSS emulation modules are stored in this
72directory. The rawmidi OSS emulation is included in the ALSA rawmidi
73code since it's quite small. The sequencer code is stored in
74``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
75
76core/seq
77~~~~~~~~
78
79This directory and its sub-directories are for the ALSA sequencer. This
80directory contains the sequencer core and primary sequencer modules such
81like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
82``CONFIG_SND_SEQUENCER`` is set in the kernel config.
83
84core/seq/oss
85~~~~~~~~~~~~
86
87This contains the OSS sequencer emulation codes.
88
89include directory
90-----------------
91
92This is the place for the public header files of ALSA drivers, which are
93to be exported to user-space, or included by several files at different
94directories. Basically, the private header files should not be placed in
95this directory, but you may still find files there, due to historical
96reasons :)
97
98drivers directory
99-----------------
100
101This directory contains code shared among different drivers on different
102architectures. They are hence supposed not to be architecture-specific.
103For example, the dummy pcm driver and the serial MIDI driver are found
104in this directory. In the sub-directories, there is code for components
105which are independent from bus and cpu architectures.
106
107drivers/mpu401
108~~~~~~~~~~~~~~
109
110The MPU401 and MPU401-UART modules are stored here.
111
112drivers/opl3 and opl4
113~~~~~~~~~~~~~~~~~~~~~
114
115The OPL3 and OPL4 FM-synth stuff is found here.
116
117i2c directory
118-------------
119
120This contains the ALSA i2c components.
121
122Although there is a standard i2c layer on Linux, ALSA has its own i2c
123code for some cards, because the soundcard needs only a simple operation
124and the standard i2c API is too complicated for such a purpose.
125
126synth directory
127---------------
128
129This contains the synth middle-level modules.
130
131So far, there is only Emu8000/Emu10k1 synth driver under the
132``synth/emux`` sub-directory.
133
134pci directory
135-------------
136
137This directory and its sub-directories hold the top-level card modules
138for PCI soundcards and the code specific to the PCI BUS.
139
140The drivers compiled from a single file are stored directly in the pci
141directory, while the drivers with several source files are stored on
142their own sub-directory (e.g. emu10k1, ice1712).
143
144isa directory
145-------------
146
147This directory and its sub-directories hold the top-level card modules
148for ISA soundcards.
149
150arm, ppc, and sparc directories
151-------------------------------
152
153They are used for top-level card modules which are specific to one of
154these architectures.
155
156usb directory
157-------------
158
159This directory contains the USB-audio driver. In the latest version, the
160USB MIDI driver is integrated in the usb-audio driver.
161
162pcmcia directory
163----------------
164
165The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
166be in the pci directory, because their API is identical to that of
167standard PCI cards.
168
169soc directory
170-------------
171
172This directory contains the codes for ASoC (ALSA System on Chip)
173layer including ASoC core, codec and machine drivers.
174
175oss directory
176-------------
177
178Here contains OSS/Lite codes.
179All codes have been deprecated except for dmasound on m68k as of
180writing this.
181
182
183Basic Flow for PCI Drivers
184==========================
185
186Outline
187-------
188
189The 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
207Full Code Example
208-----------------
209
210The code example is shown below. Some parts are kept unimplemented at
211this moment but will be filled in the next sections. The numbers in the
212comment lines of the :c:func:`snd_mychip_probe()` function refer
213to 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
355Driver Constructor
356------------------
357
358The real constructor of PCI drivers is the ``probe`` callback. The
359``probe`` callback and other component-constructors which are called
360from the ``probe`` callback cannot be used with the ``__init`` prefix
361because any PCI device could be a hotplug device.
362
363In the ``probe`` callback, the following scheme is often used.
364
3651) 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
380where ``enable[dev]`` is the module option.
381
382Each time the ``probe`` callback is called, check the availability of
383the device. If not available, simply increment the device index and
384returns. dev will be incremented also later (`step 7
385<#set-the-pci-driver-data-and-return-zero>`__).
386
3872) 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
399The details will be explained in the section `Management of Cards and
400Components`_.
401
4023) Create a main component
403~~~~~~~~~~~~~~~~~~~~~~~~~~
404
405In 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
415The details will be explained in the section `PCI Resource
416Management`_.
417
418When something goes wrong, the probe function needs to deal with the
419error.  In this example, we have a single error handling path placed
420at the end of the function.
421
422::
423
424  error:
425          snd_card_free(card);
426	  return err;
427
428Since each component can be properly freed, the single
429:c:func:`snd_card_free()` call should suffice in most cases.
430
431
4324) 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
442The driver field holds the minimal ID string of the chip. This is used
443by alsa-lib's configurator, so keep it simple but unique. Even the
444same driver can have different driver IDs to distinguish the
445functionality of each chip type.
446
447The shortname field is a string shown as more verbose name. The longname
448field contains the information shown in ``/proc/asound/cards``.
449
4505) Create other components, such as mixer, MIDI, etc.
451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452
453Here you define the basic components such as `PCM <#PCM-Interface>`__,
454mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
455`MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
456Also, if you want a `proc file <#Proc-Interface>`__, define it here,
457too.
458
4596) Register the card instance.
460~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461
462::
463
464  err = snd_card_register(card);
465  if (err < 0)
466          goto error;
467
468Will be explained in the section `Management of Cards and
469Components`_, too.
470
4717) Set the PCI driver data and return zero.
472~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
473
474::
475
476  pci_set_drvdata(pci, card);
477  dev++;
478  return 0;
479
480In the above, the card record is stored. This pointer is used in the
481remove callback and power-management callbacks, too.
482
483Destructor
484----------
485
486The destructor, remove callback, simply releases the card instance. Then
487the ALSA middle layer will release all the attached components
488automatically.
489
490It 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
500The above code assumes that the card pointer is set to the PCI driver
501data.
502
503Header Files
504------------
505
506For the above example, at least the following include files are
507necessary.
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
517where the last one is necessary only when module options are defined
518in the source file. If the code is split into several files, the files
519without module options don't need them.
520
521In addition to these headers, you'll need ``<linux/interrupt.h>`` for
522interrupt 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
524to include ``<linux/delay.h>`` too.
525
526The 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
530Management of Cards and Components
531==================================
532
533Card Instance
534-------------
535
536For each soundcard, a “card” record must be allocated.
537
538A card record is the headquarters of the soundcard. It manages the whole
539list of devices (components) on the soundcard, such as PCM, mixers,
540MIDI, synthesizer, and so on. Also, the card record holds the ID and the
541name strings of the card, manages the root of proc files, and controls
542the power-management states and hotplug disconnections. The component
543list on the card record is used to manage the correct release of
544resources at destruction.
545
546As 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
556The function takes six arguments: the parent device pointer, the
557card-index number, the id string, the module pointer (usually
558``THIS_MODULE``), the size of extra-data space, and the pointer to
559return the card instance. The extra_size argument is used to allocate
560card->private_data for the chip-specific data. Note that these data are
561allocated by :c:func:`snd_card_new()`.
562
563The 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
567Components
568----------
569
570After the card is created, you can attach the components (devices) to
571the card instance. In an ALSA driver, a component is represented as a
572:c:type:`struct snd_device <snd_device>` object. A component
573can be a PCM instance, a control interface, a raw MIDI interface, etc.
574Each such instance has one component entry.
575
576A component can be created via :c:func:`snd_device_new()`
577function.
578
579::
580
581  snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
582
583This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
584data pointer, and the callback pointers (``&ops``). The device-level
585defines the type of components and the order of registration and
586de-registration. For most components, the device-level is already
587defined. For a user-defined component, you can use
588``SNDRV_DEV_LOWLEVEL``.
589
590This function itself doesn't allocate the data space. The data must be
591allocated manually beforehand, and its pointer is passed as the
592argument. This pointer (``chip`` in the above example) is used as the
593identifier for the instance.
594
595Each pre-defined ALSA component such as ac97 and pcm calls
596:c:func:`snd_device_new()` inside its constructor. The destructor
597for each component is defined in the callback pointers. Hence, you don't
598need to take care of calling a destructor for such a component.
599
600If you wish to create your own component, you need to set the destructor
601function to the dev_free callback in the ``ops``, so that it can be
602released automatically via :c:func:`snd_card_free()`. The next
603example will show an implementation of chip-specific data.
604
605Chip-Specific Data
606------------------
607
608Chip-specific information, e.g. the I/O port address, its resource
609pointer, or the irq number, is stored in the chip-specific record.
610
611::
612
613  struct mychip {
614          ....
615  };
616
617
618In general, there are two ways of allocating the chip record.
619
6201. Allocating via :c:func:`snd_card_new()`.
621~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622
623As mentioned above, you can pass the extra-data-length to the 5th
624argument 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
633In return, the allocated record can be accessed as
634
635::
636
637  struct mychip *chip = card->private_data;
638
639With this method, you don't have to allocate twice. The record is
640released together with the card instance.
641
6422. Allocating an extra device.
643~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
644
645After 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
657The 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
667Then, set the card pointer in the returned chip instance.
668
669::
670
671  chip->card = card;
672
673Next, initialize the fields, and register this chip record as a
674low-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
685function, 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
694where :c:func:`snd_mychip_free()` is the real destructor.
695
696The demerit of this method is the obviously more amount of codes.
697The merit is, however, you can trigger the own callback at registering
698and disconnecting the card via setting in snd_device_ops.
699About the registering and disconnecting the card, see the subsections
700below.
701
702
703Registration and Release
704------------------------
705
706After all components are assigned, register the card instance by calling
707:c:func:`snd_card_register()`. Access to the device files is
708enabled at this point. That is, before
709:c:func:`snd_card_register()` is called, the components are safely
710inaccessible from external side. If this call fails, exit the probe
711function after releasing the card via :c:func:`snd_card_free()`.
712
713For releasing the card instance, you can call simply
714:c:func:`snd_card_free()`. As mentioned earlier, all components
715are released automatically by this call.
716
717For a device which allows hotplugging, you can use
718:c:func:`snd_card_free_when_closed()`. This one will postpone
719the destruction until all devices are closed.
720
721PCI Resource Management
722=======================
723
724Full Code Example
725-----------------
726
727In this section, we'll complete the chip-specific constructor,
728destructor 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
857Some Hafta's
858------------
859
860The allocation of PCI resources is done in the ``probe`` function, and
861usually an extra :c:func:`xxx_create()` function is written for this
862purpose.
863
864In the case of PCI devices, you first have to call the
865:c:func:`pci_enable_device()` function before allocating
866resources. Also, you need to set the proper PCI DMA mask to limit the
867accessed I/O range. In some cases, you might need to call
868:c:func:`pci_set_master()` function, too.
869
870Suppose 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
885Resource Allocation
886-------------------
887
888The allocation of I/O ports and irqs is done via standard kernel
889functions.  These resources must be released in the destructor
890function (see below).
891
892Now assume that the PCI device has an I/O port with 8 bytes and an
893interrupt. Then :c:type:`struct mychip <mychip>` will have the
894following fields:
895
896::
897
898  struct mychip {
899          struct snd_card *card;
900
901          unsigned long port;
902          int irq;
903  };
904
905
906For an I/O port (and also a memory region), you need to have the
907resource pointer for the standard resource management. For an irq, you
908have to keep only the irq number (integer). But you need to initialize
909this number as -1 before actual allocation, since irq 0 is valid. The
910port 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
912resetting them.
913
914The 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
926It will reserve the I/O port region of 8 bytes of the given PCI device.
927The returned value, ``chip->res_port``, is allocated via
928:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
929must be released via :c:func:`kfree()`, but there is a problem with
930this. This issue will be explained later.
931
932The 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
944where :c:func:`snd_mychip_interrupt()` is the interrupt handler
945defined `later <#pcm-interface-interrupt-handler>`__. Note that
946``chip->irq`` should be defined only when :c:func:`request_irq()`
947succeeded.
948
949On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
950as the interrupt flag of :c:func:`request_irq()`.
951
952The last argument of :c:func:`request_irq()` is the data pointer
953passed to the interrupt handler. Usually, the chip-specific record is
954used for that, but you can use what you like, too.
955
956I won't give details about the interrupt handler at this point, but at
957least its appearance can be explained now. The interrupt handler looks
958usually 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
969After requesting the IRQ, you can passed it to ``card->sync_irq``
970field:
971::
972
973          card->irq = chip->irq;
974
975This allows PCM core automatically performing
976:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
977See the later section `sync_stop callback`_ for details.
978
979Now let's write the corresponding destructor for the resources above.
980The role of destructor is simple: disable the hardware (if already
981activated) and release the resources. So far, we have no hardware part,
982so the disabling code is not written here.
983
984To release the resources, the “check-and-release” method is a safer way.
985For the interrupt, do like this:
986
987::
988
989  if (chip->irq >= 0)
990          free_irq(chip->irq, chip);
991
992Since 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
994the validity of the irq number as above.
995
996When 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
999resource(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
1007When 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
1010pointer returned from :c:func:`request_region()` in
1011chip->res_port, the release procedure looks like:
1012
1013::
1014
1015  release_and_free_resource(chip->res_port);
1016
1017Don't forget to call :c:func:`pci_disable_device()` before the
1018end.
1019
1020And finally, release the chip-specific record.
1021
1022::
1023
1024  kfree(chip);
1025
1026We didn't implement the hardware disabling part in the above. If you
1027need to do this, please note that the destructor may be called even
1028before the initialization of the chip is completed. It would be better
1029to have a flag to skip hardware disabling if the hardware was not
1030initialized yet.
1031
1032When the chip-data is assigned to the card using
1033:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
1034destructor is called at the last. That is, it is assured that all other
1035components like PCMs and controls have already been released. You don't
1036have to stop PCMs, etc. explicitly, but just call low-level hardware
1037stopping.
1038
1039The management of a memory-mapped region is almost as same as the
1040management of an I/O port. You'll need three fields like the
1041following:
1042
1043::
1044
1045  struct mychip {
1046          ....
1047          unsigned long iobase_phys;
1048          void __iomem *iobase_virt;
1049  };
1050
1051and 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(chip->iobase_phys,
1062                                      pci_resource_len(pci, 0));
1063
1064and 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
1078Of course, a modern way with :c:func:`pci_iomap()` will make things a
1079bit 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
1090which is paired with :c:func:`pci_iounmap()` at destructor.
1091
1092
1093PCI Entries
1094-----------
1095
1096So 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
1098this chipset. It's a table of PCI vendor/device ID number, and some
1099masks.
1100
1101For 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
1113The 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
1115have no reason to filter the matching devices, you can leave the
1116remaining fields as above. The last field of the :c:type:`struct
1117pci_device_id <pci_device_id>` struct contains private data
1118for this entry. You can specify any value here, for example, to define
1119specific operations for supported device IDs. Such an example is found
1120in the intel8x0 driver.
1121
1122The last entry of this list is the terminator. You must specify this
1123all-zero entry.
1124
1125Then, prepare the :c:type:`struct pci_driver <pci_driver>`
1126record:
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
1137The ``probe`` and ``remove`` functions have already been defined in
1138the previous sections. The ``name`` field is the name string of this
1139device. Note that you must not use a slash “/” in this string.
1140
1141And 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
1158Note that these module entries are tagged with ``__init`` and ``__exit``
1159prefixes.
1160
1161That's all!
1162
1163PCM Interface
1164=============
1165
1166General
1167-------
1168
1169The PCM middle layer of ALSA is quite powerful and it is only necessary
1170for each driver to implement the low-level functions to access its
1171hardware.
1172
1173For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
1174first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1175access to some functions related with hw_param.
1176
1177Each card device can have up to four pcm instances. A pcm instance
1178corresponds to a pcm device file. The limitation of number of instances
1179comes only from the available bit size of the Linux's device numbers.
1180Once when 64bit device number is used, we'll have more pcm instances
1181available.
1182
1183A pcm instance consists of pcm playback and capture streams, and each
1184pcm stream consists of one or more pcm substreams. Some soundcards
1185support multiple playback functions. For example, emu10k1 has a PCM
1186playback of 32 stereo substreams. In this case, at each open, a free
1187substream is (usually) automatically chosen and opened. Meanwhile, when
1188only one substream exists and it was already opened, the successful open
1189will either block or error with ``EAGAIN`` according to the file open
1190mode. But you don't have to care about such details in your driver. The
1191PCM middle layer will take care of such work.
1192
1193Full Code Example
1194-----------------
1195
1196The example code below does not include any hardware access routines but
1197shows 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
1402PCM Constructor
1403---------------
1404
1405A pcm instance is allocated by the :c:func:`snd_pcm_new()`
1406function. 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
1425The :c:func:`snd_pcm_new()` function takes four arguments. The
1426first argument is the card pointer to which this pcm is assigned, and
1427the second is the ID string.
1428
1429The third argument (``index``, 0 in the above) is the index of this new
1430pcm. It begins from zero. If you create more than one pcm instances,
1431specify the different numbers in this argument. For example, ``index =
14321`` for the second PCM device.
1433
1434The fourth and fifth arguments are the number of substreams for playback
1435and capture, respectively. Here 1 is used for both arguments. When no
1436playback or capture substreams are available, pass 0 to the
1437corresponding argument.
1438
1439If a chip supports multiple playbacks or captures, you can specify more
1440numbers, but they must be handled properly in open/close, etc.
1441callbacks. When you need to know which substream you are referring to,
1442then 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
1451After 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
1460The 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
1474All the callbacks are described in the Operators_ subsection.
1475
1476After setting the operators, you probably will want to pre-allocate the
1477buffer and set up the managed allocation mode.
1478For 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
1486It will allocate a buffer up to 64kB as default. Buffer management
1487details will be described in the later section `Buffer and Memory
1488Management`_.
1489
1490Additionally, 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
1493hardware definition (described later). When your soundchip supports only
1494half-duplex, specify like this:
1495
1496::
1497
1498  pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1499
1500
1501... And the Destructor?
1502-----------------------
1503
1504The destructor for a pcm instance is not always necessary. Since the pcm
1505device will be released by the middle layer code automatically, you
1506don't have to call the destructor explicitly.
1507
1508The destructor would be necessary if you created special records
1509internally and needed to release them. In such a case, set the
1510destructor 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
1537Runtime Pointer - The Chest of PCM Information
1538----------------------------------------------
1539
1540When the PCM substream is opened, a PCM runtime instance is allocated
1541and assigned to the substream. This pointer is accessible via
1542``substream->runtime``. This runtime pointer holds most information you
1543need to control the PCM: the copy of hw_params and sw_params
1544configurations, the buffer pointers, mmap records, spinlocks, etc.
1545
1546The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1547are 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
1630For the operators (callbacks) of each sound driver, most of these
1631records are supposed to be read-only. Only the PCM middle-layer changes
1632/ updates them. The exceptions are the hardware description (hw) DMA
1633buffer information and the private data. Besides, if you use the
1634standard managed buffer allocation mode, you don't need to set the
1635DMA buffer information by yourself.
1636
1637In the sections below, important records are explained.
1638
1639Hardware Description
1640~~~~~~~~~~~~~~~~~~~~
1641
1642The hardware descriptor (:c:type:`struct snd_pcm_hardware
1643<snd_pcm_hardware>`) contains the definitions of the fundamental
1644hardware configuration. Above all, you'll need to define this in the
1645`PCM open callback`_. Note that the runtime instance holds the copy of
1646the descriptor, not the pointer to the existing descriptor. That is,
1647in the open callback, you can modify the copied descriptor
1648(``runtime->hw``) as you need. For example, if the maximum number of
1649channels is 1 only on some chip models, you can still use the same
1650hardware 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
1660Typically, 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
1750PCM Configurations
1751~~~~~~~~~~~~~~~~~~
1752
1753Ok, let's go back again to the PCM runtime records. The most
1754frequently referred records in the runtime instance are the PCM
1755configurations. The PCM configurations are stored in the runtime
1756instance after the application sends ``hw_params`` data via
1757alsa-lib. There are many fields copied from hw_params and sw_params
1758structs. For example, ``format`` holds the format type chosen by the
1759application. This field contains the enum value
1760``SNDRV_PCM_FORMAT_XXX``.
1761
1762One thing to be noted is that the configured buffer and period sizes
1763are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1764channels \* samples-size``. For conversion between frames and bytes,
1765you 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
1772Also, many software parameters (sw_params) are stored in frames, too.
1773Please check the type of the field. ``snd_pcm_uframes_t`` is for the
1774frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
1775frames as signed integer.
1776
1777DMA Buffer Information
1778~~~~~~~~~~~~~~~~~~~~~~
1779
1780The DMA buffer is defined by the following four fields, ``dma_area``,
1781``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
1782holds the buffer pointer (the logical address). You can call
1783:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1784the physical address of the buffer. This field is specified only when
1785the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
1786in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1787
1788If you use either the managed buffer allocation mode or the standard
1789API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1790these fields are set by the ALSA middle layer, and you should *not*
1791change them by yourself. You can read them but not write them. On the
1792other hand, if you want to allocate the buffer by yourself, you'll
1793need to manage it in hw_params callback. At least, ``dma_bytes`` is
1794mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1795your driver doesn't support mmap, this field is not
1796necessary. ``dma_addr`` is also optional. You can use dma_private as
1797you like, too.
1798
1799Running Status
1800~~~~~~~~~~~~~~
1801
1802The running status can be referred via ``runtime->status``. This is
1803the pointer to the :c:type:`struct snd_pcm_mmap_status
1804<snd_pcm_mmap_status>` record. For example, you can get the current
1805DMA hardware pointer via ``runtime->status->hw_ptr``.
1806
1807The DMA application pointer can be referred via ``runtime->control``,
1808which points to the :c:type:`struct snd_pcm_mmap_control
1809<snd_pcm_mmap_control>` record. However, accessing directly to
1810this value is not recommended.
1811
1812Private Data
1813~~~~~~~~~~~~
1814
1815You can allocate a record for the substream and store it in
1816``runtime->private_data``. Usually, this is done in the `PCM open
1817callback`_. Don't mix this with ``pcm->private_data``. The
1818``pcm->private_data`` usually points to the chip instance assigned
1819statically at the creation of PCM, while the ``runtime->private_data``
1820points to a dynamic data structure created at the PCM open
1821callback.
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
1835The allocated object must be released in the `close callback`_.
1836
1837Operators
1838---------
1839
1840OK, now let me give details about each pcm callback (``ops``). In
1841general, every callback must return 0 if successful, or a negative
1842error number such as ``-EINVAL``. To choose an appropriate error
1843number, it is advised to check what value other parts of the kernel
1844return when the same kind of request fails.
1845
1846The callback function takes at least the argument with :c:type:`struct
1847snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip
1848record from the given substream instance, you can use the following
1849macro.
1850
1851::
1852
1853  int xxx() {
1854          struct mychip *chip = snd_pcm_substream_chip(substream);
1855          ....
1856  }
1857
1858The macro reads ``substream->private_data``, which is a copy of
1859``pcm->private_data``. You can override the former if you need to
1860assign different data records per PCM substream. For example, the
1861cmi8330 driver assigns different ``private_data`` for playback and
1862capture directions, because it uses two different codecs (SB- and
1863AD-compatible) for different directions.
1864
1865PCM open callback
1866~~~~~~~~~~~~~~~~~
1867
1868::
1869
1870  static int snd_xxx_open(struct snd_pcm_substream *substream);
1871
1872This is called when a pcm substream is opened.
1873
1874At least, here you have to initialize the ``runtime->hw``
1875record. 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
1888where ``snd_mychip_playback_hw`` is the pre-defined hardware
1889description.
1890
1891You can allocate a private data in this callback, as described in
1892`Private Data`_ section.
1893
1894If the hardware configuration needs more constraints, set the hardware
1895constraints here, too. See Constraints_ for more details.
1896
1897close callback
1898~~~~~~~~~~~~~~
1899
1900::
1901
1902  static int snd_xxx_close(struct snd_pcm_substream *substream);
1903
1904
1905Obviously, this is called when a pcm substream is closed.
1906
1907Any private instance for a pcm substream allocated in the ``open``
1908callback 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
1919ioctl callback
1920~~~~~~~~~~~~~~
1921
1922This is used for any special call to pcm ioctls. But usually you can
1923leave it as NULL, then PCM core calls the generic ioctl callback
1924function :c:func:`snd_pcm_lib_ioctl()`.  If you need to deal with the
1925unique setup of channel info or reset procedure, you can pass your own
1926callback function here.
1927
1928hw_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
1936This is called when the hardware parameter (``hw_params``) is set up
1937by the application, that is, once when the buffer size, the period
1938size, the format, etc. are defined for the pcm substream.
1939
1940Many hardware setups should be done in this callback, including the
1941allocation of buffers.
1942
1943Parameters to be initialized are retrieved by
1944:c:func:`params_xxx()` macros.
1945
1946When you set up the managed buffer allocation mode for the substream,
1947a buffer is already allocated before this callback gets
1948called. Alternatively, you can call a helper function below for
1949allocating 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
1956DMA buffers have been pre-allocated. See the section `Buffer Types`_
1957for more details.
1958
1959Note that this and ``prepare`` callbacks may be called multiple times
1960per initialization. For example, the OSS emulation may call these
1961callbacks at each change via its ioctl.
1962
1963Thus, you need to be careful not to allocate the same buffers many
1964times, which will lead to memory leaks! Calling the helper function
1965above many times is OK. It will release the previous buffer
1966automatically when it was already allocated.
1967
1968Another note is that this callback is non-atomic (schedulable) as
1969default, i.e. when no ``nonatomic`` flag set. This is important,
1970because the ``trigger`` callback is atomic (non-schedulable). That is,
1971mutexes or any schedule-related functions are not available in
1972``trigger`` callback. Please see the subsection Atomicity_ for
1973details.
1974
1975hw_free callback
1976~~~~~~~~~~~~~~~~~
1977
1978::
1979
1980  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1981
1982This is called to release the resources allocated via
1983``hw_params``.
1984
1985This function is always called before the close callback is called.
1986Also, the callback may be called multiple times, too. Keep track
1987whether the resource was already released.
1988
1989When you have set up the managed buffer allocation mode for the PCM
1990substream, the allocated PCM buffer will be automatically released
1991after this callback gets called.  Otherwise you'll have to release the
1992buffer manually.  Typically, when the buffer was allocated from the
1993pre-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
2000prepare callback
2001~~~~~~~~~~~~~~~~
2002
2003::
2004
2005  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
2006
2007This callback is called when the pcm is “prepared”. You can set the
2008format type, sample rate, etc. here. The difference from ``hw_params``
2009is that the ``prepare`` callback will be called each time
2010:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
2011underruns, etc.
2012
2013Note that this callback is now non-atomic. You can use
2014schedule-related functions safely in this callback.
2015
2016In this and the following callbacks, you can refer to the values via
2017the runtime record, ``substream->runtime``. For example, to get the
2018current rate, format or channels, access to ``runtime->rate``,
2019``runtime->format`` or ``runtime->channels``, respectively. The
2020physical 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
2024Be careful that this callback will be called many times at each setup,
2025too.
2026
2027trigger callback
2028~~~~~~~~~~~~~~~~
2029
2030::
2031
2032  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
2033
2034This is called when the pcm is started, stopped or paused.
2035
2036Which action is specified in the second argument,
2037``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
2038and ``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
2053When the pcm supports the pause operation (given in the info field of
2054the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
2055must be handled here, too. The former is the command to pause the pcm,
2056and the latter to restart the pcm again.
2057
2058When the pcm supports the suspend/resume operation, regardless of full
2059or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
2060commands must be handled, too. These commands are issued when the
2061power-management status is changed. Obviously, the ``SUSPEND`` and
2062``RESUME`` commands suspend and resume the pcm substream, and usually,
2063they are identical to the ``STOP`` and ``START`` commands, respectively.
2064See the `Power Management`_ section for details.
2065
2066As mentioned, this callback is atomic as default unless ``nonatomic``
2067flag set, and you cannot call functions which may sleep. The
2068``trigger`` callback should be as minimal as possible, just really
2069triggering the DMA. The other stuff should be initialized
2070``hw_params`` and ``prepare`` callbacks properly beforehand.
2071
2072sync_stop callback
2073~~~~~~~~~~~~~~~~~~
2074
2075::
2076
2077  static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
2078
2079This callback is optional, and NULL can be passed.  It's called after
2080the PCM core stops the stream and changes the stream state
2081``prepare``, ``hw_params`` or ``hw_free``.
2082Since the IRQ handler might be still pending, we need to wait until
2083the pending task finishes before moving to the next step; otherwise it
2084might lead to a crash due to resource conflicts or access to the freed
2085resources.  A typical behavior is to call a synchronization function
2086like :c:func:`synchronize_irq()` here.
2087
2088For majority of drivers that need only a call of
2089:c:func:`synchronize_irq()`, there is a simpler setup, too.
2090While keeping NULL to ``sync_stop`` PCM callback, the driver can set
2091``card->sync_irq`` field to store the valid interrupt number after
2092requesting an IRQ, instead.   Then PCM core will look call
2093:c:func:`synchronize_irq()` with the given IRQ appropriately.
2094
2095If the IRQ handler is released at the card destructor, you don't need
2096to clear ``card->sync_irq``, as the card itself is being released.
2097So, 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
2099the 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
2103pointer callback
2104~~~~~~~~~~~~~~~~
2105
2106::
2107
2108  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2109
2110This callback is called when the PCM middle layer inquires the current
2111hardware position on the buffer. The position must be returned in
2112frames, ranging from 0 to ``buffer_size - 1``.
2113
2114This is called usually from the buffer-update routine in the pcm
2115middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2116is called in the interrupt routine. Then the pcm middle layer updates
2117the position and calculates the available space, and wakes up the
2118sleeping poll threads, etc.
2119
2120This callback is also atomic as default.
2121
2122copy_user, copy_kernel and fill_silence ops
2123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2124
2125These callbacks are not mandatory, and can be omitted in most cases.
2126These callbacks are used when the hardware buffer cannot be in the
2127normal memory space. Some chips have their own buffer on the hardware
2128which is not mappable. In such a case, you have to transfer the data
2129manually from the memory buffer to the hardware buffer. Or, if the
2130buffer is non-contiguous on both physical and virtual memory spaces,
2131these callbacks must be defined, too.
2132
2133If these two callbacks are defined, copy and set-silence operations
2134are done by them. The detailed will be described in the later section
2135`Buffer and Memory Management`_.
2136
2137ack callback
2138~~~~~~~~~~~~
2139
2140This callback is also not mandatory. This callback is called when the
2141``appl_ptr`` is updated in read or write operations. Some drivers like
2142emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2143internal buffer, and this callback is useful only for such a purpose.
2144
2145This callback is atomic as default.
2146
2147page callback
2148~~~~~~~~~~~~~
2149
2150This callback is optional too. The mmap calls this callback to get the
2151page fault address.
2152
2153Since the recent changes, you need no special callback any longer for
2154the standard SG-buffer or vmalloc-buffer. Hence this callback should
2155be rarely used.
2156
2157mmap calllback
2158~~~~~~~~~~~~~~
2159
2160This is another optional callback for controlling mmap behavior.
2161Once when defined, PCM core calls this callback when a page is
2162memory-mapped instead of dealing via the standard helper.
2163If you need special handling (due to some architecture or
2164device-specific issues), implement everything here as you like.
2165
2166
2167PCM Interrupt Handler
2168---------------------
2169
2170The rest of pcm stuff is the PCM interrupt handler. The role of PCM
2171interrupt handler in the sound driver is to update the buffer position
2172and to tell the PCM middle layer when the buffer position goes across
2173the prescribed period size. To inform this, call the
2174:c:func:`snd_pcm_period_elapsed()` function.
2175
2176There are several types of sound chips to generate the interrupts.
2177
2178Interrupts at the period (fragment) boundary
2179~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2180
2181This is the most frequently found type: the hardware generates an
2182interrupt 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
2186its argument. Thus, you need to keep the substream pointer accessible
2187from the chip instance. For example, define ``substream`` field in the
2188chip record to hold the current running substream pointer, and set the
2189pointer value at ``open`` callback (and reset at ``close`` callback).
2190
2191If you acquire a spinlock in the interrupt handler, and the lock is used
2192in other pcm callbacks, too, then you have to release the lock before
2193calling :c:func:`snd_pcm_period_elapsed()`, because
2194:c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
2195inside.
2196
2197Typical 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
2221High frequency timer interrupts
2222~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2223
2224This happens when the hardware doesn't generate interrupts at the period
2225boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2226or ymfpci drivers). In this case, you need to check the current hardware
2227position and accumulate the processed sample length at each interrupt.
2228When the accumulated size exceeds the period size, call
2229:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2230
2231Typical 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
2275On calling :c:func:`snd_pcm_period_elapsed()`
2276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2277
2278In both cases, even if more than one period are elapsed, you don't have
2279to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2280once. And the pcm layer will check the current hardware pointer and
2281update to the latest status.
2282
2283Atomicity
2284---------
2285
2286One of the most important (and thus difficult to debug) problems in
2287kernel programming are race conditions. In the Linux kernel, they are
2288usually avoided via spin-locks, mutexes or semaphores. In general, if a
2289race condition can happen in an interrupt handler, it has to be managed
2290atomically, and you have to use a spinlock to protect the critical
2291session. If the critical section is not in interrupt handler code and if
2292taking a relatively long time to execute is acceptable, you should use
2293mutexes or semaphores instead.
2294
2295As already seen, some pcm callbacks are atomic and some are not. For
2296example, the ``hw_params`` callback is non-atomic, while ``trigger``
2297callback is atomic. This means, the latter is called already in a
2298spinlock held by the PCM middle layer. Please take this atomicity into
2299account when you choose a locking scheme in the callbacks.
2300
2301In the atomic callbacks, you cannot use functions which may call
2302:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2303mutexes can sleep, and hence they cannot be used inside the atomic
2304callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2305callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2306
2307All three atomic callbacks (trigger, pointer, and ack) are called with
2308local interrupts disabled.
2309
2310The recent changes in PCM core code, however, allow all PCM operations
2311to be non-atomic. This assumes that the all caller sides are in
2312non-atomic contexts. For example, the function
2313:c:func:`snd_pcm_period_elapsed()` is called typically from the
2314interrupt handler. But, if you set up the driver to use a threaded
2315interrupt handler, this call can be in non-atomic context, too. In such
2316a 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
2318and rwsem are used internally in the PCM core instead of spin and
2319rwlocks, so that you can call all PCM functions safely in a non-atomic
2320context.
2321
2322Constraints
2323-----------
2324
2325If your chip supports unconventional sample rates, or only the limited
2326samples, you need to set a constraint for the condition.
2327
2328For example, in order to restrict the sample rates in the some supported
2329values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2330call 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
2356There are many different constraints. Look at ``sound/pcm.h`` for a
2357complete list. You can even define your own constraint rules. For
2358example, let's suppose my_chip can manage a substream of 1 channel if
2359and only if the format is ``S16_LE``, otherwise it supports any format
2360specified in the :c:type:`struct snd_pcm_hardware
2361<snd_pcm_hardware>` structure (or in any other
2362constraint_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
2384Then 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
2392The rule function is called when an application sets the PCM format, and
2393it refines the number of channels accordingly. But an application may
2394set the number of channels before setting the format. Thus you also need
2395to 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
2424One typical usage of the hw constraints is to align the buffer size
2425with the period size.  As default, ALSA PCM core doesn't enforce the
2426buffer size to be aligned with the period size.  For example, it'd be
2427possible to have a combination like 256 period bytes with 999 buffer
2428bytes.
2429
2430Many device chips, however, require the buffer to be a multiple of
2431periods.  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
2440This assures that the number of periods is integer, hence the buffer
2441size is aligned with the period size.
2442
2443The hw constraint is a very much powerful mechanism to define the
2444preferred PCM configuration, and there are relevant helpers.
2445I won't give more details here, rather I would like to say, “Luke, use
2446the source.”
2447
2448Control Interface
2449=================
2450
2451General
2452-------
2453
2454The control interface is used widely for many switches, sliders, etc.
2455which are accessed from user-space. Its most important use is the mixer
2456interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2457implemented on the control kernel API.
2458
2459ALSA has a well-defined AC97 control module. If your chip supports only
2460the AC97 and nothing else, you can skip this section.
2461
2462The control API is defined in ``<sound/control.h>``. Include this file
2463if you want to add your own controls.
2464
2465Definition of Controls
2466----------------------
2467
2468To create a new control, you need to define the following three
2469callbacks: ``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
2487The ``iface`` field specifies the control type,
2488``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2489for global controls that are not logically part of the mixer. If the
2490control is closely associated with some specific device on the sound
2491card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2492and specify the device number with the ``device`` and ``subdevice``
2493fields.
2494
2495The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2496control name is very important, because its role is classified from
2497its name. There are pre-defined standard control names. The details
2498are described in the `Control Names`_ subsection.
2499
2500The ``index`` field holds the index number of this control. If there
2501are several different controls with the same name, they can be
2502distinguished by the index number. This is the case when several
2503codecs exist on the card. If the index is zero, you can omit the
2504definition above.
2505
2506The ``access`` field contains the access type of this control. Give
2507the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2508there. The details will be explained in the `Access Flags`_
2509subsection.
2510
2511The ``private_value`` field contains an arbitrary long integer value
2512for this record. When using the generic ``info``, ``get`` and ``put``
2513callbacks, you can pass a value through this field. If several small
2514numbers are necessary, you can combine them in bitwise. Or, it's
2515possible to give a pointer (casted to unsigned long) of some record to
2516this field, too.
2517
2518The ``tlv`` field can be used to provide metadata about the control;
2519see the `Metadata`_ subsection.
2520
2521The other three are `Control Callbacks`_.
2522
2523Control Names
2524-------------
2525
2526There are some standards to define the control names. A control is
2527usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2528
2529The first, ``SOURCE``, specifies the source of the control, and is a
2530string such as “Master”, “PCM”, “CD” and “Line”. There are many
2531pre-defined sources.
2532
2533The second, ``DIRECTION``, is one of the following strings according to
2534the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2535and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2536capture directions.
2537
2538The third, ``FUNCTION``, is one of the following strings according to
2539the function of the control: “Switch”, “Volume” and “Route”.
2540
2541The example of control names are, thus, “Master Capture Switch” or “PCM
2542Playback Volume”.
2543
2544There are some exceptions:
2545
2546Global capture and playback
2547~~~~~~~~~~~~~~~~~~~~~~~~~~~
2548
2549“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2550global capture (input) source, switch and volume. Similarly, “Playback
2551Switch” and “Playback Volume” are used for the global output gain switch
2552and volume.
2553
2554Tone-controls
2555~~~~~~~~~~~~~
2556
2557tone-control switch and volumes are specified like “Tone Control - XXX”,
2558e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2559Center”.
2560
25613D controls
2562~~~~~~~~~~~
2563
25643D-control switches and volumes are specified like “3D Control - XXX”,
2565e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2566
2567Mic boost
2568~~~~~~~~~
2569
2570Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2571
2572More precise information can be found in
2573``Documentation/sound/designs/control-names.rst``.
2574
2575Access Flags
2576------------
2577
2578The access flag is the bitmask which specifies the access type of the
2579given control. The default access type is
2580``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2581allowed to this control. When the access flag is omitted (i.e. = 0), it
2582is considered as ``READWRITE`` access as default.
2583
2584When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2585instead. In this case, you don't have to define the ``put`` callback.
2586Similarly, when the control is write-only (although it's a rare case),
2587you can use the ``WRITE`` flag instead, and you don't need the ``get``
2588callback.
2589
2590If the control value changes frequently (e.g. the VU meter),
2591``VOLATILE`` flag should be given. This means that the control may be
2592changed without `Change notification`_. Applications should poll such
2593a control constantly.
2594
2595When the control is inactive, set the ``INACTIVE`` flag, too. There are
2596``LOCK`` and ``OWNER`` flags to change the write permissions.
2597
2598Control Callbacks
2599-----------------
2600
2601info callback
2602~~~~~~~~~~~~~
2603
2604The ``info`` callback is used to get detailed information on this
2605control. This must store the values of the given :c:type:`struct
2606snd_ctl_elem_info <snd_ctl_elem_info>` object. For example,
2607for 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
2624The ``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
2627this 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
2629type. The boolean and integer types are identical.
2630
2631The enumerated type is a bit different from others. You'll need to set
2632the 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
2652The 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;
2655it'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
2669Some 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
2672is 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
2674stereo channel boolean item.
2675
2676get callback
2677~~~~~~~~~~~~
2678
2679This callback is used to read the current value of the control and to
2680return to user-space.
2681
2682For 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
2697The ``value`` field depends on the type of control as well as on the
2698info callback. For example, the sb driver uses this field to store the
2699register offset, the bit-shift and the bit-mask. The ``private_value``
2700field is set as follows:
2701
2702::
2703
2704  .private_value = reg | (shift << 16) | (mask << 24)
2705
2706and 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
2719In the ``get`` callback, you have to fill all the elements if the
2720control has more than one elements, i.e. ``count > 1``. In the example
2721above, we filled only one element (``value.integer.value[0]``) since
2722it's assumed as ``count = 1``.
2723
2724put callback
2725~~~~~~~~~~~~
2726
2727This callback is used to write a value from user-space.
2728
2729For 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
2750As seen above, you have to return 1 if the value is changed. If the
2751value is not changed, return 0 instead. If any fatal error happens,
2752return a negative error code as usual.
2753
2754As in the ``get`` callback, when the control has more than one
2755elements, all elements must be evaluated in this callback, too.
2756
2757Callbacks are not atomic
2758~~~~~~~~~~~~~~~~~~~~~~~~
2759
2760All these three callbacks are basically not atomic.
2761
2762Control Constructor
2763-------------------
2764
2765When everything is ready, finally we can create a new control. To create
2766a control, there are two functions to be called,
2767:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2768
2769In 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
2777where ``my_control`` is the :c:type:`struct snd_kcontrol_new
2778<snd_kcontrol_new>` object defined above, and chip is the object
2779pointer to be passed to kcontrol->private_data which can be referred
2780to in callbacks.
2781
2782:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct
2783snd_kcontrol <snd_kcontrol>` instance, and
2784:c:func:`snd_ctl_add()` assigns the given control component to the
2785card.
2786
2787Change Notification
2788-------------------
2789
2790If you need to change and update a control in the interrupt routine, you
2791can call :c:func:`snd_ctl_notify()`. For example,
2792
2793::
2794
2795  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2796
2797This function takes the card pointer, the event-mask, and the control id
2798pointer for the notification. The event-mask specifies the types of
2799notification, for example, in the above example, the change of control
2800values is notified. The id pointer is the pointer of :c:type:`struct
2801snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can
2802find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume
2803interrupts.
2804
2805Metadata
2806--------
2807
2808To provide information about the dB values of a mixer control, use on of
2809the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2810variable containing this information, set the ``tlv.p`` field to point to
2811this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2812in 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
2827The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2828about a mixer control where each step in the control's value changes the
2829dB value by a constant dB amount. The first parameter is the name of the
2830variable to be defined. The second parameter is the minimum value, in
2831units of 0.01 dB. The third parameter is the step size, in units of 0.01
2832dB. Set the fourth parameter to 1 if the minimum value actually mutes
2833the control.
2834
2835The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2836about a mixer control where the control's value affects the output
2837linearly. The first parameter is the name of the variable to be defined.
2838The second parameter is the minimum value, in units of 0.01 dB. The
2839third parameter is the maximum value, in units of 0.01 dB. If the
2840minimum value mutes the control, set the second parameter to
2841``TLV_DB_GAIN_MUTE``.
2842
2843API for AC97 Codec
2844==================
2845
2846General
2847-------
2848
2849The ALSA AC97 codec layer is a well-defined one, and you don't have to
2850write much code to control it. Only low-level control routines are
2851necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2852
2853Full 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
2900AC97 Constructor
2901----------------
2902
2903To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2904with 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
2916The bus record is shared among all belonging ac97 instances.
2917
2918And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct
2919snd_ac97_template <snd_ac97_template>` record together with
2920the 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
2931where chip->ac97 is a pointer to a newly created ``ac97_t``
2932instance. In this case, the chip pointer is set as the private data,
2933so that the read/write callback functions can refer to this chip
2934instance. This instance is not necessarily stored in the chip
2935record. If you need to change the register values from the driver, or
2936need the suspend/resume of ac97 codecs, keep this pointer to pass to
2937the corresponding functions.
2938
2939AC97 Callbacks
2940--------------
2941
2942The standard callbacks are ``read`` and ``write``. Obviously they
2943correspond to the functions for read and write accesses to the
2944hardware low-level codes.
2945
2946The ``read`` callback returns the register value specified in the
2947argument.
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
2959Here, the chip can be cast from ``ac97->private_data``.
2960
2961Meanwhile, the ``write`` callback is used to set the register
2962value
2963
2964::
2965
2966  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2967                       unsigned short reg, unsigned short val)
2968
2969
2970These callbacks are non-atomic like the control API callbacks.
2971
2972There are also other callbacks: ``reset``, ``wait`` and ``init``.
2973
2974The ``reset`` callback is used to reset the codec. If the chip
2975requires a special kind of reset, you can define this callback.
2976
2977The ``wait`` callback is used to add some waiting time in the standard
2978initialization of the codec. If the chip requires the extra waiting
2979time, define this callback.
2980
2981The ``init`` callback is used for additional initialization of the
2982codec.
2983
2984Updating Registers in The Driver
2985--------------------------------
2986
2987If you need to access to the codec from the driver, you can call the
2988following 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
2992Both :c:func:`snd_ac97_write()` and
2993:c:func:`snd_ac97_update()` functions are used to set a value to
2994the given register (``AC97_XXX``). The difference between them is that
2995:c:func:`snd_ac97_update()` doesn't write a value if the given
2996value has been already set, while :c:func:`snd_ac97_write()`
2997always 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
3005register. 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
3012the given register.
3013
3014::
3015
3016  snd_ac97_update_bits(ac97, reg, mask, value);
3017
3018Also, there is a function to change the sample rate (of a given register
3019such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
3020codec: :c:func:`snd_ac97_set_rate()`.
3021
3022::
3023
3024  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
3025
3026
3027The 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
3030specified, the register is not really changed but the corresponding
3031IEC958 status bits will be updated.
3032
3033Clock Adjustment
3034----------------
3035
3036In 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
3038the corresponding value. For example, intel8x0 and es1968 drivers have
3039their own function to read from the clock.
3040
3041Proc Files
3042----------
3043
3044The 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
3046can refer to these files to see the current status and registers of
3047the codec.
3048
3049Multiple Codecs
3050---------------
3051
3052When 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
3054greater. The ``num`` field specifies the codec number.
3055
3056If you set up multiple codecs, you either need to write different
3057callbacks for each codec or check ``ac97->num`` in the callback
3058routines.
3059
3060MIDI (MPU401-UART) Interface
3061============================
3062
3063General
3064-------
3065
3066Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
3067soundcard supports the standard MPU401-UART interface, most likely you
3068can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
3069``<sound/mpu401.h>``.
3070
3071Some soundchips have a similar but slightly different implementation of
3072mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
3073
3074MIDI Constructor
3075----------------
3076
3077To 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
3086The first argument is the card pointer, and the second is the index of
3087this component. You can create up to 8 rawmidi devices.
3088
3089The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
3090it's not a special one, you can use ``MPU401_HW_MPU401``.
3091
3092The 4th argument is the I/O port address. Many backward-compatible
3093MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
3094PCI I/O region. It depends on the chip design.
3095
3096The 5th argument is a bitflag for additional information. When the I/O
3097port address above is part of the PCI I/O region, the MPU401 I/O port
3098might have been already allocated (reserved) by the driver itself. In
3099such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
3100mpu401-uart layer will allocate the I/O ports by itself.
3101
3102When the controller supports only the input or output MIDI stream, pass
3103the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
3104respectively. 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
3108to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
3109
3110When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
3111the default interrupt handler. The driver needs to call
3112:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
3113processing the output stream in the irq handler.
3114
3115If the MPU-401 interface shares its interrupt with the other logical
3116devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
3117`below <#MIDI-Interrupt-Handler>`__).
3118
3119Usually, the port address corresponds to the command port and port + 1
3120corresponds to the data port. If not, you may change the ``cport``
3121field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward.
3122However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is
3123not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
3124need 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
3132and reset the ``cport`` as you like:
3133
3134::
3135
3136  mpu->cport = my_own_control_port;
3137
3138The 6th argument specifies the ISA irq number that will be allocated. If
3139no interrupt is to be allocated (because your code is already allocating
3140a 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
3142will be used instead.
3143
3144MIDI Interrupt Handler
3145----------------------
3146
3147When the interrupt is allocated in
3148:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3149handler is automatically used, hence you don't have anything else to do
3150than 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
3153interrupt handler when it has determined that a UART interrupt has
3154occurred.
3155
3156In this case, you need to pass the private_data of the returned rawmidi
3157object from :c:func:`snd_mpu401_uart_new()` as the second
3158argument of :c:func:`snd_mpu401_uart_interrupt()`.
3159
3160::
3161
3162  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3163
3164
3165RawMIDI Interface
3166=================
3167
3168Overview
3169--------
3170
3171The raw MIDI interface is used for hardware MIDI ports that can be
3172accessed as a byte stream. It is not used for synthesizer chips that do
3173not directly understand MIDI.
3174
3175ALSA handles file and buffer management. All you have to do is to write
3176some code to move data between the buffer and the hardware.
3177
3178The rawmidi API is defined in ``<sound/rawmidi.h>``.
3179
3180RawMIDI Constructor
3181-------------------
3182
3183To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3184function:
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
3198The first argument is the card pointer, the second argument is the ID
3199string.
3200
3201The third argument is the index of this component. You can create up to
32028 rawmidi devices.
3203
3204The fourth and fifth arguments are the number of output and input
3205substreams, respectively, of this device (a substream is the equivalent
3206of a MIDI port).
3207
3208Set the ``info_flags`` field to specify the capabilities of the
3209device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3210output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3211input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3212output and input at the same time.
3213
3214After the rawmidi device is created, you need to set the operators
3215(callbacks) for each substream. There are helper functions to set the
3216operators 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
3223The 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
3233These callbacks are explained in the `RawMIDI Callbacks`_ section.
3234
3235If there are more than one substream, you should give a unique name to
3236each 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
3248RawMIDI Callbacks
3249-----------------
3250
3251In all the callbacks, the private data that you've set for the rawmidi
3252device can be accessed as ``substream->rmidi->private_data``.
3253
3254If there is more than one port, your callbacks can determine the port
3255index from the struct snd_rawmidi_substream data passed to each
3256callback:
3257
3258::
3259
3260  struct snd_rawmidi_substream *substream;
3261  int index = substream->number;
3262
3263RawMIDI open callback
3264~~~~~~~~~~~~~~~~~~~~~
3265
3266::
3267
3268      static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3269
3270
3271This is called when a substream is opened. You can initialize the
3272hardware here, but you shouldn't start transmitting/receiving data yet.
3273
3274RawMIDI close callback
3275~~~~~~~~~~~~~~~~~~~~~~
3276
3277::
3278
3279      static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3280
3281Guess what.
3282
3283The ``open`` and ``close`` callbacks of a rawmidi device are
3284serialized with a mutex, and can sleep.
3285
3286Rawmidi 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
3294This is called with a nonzero ``up`` parameter when there is some data
3295in the substream buffer that must be transmitted.
3296
3297To read data from the buffer, call
3298:c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3299of bytes that have been read; this will be less than the number of bytes
3300requested when there are no more data in the buffer. After the data have
3301been transmitted successfully, call
3302:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3303substream buffer:
3304
3305::
3306
3307  unsigned char data;
3308  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3309          if (snd_mychip_try_to_transmit(data))
3310                  snd_rawmidi_transmit_ack(substream, 1);
3311          else
3312                  break; /* hardware FIFO full */
3313  }
3314
3315If you know beforehand that the hardware will accept data, you can use
3316the :c:func:`snd_rawmidi_transmit()` function which reads some
3317data and removes them from the buffer at once:
3318
3319::
3320
3321  while (snd_mychip_transmit_possible()) {
3322          unsigned char data;
3323          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3324                  break; /* no more data */
3325          snd_mychip_transmit(data);
3326  }
3327
3328If you know beforehand how many bytes you can accept, you can use a
3329buffer size greater than one with the
3330:c:func:`snd_rawmidi_transmit\*()` functions.
3331
3332The ``trigger`` callback must not sleep. If the hardware FIFO is full
3333before the substream buffer has been emptied, you have to continue
3334transmitting data later, either in an interrupt handler, or with a
3335timer if the hardware doesn't have a MIDI transmit interrupt.
3336
3337The ``trigger`` callback is called with a zero ``up`` parameter when
3338the transmission of data should be aborted.
3339
3340RawMIDI trigger callback for input substreams
3341~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3342
3343::
3344
3345      static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3346
3347
3348This is called with a nonzero ``up`` parameter to enable receiving data,
3349or with a zero ``up`` parameter do disable receiving data.
3350
3351The ``trigger`` callback must not sleep; the actual reading of data
3352from the device is usually done in an interrupt handler.
3353
3354When data reception is enabled, your interrupt handler should call
3355:c:func:`snd_rawmidi_receive()` for all received data:
3356
3357::
3358
3359  void snd_mychip_midi_interrupt(...)
3360  {
3361          while (mychip_midi_available()) {
3362                  unsigned char data;
3363                  data = mychip_midi_read();
3364                  snd_rawmidi_receive(substream, &data, 1);
3365          }
3366  }
3367
3368
3369drain callback
3370~~~~~~~~~~~~~~
3371
3372::
3373
3374      static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3375
3376
3377This is only used with output substreams. This function should wait
3378until all data read from the substream buffer have been transmitted.
3379This ensures that the device can be closed and the driver unloaded
3380without losing data.
3381
3382This callback is optional. If you do not set ``drain`` in the struct
3383snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3384instead.
3385
3386Miscellaneous Devices
3387=====================
3388
3389FM OPL3
3390-------
3391
3392The FM OPL3 is still used in many chips (mainly for backward
3393compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3394is defined in ``<sound/opl3.h>``.
3395
3396FM registers can be directly accessed through the direct-FM API, defined
3397in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3398accessed through the Hardware-Dependent Device direct-FM extension API,
3399whereas in OSS compatible mode, FM registers can be accessed with the
3400OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3401
3402To create the OPL3 component, you have two functions to call. The first
3403one is a constructor for the ``opl3_t`` instance.
3404
3405::
3406
3407  struct snd_opl3 *opl3;
3408  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3409                  integrated, &opl3);
3410
3411The first argument is the card pointer, the second one is the left port
3412address, and the third is the right port address. In most cases, the
3413right port is placed at the left port + 2.
3414
3415The fourth argument is the hardware type.
3416
3417When the left and right ports have been already allocated by the card
3418driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3419the opl3 module will allocate the specified ports by itself.
3420
3421When the accessing the hardware requires special method instead of the
3422standard I/O access, you can create opl3 instance separately with
3423:c:func:`snd_opl3_new()`.
3424
3425::
3426
3427  struct snd_opl3 *opl3;
3428  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3429
3430Then set ``command``, ``private_data`` and ``private_free`` for the
3431private access function, the private data and the destructor. The
3432``l_port`` and ``r_port`` are not necessarily set. Only the command
3433must be set properly. You can retrieve the data from the
3434``opl3->private_data`` field.
3435
3436After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3437call :c:func:`snd_opl3_init()` to initialize the chip to the
3438proper state. Note that :c:func:`snd_opl3_create()` always calls
3439it internally.
3440
3441If the opl3 instance is created successfully, then create a hwdep device
3442for this opl3.
3443
3444::
3445
3446  struct snd_hwdep *opl3hwdep;
3447  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3448
3449The first argument is the ``opl3_t`` instance you created, and the
3450second is the index number, usually 0.
3451
3452The third argument is the index-offset for the sequencer client assigned
3453to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3454always takes 0).
3455
3456Hardware-Dependent Devices
3457--------------------------
3458
3459Some chips need user-space access for special controls or for loading
3460the micro code. In such a case, you can create a hwdep
3461(hardware-dependent) device. The hwdep API is defined in
3462``<sound/hwdep.h>``. You can find examples in opl3 driver or
3463``isa/sb/sb16_csp.c``.
3464
3465The creation of the ``hwdep`` instance is done via
3466:c:func:`snd_hwdep_new()`.
3467
3468::
3469
3470  struct snd_hwdep *hw;
3471  snd_hwdep_new(card, "My HWDEP", 0, &hw);
3472
3473where the third argument is the index number.
3474
3475You can then pass any pointer value to the ``private_data``. If you
3476assign a private data, you should define the destructor, too. The
3477destructor function is set in the ``private_free`` field.
3478
3479::
3480
3481  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3482  hw->private_data = p;
3483  hw->private_free = mydata_free;
3484
3485and the implementation of the destructor would be:
3486
3487::
3488
3489  static void mydata_free(struct snd_hwdep *hw)
3490  {
3491          struct mydata *p = hw->private_data;
3492          kfree(p);
3493  }
3494
3495The arbitrary file operations can be defined for this instance. The file
3496operators are defined in the ``ops`` table. For example, assume that
3497this chip needs an ioctl.
3498
3499::
3500
3501  hw->ops.open = mydata_open;
3502  hw->ops.ioctl = mydata_ioctl;
3503  hw->ops.release = mydata_release;
3504
3505And implement the callback functions as you like.
3506
3507IEC958 (S/PDIF)
3508---------------
3509
3510Usually the controls for IEC958 devices are implemented via the control
3511interface. There is a macro to compose a name string for IEC958
3512controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3513``<include/asound.h>``.
3514
3515There are some standard controls for IEC958 status bits. These controls
3516use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3517fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3518callback, you don't specify the value field for this type (the count
3519field must be set, though).
3520
3521“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3522status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3523returns the bitmask for professional mode. They are read-only controls,
3524and are defined as MIXER controls (iface =
3525``SNDRV_CTL_ELEM_IFACE_MIXER``).
3526
3527Meanwhile, “IEC958 Playback Default” control is defined for getting and
3528setting the current default IEC958 bits. Note that this one is usually
3529defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``),
3530although in some places it's defined as a MIXER control.
3531
3532In addition, you can define the control switches to enable/disable or to
3533set the raw bit mode. The implementation will depend on the chip, but
3534the control should be named as “IEC958 xxx”, preferably using the
3535:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3536
3537You can find several cases, for example, ``pci/emu10k1``,
3538``pci/ice1712``, or ``pci/cmipci.c``.
3539
3540Buffer and Memory Management
3541============================
3542
3543Buffer Types
3544------------
3545
3546ALSA provides several different buffer allocation functions depending on
3547the bus and the architecture. All these have a consistent API. The
3548allocation of physically-contiguous pages is done via
3549:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3550type.
3551
3552The allocation of pages with fallback is
3553:c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
3554to allocate the specified pages but if the pages are not available, it
3555tries to reduce the page sizes until enough space is found.
3556
3557The release the pages, call :c:func:`snd_free_xxx_pages()`
3558function.
3559
3560Usually, ALSA drivers try to allocate and reserve a large contiguous
3561physical space at the time the module is loaded for the later use. This
3562is called “pre-allocation”. As already written, you can call the
3563following function at pcm instance construction time (in the case of PCI
3564bus).
3565
3566::
3567
3568  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3569                                        &pci->dev, size, max);
3570
3571where ``size`` is the byte size to be pre-allocated and the ``max`` is
3572the maximum size to be changed via the ``prealloc`` proc file. The
3573allocator will try to get an area as large as possible within the
3574given size.
3575
3576The second argument (type) and the third argument (device pointer) are
3577dependent on the bus. For normal devices, pass the device pointer
3578(typically identical as ``card->dev``) to the third argument with
3579``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
3580bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3581You can pass NULL to the device pointer in that case, which is the
3582default mode implying to allocate with ``GFP_KERNEL`` flag.
3583If you need a different GFP flag, you can pass it by encoding the flag
3584into the device pointer via a special macro
3585:c:func:`snd_dma_continuous_data()`.
3586For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3587device pointer (see the `Non-Contiguous Buffers`_ section).
3588
3589Once the buffer is pre-allocated, you can use the allocator in the
3590``hw_params`` callback:
3591
3592::
3593
3594  snd_pcm_lib_malloc_pages(substream, size);
3595
3596Note that you have to pre-allocate to use this function.
3597
3598Most of drivers use, though, rather the newly introduced "managed
3599buffer allocation mode" instead of the manual allocation or release.
3600This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3601instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
3602
3603::
3604
3605  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3606                                 &pci->dev, size, max);
3607
3608where passed arguments are identical in both functions.
3609The difference in the managed mode is that PCM core will call
3610:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3611the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3612after the PCM ``hw_free`` callback automatically.  So the driver
3613doesn't have to call these functions explicitly in its callback any
3614longer.  This made many driver code having NULL ``hw_params`` and
3615``hw_free`` entries.
3616
3617External Hardware Buffers
3618-------------------------
3619
3620Some chips have their own hardware buffers and the DMA transfer from the
3621host memory is not available. In such a case, you need to either 1)
3622copy/set the audio data directly to the external hardware buffer, or 2)
3623make an intermediate buffer and copy/set the data from it to the
3624external hardware buffer in interrupts (or in tasklets, preferably).
3625
3626The first case works fine if the external hardware buffer is large
3627enough. This method doesn't need any extra buffers and thus is more
3628effective. You need to define the ``copy_user`` and ``copy_kernel``
3629callbacks for the data transfer, in addition to ``fill_silence``
3630callback for playback. However, there is a drawback: it cannot be
3631mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3632
3633The second case allows for mmap on the buffer, although you have to
3634handle an interrupt or a tasklet to transfer the data from the
3635intermediate buffer to the hardware buffer. You can find an example in
3636the vxpocket driver.
3637
3638Another case is when the chip uses a PCI memory-map region for the
3639buffer instead of the host memory. In this case, mmap is available only
3640on certain architectures like the Intel one. In non-mmap mode, the data
3641cannot be transferred as in the normal way. Thus you need to define the
3642``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3643as in the cases above. The examples are found in ``rme32.c`` and
3644``rme96.c``.
3645
3646The implementation of the ``copy_user``, ``copy_kernel`` and
3647``silence`` callbacks depends upon whether the hardware supports
3648interleaved or non-interleaved samples. The ``copy_user`` callback is
3649defined like below, a bit differently depending whether the direction
3650is playback or capture:
3651
3652::
3653
3654  static int playback_copy_user(struct snd_pcm_substream *substream,
3655               int channel, unsigned long pos,
3656               void __user *src, unsigned long count);
3657  static int capture_copy_user(struct snd_pcm_substream *substream,
3658               int channel, unsigned long pos,
3659               void __user *dst, unsigned long count);
3660
3661In the case of interleaved samples, the second argument (``channel``) is
3662not used. The third argument (``pos``) points the current position
3663offset in bytes.
3664
3665The meaning of the fourth argument is different between playback and
3666capture. For playback, it holds the source data pointer, and for
3667capture, it's the destination data pointer.
3668
3669The last argument is the number of bytes to be copied.
3670
3671What you have to do in this callback is again different between playback
3672and capture directions. In the playback case, you copy the given amount
3673of data (``count``) at the specified pointer (``src``) to the specified
3674offset (``pos``) on the hardware buffer. When coded like memcpy-like
3675way, the copy would be like:
3676
3677::
3678
3679  my_memcpy_from_user(my_buffer + pos, src, count);
3680
3681For the capture direction, you copy the given amount of data (``count``)
3682at the specified offset (``pos``) on the hardware buffer to the
3683specified pointer (``dst``).
3684
3685::
3686
3687  my_memcpy_to_user(dst, my_buffer + pos, count);
3688
3689Here the functions are named as ``from_user`` and ``to_user`` because
3690it's the user-space buffer that is passed to these callbacks.  That
3691is, the callback is supposed to copy from/to the user-space data
3692directly to/from the hardware buffer.
3693
3694Careful readers might notice that these callbacks receive the
3695arguments in bytes, not in frames like other callbacks.  It's because
3696it would make coding easier like the examples above, and also it makes
3697easier to unify both the interleaved and non-interleaved cases, as
3698explained in the following.
3699
3700In the case of non-interleaved samples, the implementation will be a bit
3701more complicated.  The callback is called for each channel, passed by
3702the second argument, so totally it's called for N-channels times per
3703transfer.
3704
3705The meaning of other arguments are almost same as the interleaved
3706case.  The callback is supposed to copy the data from/to the given
3707user-space buffer, but only for the given channel.  For the detailed
3708implementations, please check ``isa/gus/gus_pcm.c`` or
3709"pci/rme9652/rme9652.c" as examples.
3710
3711The above callbacks are the copy from/to the user-space buffer.  There
3712are some cases where we want copy from/to the kernel-space buffer
3713instead.  In such a case, ``copy_kernel`` callback is called.  It'd
3714look like:
3715
3716::
3717
3718  static int playback_copy_kernel(struct snd_pcm_substream *substream,
3719               int channel, unsigned long pos,
3720               void *src, unsigned long count);
3721  static int capture_copy_kernel(struct snd_pcm_substream *substream,
3722               int channel, unsigned long pos,
3723               void *dst, unsigned long count);
3724
3725As found easily, the only difference is that the buffer pointer is
3726without ``__user`` prefix; that is, a kernel-buffer pointer is passed
3727in the fourth argument.  Correspondingly, the implementation would be
3728a version without the user-copy, such as:
3729
3730::
3731
3732  my_memcpy(my_buffer + pos, src, count);
3733
3734Usually for the playback, another callback ``fill_silence`` is
3735defined.  It's implemented in a similar way as the copy callbacks
3736above:
3737
3738::
3739
3740  static int silence(struct snd_pcm_substream *substream, int channel,
3741                     unsigned long pos, unsigned long count);
3742
3743The meanings of arguments are the same as in the ``copy_user`` and
3744``copy_kernel`` callbacks, although there is no buffer pointer
3745argument. In the case of interleaved samples, the channel argument has
3746no meaning, as well as on ``copy_*`` callbacks.
3747
3748The role of ``fill_silence`` callback is to set the given amount
3749(``count``) of silence data at the specified offset (``pos``) on the
3750hardware buffer. Suppose that the data format is signed (that is, the
3751silent-data is 0), and the implementation using a memset-like function
3752would be like:
3753
3754::
3755
3756  my_memset(my_buffer + pos, 0, count);
3757
3758In the case of non-interleaved samples, again, the implementation
3759becomes a bit more complicated, as it's called N-times per transfer
3760for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3761
3762Non-Contiguous Buffers
3763----------------------
3764
3765If your hardware supports the page table as in emu10k1 or the buffer
3766descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
3767provides an interface for handling SG-buffers. The API is provided in
3768``<sound/pcm.h>``.
3769
3770For creating the SG-buffer handler, call
3771:c:func:`snd_pcm_set_managed_buffer()` or
3772:c:func:`snd_pcm_set_managed_buffer_all()` with
3773``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
3774pre-allocator. You need to pass ``&pci->dev``, where pci is
3775the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as
3776well.
3777
3778::
3779
3780  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3781                                 &pci->dev, size, max);
3782
3783The ``struct snd_sg_buf`` instance is created as
3784``substream->dma_private`` in turn. You can cast the pointer like:
3785
3786::
3787
3788  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3789
3790Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3791handler will allocate the non-contiguous kernel pages of the given size
3792and map them onto the virtually contiguous memory. The virtual pointer
3793is addressed in runtime->dma_area. The physical address
3794(``runtime->dma_addr``) is set to zero, because the buffer is
3795physically non-contiguous. The physical address table is set up in
3796``sgbuf->table``. You can get the physical address at a certain offset
3797via :c:func:`snd_pcm_sgbuf_get_addr()`.
3798
3799If you need to release the SG-buffer data explicitly, call the
3800standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3801
3802Vmalloc'ed Buffers
3803------------------
3804
3805It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3806example, for an intermediate buffer. In the recent version of kernel,
3807you can simply allocate it via standard
3808:c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
3809buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
3810
3811::
3812
3813  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3814                                 NULL, 0, 0);
3815
3816The NULL is passed to the device pointer argument, which indicates
3817that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3818allocated.
3819
3820Also, note that zero is passed to both the size and the max size
3821arguments here.  Since each vmalloc call should succeed at any time,
3822we don't need to pre-allocate the buffers like other continuous
3823pages.
3824
3825If you need the 32bit DMA allocation, pass the device pointer encoded
3826by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
3827argument.
3828
3829::
3830
3831  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3832          snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
3833
3834Proc Interface
3835==============
3836
3837ALSA provides an easy interface for procfs. The proc files are very
3838useful for debugging. I recommend you set up proc files if you write a
3839driver and want to get a running status or register dumps. The API is
3840found in ``<sound/info.h>``.
3841
3842To create a proc file, call :c:func:`snd_card_proc_new()`.
3843
3844::
3845
3846  struct snd_info_entry *entry;
3847  int err = snd_card_proc_new(card, "my-file", &entry);
3848
3849where the second argument specifies the name of the proc file to be
3850created. The above example will create a file ``my-file`` under the
3851card directory, e.g. ``/proc/asound/card0/my-file``.
3852
3853Like other components, the proc entry created via
3854:c:func:`snd_card_proc_new()` will be registered and released
3855automatically in the card registration and release functions.
3856
3857When the creation is successful, the function stores a new instance in
3858the pointer given in the third argument. It is initialized as a text
3859proc file for read only. To use this proc file as a read-only text file
3860as it is, set the read callback with a private data via
3861:c:func:`snd_info_set_text_ops()`.
3862
3863::
3864
3865  snd_info_set_text_ops(entry, chip, my_proc_read);
3866
3867where the second argument (``chip``) is the private data to be used in
3868the callbacks. The third parameter specifies the read buffer size and
3869the fourth (``my_proc_read``) is the callback function, which is
3870defined like
3871
3872::
3873
3874  static void my_proc_read(struct snd_info_entry *entry,
3875                           struct snd_info_buffer *buffer);
3876
3877In the read callback, use :c:func:`snd_iprintf()` for output
3878strings, which works just like normal :c:func:`printf()`. For
3879example,
3880
3881::
3882
3883  static void my_proc_read(struct snd_info_entry *entry,
3884                           struct snd_info_buffer *buffer)
3885  {
3886          struct my_chip *chip = entry->private_data;
3887
3888          snd_iprintf(buffer, "This is my chip!\n");
3889          snd_iprintf(buffer, "Port = %ld\n", chip->port);
3890  }
3891
3892The file permissions can be changed afterwards. As default, it's set as
3893read only for all users. If you want to add write permission for the
3894user (root as default), do as follows:
3895
3896::
3897
3898 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3899
3900and set the write buffer size and the callback
3901
3902::
3903
3904  entry->c.text.write = my_proc_write;
3905
3906For the write callback, you can use :c:func:`snd_info_get_line()`
3907to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3908a string from the line. Some examples are found in
3909``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3910
3911For a raw-data proc-file, set the attributes as follows:
3912
3913::
3914
3915  static const struct snd_info_entry_ops my_file_io_ops = {
3916          .read = my_file_io_read,
3917  };
3918
3919  entry->content = SNDRV_INFO_CONTENT_DATA;
3920  entry->private_data = chip;
3921  entry->c.ops = &my_file_io_ops;
3922  entry->size = 4096;
3923  entry->mode = S_IFREG | S_IRUGO;
3924
3925For the raw data, ``size`` field must be set properly. This specifies
3926the maximum size of the proc file access.
3927
3928The read/write callbacks of raw mode are more direct than the text mode.
3929You need to use a low-level I/O functions such as
3930:c:func:`copy_from/to_user()` to transfer the data.
3931
3932::
3933
3934  static ssize_t my_file_io_read(struct snd_info_entry *entry,
3935                              void *file_private_data,
3936                              struct file *file,
3937                              char *buf,
3938                              size_t count,
3939                              loff_t pos)
3940  {
3941          if (copy_to_user(buf, local_data + pos, count))
3942                  return -EFAULT;
3943          return count;
3944  }
3945
3946If the size of the info entry has been set up properly, ``count`` and
3947``pos`` are guaranteed to fit within 0 and the given size. You don't
3948have to check the range in the callbacks unless any other condition is
3949required.
3950
3951Power Management
3952================
3953
3954If the chip is supposed to work with suspend/resume functions, you need
3955to add power-management code to the driver. The additional code for
3956power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3957with __maybe_unused attribute; otherwise the compiler will complain
3958you.
3959
3960If the driver *fully* supports suspend/resume that is, the device can be
3961properly resumed to its state when suspend was called, you can set the
3962``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
3963possible when the registers of the chip can be safely saved and restored
3964to RAM. If this is set, the trigger callback is called with
3965``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3966
3967Even if the driver doesn't support PM fully but partial suspend/resume
3968is still possible, it's still worthy to implement suspend/resume
3969callbacks. In such a case, applications would reset the status by
3970calling :c:func:`snd_pcm_prepare()` and restart the stream
3971appropriately. Hence, you can define suspend/resume callbacks below but
3972don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3973
3974Note that the trigger with SUSPEND can always be called when
3975:c:func:`snd_pcm_suspend_all()` is called, regardless of the
3976``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3977behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3978``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3979callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3980to keep it for compatibility reasons.)
3981
3982In the earlier version of ALSA drivers, a common power-management layer
3983was provided, but it has been removed. The driver needs to define the
3984suspend/resume hooks according to the bus the device is connected to. In
3985the case of PCI drivers, the callbacks look like below:
3986
3987::
3988
3989  static int __maybe_unused snd_my_suspend(struct device *dev)
3990  {
3991          .... /* do things for suspend */
3992          return 0;
3993  }
3994  static int __maybe_unused snd_my_resume(struct device *dev)
3995  {
3996          .... /* do things for suspend */
3997          return 0;
3998  }
3999
4000The scheme of the real suspend job is as follows.
4001
40021. Retrieve the card and the chip data.
4003
40042. Call :c:func:`snd_power_change_state()` with
4005   ``SNDRV_CTL_POWER_D3hot`` to change the power status.
4006
40073. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
4008   each codec.
4009
40104. Save the register values if necessary.
4011
40125. Stop the hardware if necessary.
4013
4014A typical code would be like:
4015
4016::
4017
4018  static int __maybe_unused mychip_suspend(struct device *dev)
4019  {
4020          /* (1) */
4021          struct snd_card *card = dev_get_drvdata(dev);
4022          struct mychip *chip = card->private_data;
4023          /* (2) */
4024          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
4025          /* (3) */
4026          snd_ac97_suspend(chip->ac97);
4027          /* (4) */
4028          snd_mychip_save_registers(chip);
4029          /* (5) */
4030          snd_mychip_stop_hardware(chip);
4031          return 0;
4032  }
4033
4034
4035The scheme of the real resume job is as follows.
4036
40371. Retrieve the card and the chip data.
4038
40392. Re-initialize the chip.
4040
40413. Restore the saved registers if necessary.
4042
40434. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
4044
40455. Restart the hardware (if any).
4046
40476. Call :c:func:`snd_power_change_state()` with
4048   ``SNDRV_CTL_POWER_D0`` to notify the processes.
4049
4050A typical code would be like:
4051
4052::
4053
4054  static int __maybe_unused mychip_resume(struct pci_dev *pci)
4055  {
4056          /* (1) */
4057          struct snd_card *card = dev_get_drvdata(dev);
4058          struct mychip *chip = card->private_data;
4059          /* (2) */
4060          snd_mychip_reinit_chip(chip);
4061          /* (3) */
4062          snd_mychip_restore_registers(chip);
4063          /* (4) */
4064          snd_ac97_resume(chip->ac97);
4065          /* (5) */
4066          snd_mychip_restart_chip(chip);
4067          /* (6) */
4068          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
4069          return 0;
4070  }
4071
4072Note that, at the time this callback gets called, the PCM stream has
4073been already suspended via its own PM ops calling
4074:c:func:`snd_pcm_suspend_all()` internally.
4075
4076OK, we have all callbacks now. Let's set them up. In the initialization
4077of the card, make sure that you can get the chip data from the card
4078instance, typically via ``private_data`` field, in case you created the
4079chip data individually.
4080
4081::
4082
4083  static int snd_mychip_probe(struct pci_dev *pci,
4084                              const struct pci_device_id *pci_id)
4085  {
4086          ....
4087          struct snd_card *card;
4088          struct mychip *chip;
4089          int err;
4090          ....
4091          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4092                             0, &card);
4093          ....
4094          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
4095          ....
4096          card->private_data = chip;
4097          ....
4098  }
4099
4100When you created the chip data with :c:func:`snd_card_new()`, it's
4101anyway accessible via ``private_data`` field.
4102
4103::
4104
4105  static int snd_mychip_probe(struct pci_dev *pci,
4106                              const struct pci_device_id *pci_id)
4107  {
4108          ....
4109          struct snd_card *card;
4110          struct mychip *chip;
4111          int err;
4112          ....
4113          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
4114                             sizeof(struct mychip), &card);
4115          ....
4116          chip = card->private_data;
4117          ....
4118  }
4119
4120If you need a space to save the registers, allocate the buffer for it
4121here, too, since it would be fatal if you cannot allocate a memory in
4122the suspend phase. The allocated buffer should be released in the
4123corresponding destructor.
4124
4125And next, set suspend/resume callbacks to the pci_driver.
4126
4127::
4128
4129  static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
4130
4131  static struct pci_driver driver = {
4132          .name = KBUILD_MODNAME,
4133          .id_table = snd_my_ids,
4134          .probe = snd_my_probe,
4135          .remove = snd_my_remove,
4136          .driver.pm = &snd_my_pm_ops,
4137  };
4138
4139Module Parameters
4140=================
4141
4142There are standard module options for ALSA. At least, each module should
4143have the ``index``, ``id`` and ``enable`` options.
4144
4145If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
4146cards), they should be arrays. The default initial values are defined
4147already as constants for easier programming:
4148
4149::
4150
4151  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
4152  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
4153  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
4154
4155If the module supports only a single card, they could be single
4156variables, instead. ``enable`` option is not always necessary in this
4157case, but it would be better to have a dummy option for compatibility.
4158
4159The module parameters must be declared with the standard
4160``module_param()``, ``module_param_array()`` and
4161:c:func:`MODULE_PARM_DESC()` macros.
4162
4163The typical coding would be like below:
4164
4165::
4166
4167  #define CARD_NAME "My Chip"
4168
4169  module_param_array(index, int, NULL, 0444);
4170  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
4171  module_param_array(id, charp, NULL, 0444);
4172  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
4173  module_param_array(enable, bool, NULL, 0444);
4174  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
4175
4176Also, don't forget to define the module description and the license.
4177Especially, the recent modprobe requires to define the
4178module license as GPL, etc., otherwise the system is shown as “tainted”.
4179
4180::
4181
4182  MODULE_DESCRIPTION("Sound driver for My Chip");
4183  MODULE_LICENSE("GPL");
4184
4185
4186How To Put Your Driver Into ALSA Tree
4187=====================================
4188
4189General
4190-------
4191
4192So far, you've learned how to write the driver codes. And you might have
4193a question now: how to put my own driver into the ALSA driver tree? Here
4194(finally :) the standard procedure is described briefly.
4195
4196Suppose that you create a new PCI driver for the card “xyz”. The card
4197module name would be snd-xyz. The new driver is usually put into the
4198alsa-driver tree, ``sound/pci`` directory in the case of PCI
4199cards.
4200
4201In the following sections, the driver code is supposed to be put into
4202Linux kernel tree. The two cases are covered: a driver consisting of a
4203single source file and one consisting of several source files.
4204
4205Driver with A Single Source File
4206--------------------------------
4207
42081. Modify sound/pci/Makefile
4209
4210   Suppose you have a file xyz.c. Add the following two lines
4211
4212::
4213
4214  snd-xyz-objs := xyz.o
4215  obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4216
42172. Create the Kconfig entry
4218
4219   Add the new entry of Kconfig for your xyz driver. config SND_XYZ
4220   tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
4221   to include support for Foobar XYZ soundcard. To compile this driver
4222   as a module, choose M here: the module will be called snd-xyz. the
4223   line, select SND_PCM, specifies that the driver xyz supports PCM. In
4224   addition to SND_PCM, the following components are supported for
4225   select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
4226   SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
4227   SND_AC97_CODEC. Add the select command for each supported
4228   component.
4229
4230   Note that some selections imply the lowlevel selections. For example,
4231   PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4232   includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4233   the lowlevel selections again.
4234
4235   For the details of Kconfig script, refer to the kbuild documentation.
4236
4237Drivers with Several Source Files
4238---------------------------------
4239
4240Suppose that the driver snd-xyz have several source files. They are
4241located in the new subdirectory, sound/pci/xyz.
4242
42431. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4244   as below
4245
4246::
4247
4248  obj-$(CONFIG_SND) += sound/pci/xyz/
4249
4250
42512. Under the directory ``sound/pci/xyz``, create a Makefile
4252
4253::
4254
4255         snd-xyz-objs := xyz.o abc.o def.o
4256         obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4257
42583. Create the Kconfig entry
4259
4260   This procedure is as same as in the last section.
4261
4262
4263Useful Functions
4264================
4265
4266:c:func:`snd_printk()` and friends
4267----------------------------------
4268
4269.. note:: This subsection describes a few helper functions for
4270   decorating a bit more on the standard :c:func:`printk()` & co.
4271   However, in general, the use of such helpers is no longer recommended.
4272   If possible, try to stick with the standard functions like
4273   :c:func:`dev_err()` or :c:func:`pr_err()`.
4274
4275ALSA provides a verbose version of the :c:func:`printk()` function.
4276If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4277prints the given message together with the file name and the line of the
4278caller. The ``KERN_XXX`` prefix is processed as well as the original
4279:c:func:`printk()` does, so it's recommended to add this prefix,
4280e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4281
4282There are also :c:func:`printk()`'s for debugging.
4283:c:func:`snd_printd()` can be used for general debugging purposes.
4284If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4285just like :c:func:`snd_printk()`. If the ALSA is compiled without
4286the debugging flag, it's ignored.
4287
4288:c:func:`snd_printdd()` is compiled in only when
4289``CONFIG_SND_DEBUG_VERBOSE`` is set.
4290
4291:c:func:`snd_BUG()`
4292-------------------
4293
4294It shows the ``BUG?`` message and stack trace as well as
4295:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4296fatal error happens there.
4297
4298When no debug flag is set, this macro is ignored.
4299
4300:c:func:`snd_BUG_ON()`
4301----------------------
4302
4303:c:func:`snd_BUG_ON()` macro is similar with
4304:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4305it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4306return -EINVAL;
4307
4308The macro takes an conditional expression to evaluate. When
4309``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4310the warning message such as ``BUG? (xxx)`` normally followed by stack
4311trace. In both cases it returns the evaluated value.
4312
4313Acknowledgments
4314===============
4315
4316I would like to thank Phil Kerr for his help for improvement and
4317corrections of this document.
4318
4319Kevin Conder reformatted the original plain-text to the DocBook format.
4320
4321Giuliano Pochini corrected typos and contributed the example codes in
4322the hardware constraints section.
4323