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
22File Tree Structure
23===================
24
25General
26-------
27
28The file tree structure of ALSA driver is depicted below::
29
30            sound
31                    /core
32                            /oss
33                            /seq
34                                    /oss
35                    /include
36                    /drivers
37                            /mpu401
38                            /opl3
39                    /i2c
40                    /synth
41                            /emux
42                    /pci
43                            /(cards)
44                    /isa
45                            /(cards)
46                    /arm
47                    /ppc
48                    /sparc
49                    /usb
50                    /pcmcia /(cards)
51                    /soc
52                    /oss
53
54
55core directory
56--------------
57
58This directory contains the middle layer which is the heart of ALSA
59drivers. In this directory, the native ALSA modules are stored. The
60sub-directories contain different modules and are dependent upon the
61kernel config.
62
63core/oss
64~~~~~~~~
65
66The code for OSS PCM and mixer emulation modules is stored in this
67directory. The OSS rawmidi emulation is included in the ALSA rawmidi
68code since it's quite small. The sequencer code is stored in
69``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
70
71core/seq
72~~~~~~~~
73
74This directory and its sub-directories are for the ALSA sequencer. This
75directory contains the sequencer core and primary sequencer modules such
76as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
77``CONFIG_SND_SEQUENCER`` is set in the kernel config.
78
79core/seq/oss
80~~~~~~~~~~~~
81
82This contains the OSS sequencer emulation code.
83
84include directory
85-----------------
86
87This is the place for the public header files of ALSA drivers, which are
88to be exported to user-space, or included by several files in different
89directories. Basically, the private header files should not be placed in
90this directory, but you may still find files there, due to historical
91reasons :)
92
93drivers directory
94-----------------
95
96This directory contains code shared among different drivers on different
97architectures. They are hence supposed not to be architecture-specific.
98For example, the dummy PCM driver and the serial MIDI driver are found
99in this directory. In the sub-directories, there is code for components
100which are independent from bus and cpu architectures.
101
102drivers/mpu401
103~~~~~~~~~~~~~~
104
105The MPU401 and MPU401-UART modules are stored here.
106
107drivers/opl3 and opl4
108~~~~~~~~~~~~~~~~~~~~~
109
110The OPL3 and OPL4 FM-synth stuff is found here.
111
112i2c directory
113-------------
114
115This contains the ALSA i2c components.
116
117Although there is a standard i2c layer on Linux, ALSA has its own i2c
118code for some cards, because the soundcard needs only a simple operation
119and the standard i2c API is too complicated for such a purpose.
120
121synth directory
122---------------
123
124This contains the synth middle-level modules.
125
126So far, there is only Emu8000/Emu10k1 synth driver under the
127``synth/emux`` sub-directory.
128
129pci directory
130-------------
131
132This directory and its sub-directories hold the top-level card modules
133for PCI soundcards and the code specific to the PCI BUS.
134
135The drivers compiled from a single file are stored directly in the pci
136directory, while the drivers with several source files are stored on
137their own sub-directory (e.g. emu10k1, ice1712).
138
139isa directory
140-------------
141
142This directory and its sub-directories hold the top-level card modules
143for ISA soundcards.
144
145arm, ppc, and sparc directories
146-------------------------------
147
148They are used for top-level card modules which are specific to one of
149these architectures.
150
151usb directory
152-------------
153
154This directory contains the USB-audio driver.
155The USB MIDI driver is integrated in the usb-audio driver.
156
157pcmcia directory
158----------------
159
160The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
161be in the pci directory, because their API is identical to that of
162standard PCI cards.
163
164soc directory
165-------------
166
167This directory contains the codes for ASoC (ALSA System on Chip)
168layer including ASoC core, codec and machine drivers.
169
170oss directory
171-------------
172
173This contains OSS/Lite code.
174At the time of writing, all code has been removed except for dmasound
175on m68k.
176
177
178Basic Flow for PCI Drivers
179==========================
180
181Outline
182-------
183
184The minimum flow for PCI soundcards is as follows:
185
186-  define the PCI ID table (see the section `PCI Entries`_).
187
188-  create ``probe`` callback.
189
190-  create ``remove`` callback.
191
192-  create a struct pci_driver structure
193   containing the three pointers above.
194
195-  create an ``init`` function just calling the
196   :c:func:`pci_register_driver()` to register the pci_driver
197   table defined above.
198
199-  create an ``exit`` function to call the
200   :c:func:`pci_unregister_driver()` function.
201
202Full Code Example
203-----------------
204
205The code example is shown below. Some parts are kept unimplemented at
206this moment but will be filled in the next sections. The numbers in the
207comment lines of the :c:func:`snd_mychip_probe()` function refer
208to details explained in the following section.
209
210::
211
212      #include <linux/init.h>
213      #include <linux/pci.h>
214      #include <linux/slab.h>
215      #include <sound/core.h>
216      #include <sound/initval.h>
217
218      /* module parameters (see "Module Parameters") */
219      /* SNDRV_CARDS: maximum number of cards supported by this module */
220      static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
221      static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
222      static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
223
224      /* definition of the chip-specific record */
225      struct mychip {
226              struct snd_card *card;
227              /* the rest of the implementation will be in section
228               * "PCI Resource Management"
229               */
230      };
231
232      /* chip-specific destructor
233       * (see "PCI Resource Management")
234       */
235      static int snd_mychip_free(struct mychip *chip)
236      {
237              .... /* will be implemented later... */
238      }
239
240      /* component-destructor
241       * (see "Management of Cards and Components")
242       */
243      static int snd_mychip_dev_free(struct snd_device *device)
244      {
245              return snd_mychip_free(device->device_data);
246      }
247
248      /* chip-specific constructor
249       * (see "Management of Cards and Components")
250       */
251      static int snd_mychip_create(struct snd_card *card,
252                                   struct pci_dev *pci,
253                                   struct mychip **rchip)
254      {
255              struct mychip *chip;
256              int err;
257              static const struct snd_device_ops ops = {
258                     .dev_free = snd_mychip_dev_free,
259              };
260
261              *rchip = NULL;
262
263              /* check PCI availability here
264               * (see "PCI Resource Management")
265               */
266              ....
267
268              /* allocate a chip-specific data with zero filled */
269              chip = kzalloc(sizeof(*chip), GFP_KERNEL);
270              if (chip == NULL)
271                      return -ENOMEM;
272
273              chip->card = card;
274
275              /* rest of initialization here; will be implemented
276               * later, see "PCI Resource Management"
277               */
278              ....
279
280              err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
281              if (err < 0) {
282                      snd_mychip_free(chip);
283                      return err;
284              }
285
286              *rchip = chip;
287              return 0;
288      }
289
290      /* constructor -- see "Driver Constructor" sub-section */
291      static int snd_mychip_probe(struct pci_dev *pci,
292                                  const struct pci_device_id *pci_id)
293      {
294              static int dev;
295              struct snd_card *card;
296              struct mychip *chip;
297              int err;
298
299              /* (1) */
300              if (dev >= SNDRV_CARDS)
301                      return -ENODEV;
302              if (!enable[dev]) {
303                      dev++;
304                      return -ENOENT;
305              }
306
307              /* (2) */
308              err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
309                                 0, &card);
310              if (err < 0)
311                      return err;
312
313              /* (3) */
314              err = snd_mychip_create(card, pci, &chip);
315              if (err < 0)
316                      goto error;
317
318              /* (4) */
319              strcpy(card->driver, "My Chip");
320              strcpy(card->shortname, "My Own Chip 123");
321              sprintf(card->longname, "%s at 0x%lx irq %i",
322                      card->shortname, chip->port, chip->irq);
323
324              /* (5) */
325              .... /* implemented later */
326
327              /* (6) */
328              err = snd_card_register(card);
329              if (err < 0)
330                      goto error;
331
332              /* (7) */
333              pci_set_drvdata(pci, card);
334              dev++;
335              return 0;
336
337      error:
338              snd_card_free(card);
339              return err;
340      }
341
342      /* destructor -- see the "Destructor" sub-section */
343      static void snd_mychip_remove(struct pci_dev *pci)
344      {
345              snd_card_free(pci_get_drvdata(pci));
346      }
347
348
349
350Driver Constructor
351------------------
352
353The real constructor of PCI drivers is the ``probe`` callback. The
354``probe`` callback and other component-constructors which are called
355from the ``probe`` callback cannot be used with the ``__init`` prefix
356because any PCI device could be a hotplug device.
357
358In the ``probe`` callback, the following scheme is often used.
359
3601) Check and increment the device index.
361~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362
363::
364
365  static int dev;
366  ....
367  if (dev >= SNDRV_CARDS)
368          return -ENODEV;
369  if (!enable[dev]) {
370          dev++;
371          return -ENOENT;
372  }
373
374
375where ``enable[dev]`` is the module option.
376
377Each time the ``probe`` callback is called, check the availability of
378the device. If not available, simply increment the device index and
379return. dev will be incremented also later (`step 7
380<7) Set the PCI driver data and return zero._>`__).
381
3822) Create a card instance
383~~~~~~~~~~~~~~~~~~~~~~~~~
384
385::
386
387  struct snd_card *card;
388  int err;
389  ....
390  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
391                     0, &card);
392
393
394The details will be explained in the section `Management of Cards and
395Components`_.
396
3973) Create a main component
398~~~~~~~~~~~~~~~~~~~~~~~~~~
399
400In this part, the PCI resources are allocated::
401
402  struct mychip *chip;
403  ....
404  err = snd_mychip_create(card, pci, &chip);
405  if (err < 0)
406          goto error;
407
408The details will be explained in the section `PCI Resource
409Management`_.
410
411When something goes wrong, the probe function needs to deal with the
412error.  In this example, we have a single error handling path placed
413at the end of the function::
414
415  error:
416          snd_card_free(card);
417          return err;
418
419Since each component can be properly freed, the single
420:c:func:`snd_card_free()` call should suffice in most cases.
421
422
4234) Set the driver ID and name strings.
424~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
425
426::
427
428  strcpy(card->driver, "My Chip");
429  strcpy(card->shortname, "My Own Chip 123");
430  sprintf(card->longname, "%s at 0x%lx irq %i",
431          card->shortname, chip->port, chip->irq);
432
433The driver field holds the minimal ID string of the chip. This is used
434by alsa-lib's configurator, so keep it simple but unique. Even the
435same driver can have different driver IDs to distinguish the
436functionality of each chip type.
437
438The shortname field is a string shown as more verbose name. The longname
439field contains the information shown in ``/proc/asound/cards``.
440
4415) Create other components, such as mixer, MIDI, etc.
442~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
443
444Here you define the basic components such as `PCM <PCM Interface_>`__,
445mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
446`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
447Also, if you want a `proc file <Proc Interface_>`__, define it here,
448too.
449
4506) Register the card instance.
451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452
453::
454
455  err = snd_card_register(card);
456  if (err < 0)
457          goto error;
458
459Will be explained in the section `Management of Cards and
460Components`_, too.
461
4627) Set the PCI driver data and return zero.
463~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464
465::
466
467  pci_set_drvdata(pci, card);
468  dev++;
469  return 0;
470
471In the above, the card record is stored. This pointer is used in the
472remove callback and power-management callbacks, too.
473
474Destructor
475----------
476
477The destructor, the remove callback, simply releases the card instance.
478Then the ALSA middle layer will release all the attached components
479automatically.
480
481It would be typically just calling :c:func:`snd_card_free()`::
482
483  static void snd_mychip_remove(struct pci_dev *pci)
484  {
485          snd_card_free(pci_get_drvdata(pci));
486  }
487
488
489The above code assumes that the card pointer is set to the PCI driver
490data.
491
492Header Files
493------------
494
495For the above example, at least the following include files are
496necessary::
497
498  #include <linux/init.h>
499  #include <linux/pci.h>
500  #include <linux/slab.h>
501  #include <sound/core.h>
502  #include <sound/initval.h>
503
504where the last one is necessary only when module options are defined
505in the source file. If the code is split into several files, the files
506without module options don't need them.
507
508In addition to these headers, you'll need ``<linux/interrupt.h>`` for
509interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
510:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
511to include ``<linux/delay.h>`` too.
512
513The ALSA interfaces like the PCM and control APIs are defined in other
514``<sound/xxx.h>`` header files. They have to be included after
515``<sound/core.h>``.
516
517Management of Cards and Components
518==================================
519
520Card Instance
521-------------
522
523For each soundcard, a “card” record must be allocated.
524
525A card record is the headquarters of the soundcard. It manages the whole
526list of devices (components) on the soundcard, such as PCM, mixers,
527MIDI, synthesizer, and so on. Also, the card record holds the ID and the
528name strings of the card, manages the root of proc files, and controls
529the power-management states and hotplug disconnections. The component
530list on the card record is used to manage the correct release of
531resources at destruction.
532
533As mentioned above, to create a card instance, call
534:c:func:`snd_card_new()`::
535
536  struct snd_card *card;
537  int err;
538  err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
539
540
541The function takes six arguments: the parent device pointer, the
542card-index number, the id string, the module pointer (usually
543``THIS_MODULE``), the size of extra-data space, and the pointer to
544return the card instance. The extra_size argument is used to allocate
545card->private_data for the chip-specific data. Note that these data are
546allocated by :c:func:`snd_card_new()`.
547
548The first argument, the pointer of struct device, specifies the parent
549device. For PCI devices, typically ``&pci->`` is passed there.
550
551Components
552----------
553
554After the card is created, you can attach the components (devices) to
555the card instance. In an ALSA driver, a component is represented as a
556struct snd_device object. A component
557can be a PCM instance, a control interface, a raw MIDI interface, etc.
558Each such instance has one component entry.
559
560A component can be created via the :c:func:`snd_device_new()`
561function::
562
563  snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
564
565This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
566data pointer, and the callback pointers (``&ops``). The device-level
567defines the type of components and the order of registration and
568de-registration. For most components, the device-level is already
569defined. For a user-defined component, you can use
570``SNDRV_DEV_LOWLEVEL``.
571
572This function itself doesn't allocate the data space. The data must be
573allocated manually beforehand, and its pointer is passed as the
574argument. This pointer (``chip`` in the above example) is used as the
575identifier for the instance.
576
577Each pre-defined ALSA component such as AC97 and PCM calls
578:c:func:`snd_device_new()` inside its constructor. The destructor
579for each component is defined in the callback pointers. Hence, you don't
580need to take care of calling a destructor for such a component.
581
582If you wish to create your own component, you need to set the destructor
583function to the dev_free callback in the ``ops``, so that it can be
584released automatically via :c:func:`snd_card_free()`. The next
585example will show an implementation of chip-specific data.
586
587Chip-Specific Data
588------------------
589
590Chip-specific information, e.g. the I/O port address, its resource
591pointer, or the irq number, is stored in the chip-specific record::
592
593  struct mychip {
594          ....
595  };
596
597
598In general, there are two ways of allocating the chip record.
599
6001. Allocating via :c:func:`snd_card_new()`.
601~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602
603As mentioned above, you can pass the extra-data-length to the 5th
604argument of :c:func:`snd_card_new()`, e.g.::
605
606  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
607                     sizeof(struct mychip), &card);
608
609struct mychip is the type of the chip record.
610
611In return, the allocated record can be accessed as
612
613::
614
615  struct mychip *chip = card->private_data;
616
617With this method, you don't have to allocate twice. The record is
618released together with the card instance.
619
6202. Allocating an extra device.
621~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
622
623After allocating a card instance via :c:func:`snd_card_new()`
624(with ``0`` on the 4th arg), call :c:func:`kzalloc()`::
625
626  struct snd_card *card;
627  struct mychip *chip;
628  err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
629                     0, &card);
630  .....
631  chip = kzalloc(sizeof(*chip), GFP_KERNEL);
632
633The chip record should have the field to hold the card pointer at least,
634
635::
636
637  struct mychip {
638          struct snd_card *card;
639          ....
640  };
641
642
643Then, set the card pointer in the returned chip instance::
644
645  chip->card = card;
646
647Next, initialize the fields, and register this chip record as a
648low-level device with a specified ``ops``::
649
650  static const struct snd_device_ops ops = {
651          .dev_free =        snd_mychip_dev_free,
652  };
653  ....
654  snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
655
656:c:func:`snd_mychip_dev_free()` is the device-destructor
657function, which will call the real destructor::
658
659  static int snd_mychip_dev_free(struct snd_device *device)
660  {
661          return snd_mychip_free(device->device_data);
662  }
663
664where :c:func:`snd_mychip_free()` is the real destructor.
665
666The demerit of this method is the obviously larger amount of code.
667The merit is, however, that you can trigger your own callback at
668registering and disconnecting the card via a setting in snd_device_ops.
669About registering and disconnecting the card, see the subsections
670below.
671
672
673Registration and Release
674------------------------
675
676After all components are assigned, register the card instance by calling
677:c:func:`snd_card_register()`. Access to the device files is
678enabled at this point. That is, before
679:c:func:`snd_card_register()` is called, the components are safely
680inaccessible from external side. If this call fails, exit the probe
681function after releasing the card via :c:func:`snd_card_free()`.
682
683For releasing the card instance, you can call simply
684:c:func:`snd_card_free()`. As mentioned earlier, all components
685are released automatically by this call.
686
687For a device which allows hotplugging, you can use
688:c:func:`snd_card_free_when_closed()`. This one will postpone
689the destruction until all devices are closed.
690
691PCI Resource Management
692=======================
693
694Full Code Example
695-----------------
696
697In this section, we'll complete the chip-specific constructor,
698destructor and PCI entries. Example code is shown first, below::
699
700      struct mychip {
701              struct snd_card *card;
702              struct pci_dev *pci;
703
704              unsigned long port;
705              int irq;
706      };
707
708      static int snd_mychip_free(struct mychip *chip)
709      {
710              /* disable hardware here if any */
711              .... /* (not implemented in this document) */
712
713              /* release the irq */
714              if (chip->irq >= 0)
715                      free_irq(chip->irq, chip);
716              /* release the I/O ports & memory */
717              pci_release_regions(chip->pci);
718              /* disable the PCI entry */
719              pci_disable_device(chip->pci);
720              /* release the data */
721              kfree(chip);
722              return 0;
723      }
724
725      /* chip-specific constructor */
726      static int snd_mychip_create(struct snd_card *card,
727                                   struct pci_dev *pci,
728                                   struct mychip **rchip)
729      {
730              struct mychip *chip;
731              int err;
732              static const struct snd_device_ops ops = {
733                     .dev_free = snd_mychip_dev_free,
734              };
735
736              *rchip = NULL;
737
738              /* initialize the PCI entry */
739              err = pci_enable_device(pci);
740              if (err < 0)
741                      return err;
742              /* check PCI availability (28bit DMA) */
743              if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
744                  pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
745                      printk(KERN_ERR "error to set 28bit mask DMA\n");
746                      pci_disable_device(pci);
747                      return -ENXIO;
748              }
749
750              chip = kzalloc(sizeof(*chip), GFP_KERNEL);
751              if (chip == NULL) {
752                      pci_disable_device(pci);
753                      return -ENOMEM;
754              }
755
756              /* initialize the stuff */
757              chip->card = card;
758              chip->pci = pci;
759              chip->irq = -1;
760
761              /* (1) PCI resource allocation */
762              err = pci_request_regions(pci, "My Chip");
763              if (err < 0) {
764                      kfree(chip);
765                      pci_disable_device(pci);
766                      return err;
767              }
768              chip->port = pci_resource_start(pci, 0);
769              if (request_irq(pci->irq, snd_mychip_interrupt,
770                              IRQF_SHARED, KBUILD_MODNAME, chip)) {
771                      printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
772                      snd_mychip_free(chip);
773                      return -EBUSY;
774              }
775              chip->irq = pci->irq;
776              card->sync_irq = chip->irq;
777
778              /* (2) initialization of the chip hardware */
779              .... /*   (not implemented in this document) */
780
781              err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
782              if (err < 0) {
783                      snd_mychip_free(chip);
784                      return err;
785              }
786
787              *rchip = chip;
788              return 0;
789      }
790
791      /* PCI IDs */
792      static struct pci_device_id snd_mychip_ids[] = {
793              { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
794                PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
795              ....
796              { 0, }
797      };
798      MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
799
800      /* pci_driver definition */
801      static struct pci_driver driver = {
802              .name = KBUILD_MODNAME,
803              .id_table = snd_mychip_ids,
804              .probe = snd_mychip_probe,
805              .remove = snd_mychip_remove,
806      };
807
808      /* module initialization */
809      static int __init alsa_card_mychip_init(void)
810      {
811              return pci_register_driver(&driver);
812      }
813
814      /* module clean up */
815      static void __exit alsa_card_mychip_exit(void)
816      {
817              pci_unregister_driver(&driver);
818      }
819
820      module_init(alsa_card_mychip_init)
821      module_exit(alsa_card_mychip_exit)
822
823      EXPORT_NO_SYMBOLS; /* for old kernels only */
824
825Some Hafta's
826------------
827
828The allocation of PCI resources is done in the ``probe`` function, and
829usually an extra :c:func:`xxx_create()` function is written for this
830purpose.
831
832In the case of PCI devices, you first have to call the
833:c:func:`pci_enable_device()` function before allocating
834resources. Also, you need to set the proper PCI DMA mask to limit the
835accessed I/O range. In some cases, you might need to call
836:c:func:`pci_set_master()` function, too.
837
838Suppose a 28bit mask, the code to be added would look like::
839
840  err = pci_enable_device(pci);
841  if (err < 0)
842          return err;
843  if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
844      pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
845          printk(KERN_ERR "error to set 28bit mask DMA\n");
846          pci_disable_device(pci);
847          return -ENXIO;
848  }
849
850
851Resource Allocation
852-------------------
853
854The allocation of I/O ports and irqs is done via standard kernel
855functions.  These resources must be released in the destructor
856function (see below).
857
858Now assume that the PCI device has an I/O port with 8 bytes and an
859interrupt. Then struct mychip will have the
860following fields::
861
862  struct mychip {
863          struct snd_card *card;
864
865          unsigned long port;
866          int irq;
867  };
868
869
870For an I/O port (and also a memory region), you need to have the
871resource pointer for the standard resource management. For an irq, you
872have to keep only the irq number (integer). But you need to initialize
873this number to -1 before actual allocation, since irq 0 is valid. The
874port address and its resource pointer can be initialized as null by
875:c:func:`kzalloc()` automatically, so you don't have to take care of
876resetting them.
877
878The allocation of an I/O port is done like this::
879
880  err = pci_request_regions(pci, "My Chip");
881  if (err < 0) {
882          kfree(chip);
883          pci_disable_device(pci);
884          return err;
885  }
886  chip->port = pci_resource_start(pci, 0);
887
888It will reserve the I/O port region of 8 bytes of the given PCI device.
889The returned value, ``chip->res_port``, is allocated via
890:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
891must be released via :c:func:`kfree()`, but there is a problem with
892this. This issue will be explained later.
893
894The allocation of an interrupt source is done like this::
895
896  if (request_irq(pci->irq, snd_mychip_interrupt,
897                  IRQF_SHARED, KBUILD_MODNAME, chip)) {
898          printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
899          snd_mychip_free(chip);
900          return -EBUSY;
901  }
902  chip->irq = pci->irq;
903
904where :c:func:`snd_mychip_interrupt()` is the interrupt handler
905defined `later <PCM Interrupt Handler_>`__. Note that
906``chip->irq`` should be defined only when :c:func:`request_irq()`
907succeeded.
908
909On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
910as the interrupt flag of :c:func:`request_irq()`.
911
912The last argument of :c:func:`request_irq()` is the data pointer
913passed to the interrupt handler. Usually, the chip-specific record is
914used for that, but you can use what you like, too.
915
916I won't give details about the interrupt handler at this point, but at
917least its appearance can be explained now. The interrupt handler looks
918usually as follows::
919
920  static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
921  {
922          struct mychip *chip = dev_id;
923          ....
924          return IRQ_HANDLED;
925  }
926
927After requesting the IRQ, you can passed it to ``card->sync_irq``
928field::
929
930          card->irq = chip->irq;
931
932This allows the PCM core to automatically call
933:c:func:`synchronize_irq()` at the right time, like before ``hw_free``.
934See the later section `sync_stop callback`_ for details.
935
936Now let's write the corresponding destructor for the resources above.
937The role of destructor is simple: disable the hardware (if already
938activated) and release the resources. So far, we have no hardware part,
939so the disabling code is not written here.
940
941To release the resources, the “check-and-release” method is a safer way.
942For the interrupt, do like this::
943
944  if (chip->irq >= 0)
945          free_irq(chip->irq, chip);
946
947Since the irq number can start from 0, you should initialize
948``chip->irq`` with a negative value (e.g. -1), so that you can check
949the validity of the irq number as above.
950
951When you requested I/O ports or memory regions via
952:c:func:`pci_request_region()` or
953:c:func:`pci_request_regions()` like in this example, release the
954resource(s) using the corresponding function,
955:c:func:`pci_release_region()` or
956:c:func:`pci_release_regions()`::
957
958  pci_release_regions(chip->pci);
959
960When you requested manually via :c:func:`request_region()` or
961:c:func:`request_mem_region()`, you can release it via
962:c:func:`release_resource()`. Suppose that you keep the resource
963pointer returned from :c:func:`request_region()` in
964chip->res_port, the release procedure looks like::
965
966  release_and_free_resource(chip->res_port);
967
968Don't forget to call :c:func:`pci_disable_device()` before the
969end.
970
971And finally, release the chip-specific record::
972
973  kfree(chip);
974
975We didn't implement the hardware disabling part above. If you
976need to do this, please note that the destructor may be called even
977before the initialization of the chip is completed. It would be better
978to have a flag to skip hardware disabling if the hardware was not
979initialized yet.
980
981When the chip-data is assigned to the card using
982:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its
983destructor is called last. That is, it is assured that all other
984components like PCMs and controls have already been released. You don't
985have to stop PCMs, etc. explicitly, but just call low-level hardware
986stopping.
987
988The management of a memory-mapped region is almost as same as the
989management of an I/O port. You'll need two fields as follows::
990
991  struct mychip {
992          ....
993          unsigned long iobase_phys;
994          void __iomem *iobase_virt;
995  };
996
997and the allocation would look like below::
998
999  err = pci_request_regions(pci, "My Chip");
1000  if (err < 0) {
1001          kfree(chip);
1002          return err;
1003  }
1004  chip->iobase_phys = pci_resource_start(pci, 0);
1005  chip->iobase_virt = ioremap(chip->iobase_phys,
1006                                      pci_resource_len(pci, 0));
1007
1008and the corresponding destructor would be::
1009
1010  static int snd_mychip_free(struct mychip *chip)
1011  {
1012          ....
1013          if (chip->iobase_virt)
1014                  iounmap(chip->iobase_virt);
1015          ....
1016          pci_release_regions(chip->pci);
1017          ....
1018  }
1019
1020Of course, a modern way with :c:func:`pci_iomap()` will make things a
1021bit easier, too::
1022
1023  err = pci_request_regions(pci, "My Chip");
1024  if (err < 0) {
1025          kfree(chip);
1026          return err;
1027  }
1028  chip->iobase_virt = pci_iomap(pci, 0, 0);
1029
1030which is paired with :c:func:`pci_iounmap()` at destructor.
1031
1032
1033PCI Entries
1034-----------
1035
1036So far, so good. Let's finish the missing PCI stuff. At first, we need a
1037struct pci_device_id table for
1038this chipset. It's a table of PCI vendor/device ID number, and some
1039masks.
1040
1041For example::
1042
1043  static struct pci_device_id snd_mychip_ids[] = {
1044          { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
1045            PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
1046          ....
1047          { 0, }
1048  };
1049  MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
1050
1051The first and second fields of the struct pci_device_id are the vendor
1052and device IDs. If you have no reason to filter the matching devices, you can
1053leave the remaining fields as above. The last field of the
1054struct pci_device_id contains private data for this entry. You can specify
1055any value here, for example, to define specific operations for supported
1056device IDs. Such an example is found in the intel8x0 driver.
1057
1058The last entry of this list is the terminator. You must specify this
1059all-zero entry.
1060
1061Then, prepare the struct pci_driver
1062record::
1063
1064  static struct pci_driver driver = {
1065          .name = KBUILD_MODNAME,
1066          .id_table = snd_mychip_ids,
1067          .probe = snd_mychip_probe,
1068          .remove = snd_mychip_remove,
1069  };
1070
1071The ``probe`` and ``remove`` functions have already been defined in
1072the previous sections. The ``name`` field is the name string of this
1073device. Note that you must not use slashes (“/”) in this string.
1074
1075And at last, the module entries::
1076
1077  static int __init alsa_card_mychip_init(void)
1078  {
1079          return pci_register_driver(&driver);
1080  }
1081
1082  static void __exit alsa_card_mychip_exit(void)
1083  {
1084          pci_unregister_driver(&driver);
1085  }
1086
1087  module_init(alsa_card_mychip_init)
1088  module_exit(alsa_card_mychip_exit)
1089
1090Note that these module entries are tagged with ``__init`` and ``__exit``
1091prefixes.
1092
1093That's all!
1094
1095PCM Interface
1096=============
1097
1098General
1099-------
1100
1101The PCM middle layer of ALSA is quite powerful and it is only necessary
1102for each driver to implement the low-level functions to access its
1103hardware.
1104
1105To access the PCM layer, you need to include ``<sound/pcm.h>``
1106first. In addition, ``<sound/pcm_params.h>`` might be needed if you
1107access some functions related with hw_param.
1108
1109Each card device can have up to four PCM instances. A PCM instance
1110corresponds to a PCM device file. The limitation of number of instances
1111comes only from the available bit size of Linux' device numbers.
1112Once 64bit device numbers are used, we'll have more PCM instances
1113available.
1114
1115A PCM instance consists of PCM playback and capture streams, and each
1116PCM stream consists of one or more PCM substreams. Some soundcards
1117support multiple playback functions. For example, emu10k1 has a PCM
1118playback of 32 stereo substreams. In this case, at each open, a free
1119substream is (usually) automatically chosen and opened. Meanwhile, when
1120only one substream exists and it was already opened, a subsequent open
1121will either block or error with ``EAGAIN`` according to the file open
1122mode. But you don't have to care about such details in your driver. The
1123PCM middle layer will take care of such work.
1124
1125Full Code Example
1126-----------------
1127
1128The example code below does not include any hardware access routines but
1129shows only the skeleton, how to build up the PCM interfaces::
1130
1131      #include <sound/pcm.h>
1132      ....
1133
1134      /* hardware definition */
1135      static struct snd_pcm_hardware snd_mychip_playback_hw = {
1136              .info = (SNDRV_PCM_INFO_MMAP |
1137                       SNDRV_PCM_INFO_INTERLEAVED |
1138                       SNDRV_PCM_INFO_BLOCK_TRANSFER |
1139                       SNDRV_PCM_INFO_MMAP_VALID),
1140              .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1141              .rates =            SNDRV_PCM_RATE_8000_48000,
1142              .rate_min =         8000,
1143              .rate_max =         48000,
1144              .channels_min =     2,
1145              .channels_max =     2,
1146              .buffer_bytes_max = 32768,
1147              .period_bytes_min = 4096,
1148              .period_bytes_max = 32768,
1149              .periods_min =      1,
1150              .periods_max =      1024,
1151      };
1152
1153      /* hardware definition */
1154      static struct snd_pcm_hardware snd_mychip_capture_hw = {
1155              .info = (SNDRV_PCM_INFO_MMAP |
1156                       SNDRV_PCM_INFO_INTERLEAVED |
1157                       SNDRV_PCM_INFO_BLOCK_TRANSFER |
1158                       SNDRV_PCM_INFO_MMAP_VALID),
1159              .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1160              .rates =            SNDRV_PCM_RATE_8000_48000,
1161              .rate_min =         8000,
1162              .rate_max =         48000,
1163              .channels_min =     2,
1164              .channels_max =     2,
1165              .buffer_bytes_max = 32768,
1166              .period_bytes_min = 4096,
1167              .period_bytes_max = 32768,
1168              .periods_min =      1,
1169              .periods_max =      1024,
1170      };
1171
1172      /* open callback */
1173      static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
1174      {
1175              struct mychip *chip = snd_pcm_substream_chip(substream);
1176              struct snd_pcm_runtime *runtime = substream->runtime;
1177
1178              runtime->hw = snd_mychip_playback_hw;
1179              /* more hardware-initialization will be done here */
1180              ....
1181              return 0;
1182      }
1183
1184      /* close callback */
1185      static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
1186      {
1187              struct mychip *chip = snd_pcm_substream_chip(substream);
1188              /* the hardware-specific codes will be here */
1189              ....
1190              return 0;
1191
1192      }
1193
1194      /* open callback */
1195      static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
1196      {
1197              struct mychip *chip = snd_pcm_substream_chip(substream);
1198              struct snd_pcm_runtime *runtime = substream->runtime;
1199
1200              runtime->hw = snd_mychip_capture_hw;
1201              /* more hardware-initialization will be done here */
1202              ....
1203              return 0;
1204      }
1205
1206      /* close callback */
1207      static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
1208      {
1209              struct mychip *chip = snd_pcm_substream_chip(substream);
1210              /* the hardware-specific codes will be here */
1211              ....
1212              return 0;
1213      }
1214
1215      /* hw_params callback */
1216      static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
1217                                   struct snd_pcm_hw_params *hw_params)
1218      {
1219              /* the hardware-specific codes will be here */
1220              ....
1221              return 0;
1222      }
1223
1224      /* hw_free callback */
1225      static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
1226      {
1227              /* the hardware-specific codes will be here */
1228              ....
1229              return 0;
1230      }
1231
1232      /* prepare callback */
1233      static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
1234      {
1235              struct mychip *chip = snd_pcm_substream_chip(substream);
1236              struct snd_pcm_runtime *runtime = substream->runtime;
1237
1238              /* set up the hardware with the current configuration
1239               * for example...
1240               */
1241              mychip_set_sample_format(chip, runtime->format);
1242              mychip_set_sample_rate(chip, runtime->rate);
1243              mychip_set_channels(chip, runtime->channels);
1244              mychip_set_dma_setup(chip, runtime->dma_addr,
1245                                   chip->buffer_size,
1246                                   chip->period_size);
1247              return 0;
1248      }
1249
1250      /* trigger callback */
1251      static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
1252                                        int cmd)
1253      {
1254              switch (cmd) {
1255              case SNDRV_PCM_TRIGGER_START:
1256                      /* do something to start the PCM engine */
1257                      ....
1258                      break;
1259              case SNDRV_PCM_TRIGGER_STOP:
1260                      /* do something to stop the PCM engine */
1261                      ....
1262                      break;
1263              default:
1264                      return -EINVAL;
1265              }
1266      }
1267
1268      /* pointer callback */
1269      static snd_pcm_uframes_t
1270      snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
1271      {
1272              struct mychip *chip = snd_pcm_substream_chip(substream);
1273              unsigned int current_ptr;
1274
1275              /* get the current hardware pointer */
1276              current_ptr = mychip_get_hw_pointer(chip);
1277              return current_ptr;
1278      }
1279
1280      /* operators */
1281      static struct snd_pcm_ops snd_mychip_playback_ops = {
1282              .open =        snd_mychip_playback_open,
1283              .close =       snd_mychip_playback_close,
1284              .hw_params =   snd_mychip_pcm_hw_params,
1285              .hw_free =     snd_mychip_pcm_hw_free,
1286              .prepare =     snd_mychip_pcm_prepare,
1287              .trigger =     snd_mychip_pcm_trigger,
1288              .pointer =     snd_mychip_pcm_pointer,
1289      };
1290
1291      /* operators */
1292      static struct snd_pcm_ops snd_mychip_capture_ops = {
1293              .open =        snd_mychip_capture_open,
1294              .close =       snd_mychip_capture_close,
1295              .hw_params =   snd_mychip_pcm_hw_params,
1296              .hw_free =     snd_mychip_pcm_hw_free,
1297              .prepare =     snd_mychip_pcm_prepare,
1298              .trigger =     snd_mychip_pcm_trigger,
1299              .pointer =     snd_mychip_pcm_pointer,
1300      };
1301
1302      /*
1303       *  definitions of capture are omitted here...
1304       */
1305
1306      /* create a pcm device */
1307      static int snd_mychip_new_pcm(struct mychip *chip)
1308      {
1309              struct snd_pcm *pcm;
1310              int err;
1311
1312              err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1313              if (err < 0)
1314                      return err;
1315              pcm->private_data = chip;
1316              strcpy(pcm->name, "My Chip");
1317              chip->pcm = pcm;
1318              /* set operators */
1319              snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1320                              &snd_mychip_playback_ops);
1321              snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1322                              &snd_mychip_capture_ops);
1323              /* pre-allocation of buffers */
1324              /* NOTE: this may fail */
1325              snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1326                                             &chip->pci->dev,
1327                                             64*1024, 64*1024);
1328              return 0;
1329      }
1330
1331
1332PCM Constructor
1333---------------
1334
1335A PCM instance is allocated by the :c:func:`snd_pcm_new()`
1336function. It would be better to create a constructor for the PCM, namely::
1337
1338  static int snd_mychip_new_pcm(struct mychip *chip)
1339  {
1340          struct snd_pcm *pcm;
1341          int err;
1342
1343          err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
1344          if (err < 0)
1345                  return err;
1346          pcm->private_data = chip;
1347          strcpy(pcm->name, "My Chip");
1348          chip->pcm = pcm;
1349          ...
1350          return 0;
1351  }
1352
1353The :c:func:`snd_pcm_new()` function takes six arguments. The
1354first argument is the card pointer to which this PCM is assigned, and
1355the second is the ID string.
1356
1357The third argument (``index``, 0 in the above) is the index of this new
1358PCM. It begins from zero. If you create more than one PCM instances,
1359specify the different numbers in this argument. For example, ``index =
13601`` for the second PCM device.
1361
1362The fourth and fifth arguments are the number of substreams for playback
1363and capture, respectively. Here 1 is used for both arguments. When no
1364playback or capture substreams are available, pass 0 to the
1365corresponding argument.
1366
1367If a chip supports multiple playbacks or captures, you can specify more
1368numbers, but they must be handled properly in open/close, etc.
1369callbacks. When you need to know which substream you are referring to,
1370then it can be obtained from struct snd_pcm_substream data passed to each
1371callback as follows::
1372
1373  struct snd_pcm_substream *substream;
1374  int index = substream->number;
1375
1376
1377After the PCM is created, you need to set operators for each PCM stream::
1378
1379  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
1380                  &snd_mychip_playback_ops);
1381  snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
1382                  &snd_mychip_capture_ops);
1383
1384The operators are defined typically like this::
1385
1386  static struct snd_pcm_ops snd_mychip_playback_ops = {
1387          .open =        snd_mychip_pcm_open,
1388          .close =       snd_mychip_pcm_close,
1389          .hw_params =   snd_mychip_pcm_hw_params,
1390          .hw_free =     snd_mychip_pcm_hw_free,
1391          .prepare =     snd_mychip_pcm_prepare,
1392          .trigger =     snd_mychip_pcm_trigger,
1393          .pointer =     snd_mychip_pcm_pointer,
1394  };
1395
1396All the callbacks are described in the Operators_ subsection.
1397
1398After setting the operators, you probably will want to pre-allocate the
1399buffer and set up the managed allocation mode.
1400For that, simply call the following::
1401
1402  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
1403                                 &chip->pci->dev,
1404                                 64*1024, 64*1024);
1405
1406It will allocate a buffer up to 64kB by default. Buffer management
1407details will be described in the later section `Buffer and Memory
1408Management`_.
1409
1410Additionally, you can set some extra information for this PCM in
1411``pcm->info_flags``. The available values are defined as
1412``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
1413hardware definition (described later). When your soundchip supports only
1414half-duplex, specify it like this::
1415
1416  pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
1417
1418
1419... And the Destructor?
1420-----------------------
1421
1422The destructor for a PCM instance is not always necessary. Since the PCM
1423device will be released by the middle layer code automatically, you
1424don't have to call the destructor explicitly.
1425
1426The destructor would be necessary if you created special records
1427internally and needed to release them. In such a case, set the
1428destructor function to ``pcm->private_free``::
1429
1430      static void mychip_pcm_free(struct snd_pcm *pcm)
1431      {
1432              struct mychip *chip = snd_pcm_chip(pcm);
1433              /* free your own data */
1434              kfree(chip->my_private_pcm_data);
1435              /* do what you like else */
1436              ....
1437      }
1438
1439      static int snd_mychip_new_pcm(struct mychip *chip)
1440      {
1441              struct snd_pcm *pcm;
1442              ....
1443              /* allocate your own data */
1444              chip->my_private_pcm_data = kmalloc(...);
1445              /* set the destructor */
1446              pcm->private_data = chip;
1447              pcm->private_free = mychip_pcm_free;
1448              ....
1449      }
1450
1451
1452
1453Runtime Pointer - The Chest of PCM Information
1454----------------------------------------------
1455
1456When the PCM substream is opened, a PCM runtime instance is allocated
1457and assigned to the substream. This pointer is accessible via
1458``substream->runtime``. This runtime pointer holds most information you
1459need to control the PCM: a copy of hw_params and sw_params
1460configurations, the buffer pointers, mmap records, spinlocks, etc.
1461
1462The definition of runtime instance is found in ``<sound/pcm.h>``. Here
1463is the relevant part of this file::
1464
1465  struct _snd_pcm_runtime {
1466          /* -- Status -- */
1467          struct snd_pcm_substream *trigger_master;
1468          snd_timestamp_t trigger_tstamp;	/* trigger timestamp */
1469          int overrange;
1470          snd_pcm_uframes_t avail_max;
1471          snd_pcm_uframes_t hw_ptr_base;	/* Position at buffer restart */
1472          snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
1473
1474          /* -- HW params -- */
1475          snd_pcm_access_t access;	/* access mode */
1476          snd_pcm_format_t format;	/* SNDRV_PCM_FORMAT_* */
1477          snd_pcm_subformat_t subformat;	/* subformat */
1478          unsigned int rate;		/* rate in Hz */
1479          unsigned int channels;		/* channels */
1480          snd_pcm_uframes_t period_size;	/* period size */
1481          unsigned int periods;		/* periods */
1482          snd_pcm_uframes_t buffer_size;	/* buffer size */
1483          unsigned int tick_time;		/* tick time */
1484          snd_pcm_uframes_t min_align;	/* Min alignment for the format */
1485          size_t byte_align;
1486          unsigned int frame_bits;
1487          unsigned int sample_bits;
1488          unsigned int info;
1489          unsigned int rate_num;
1490          unsigned int rate_den;
1491
1492          /* -- SW params -- */
1493          struct timespec tstamp_mode;	/* mmap timestamp is updated */
1494          unsigned int period_step;
1495          unsigned int sleep_min;		/* min ticks to sleep */
1496          snd_pcm_uframes_t start_threshold;
1497          /*
1498           * The following two thresholds alleviate playback buffer underruns; when
1499           * hw_avail drops below the threshold, the respective action is triggered:
1500           */
1501          snd_pcm_uframes_t stop_threshold;	/* - stop playback */
1502          snd_pcm_uframes_t silence_threshold;	/* - pre-fill buffer with silence */
1503          snd_pcm_uframes_t silence_size;       /* max size of silence pre-fill; when >= boundary,
1504                                                 * fill played area with silence immediately */
1505          snd_pcm_uframes_t boundary;	/* pointers wrap point */
1506
1507          /* internal data of auto-silencer */
1508          snd_pcm_uframes_t silence_start; /* starting pointer to silence area */
1509          snd_pcm_uframes_t silence_filled; /* size filled with silence */
1510
1511          snd_pcm_sync_id_t sync;		/* hardware synchronization ID */
1512
1513          /* -- mmap -- */
1514          volatile struct snd_pcm_mmap_status *status;
1515          volatile struct snd_pcm_mmap_control *control;
1516          atomic_t mmap_count;
1517
1518          /* -- locking / scheduling -- */
1519          spinlock_t lock;
1520          wait_queue_head_t sleep;
1521          struct timer_list tick_timer;
1522          struct fasync_struct *fasync;
1523
1524          /* -- private section -- */
1525          void *private_data;
1526          void (*private_free)(struct snd_pcm_runtime *runtime);
1527
1528          /* -- hardware description -- */
1529          struct snd_pcm_hardware hw;
1530          struct snd_pcm_hw_constraints hw_constraints;
1531
1532          /* -- timer -- */
1533          unsigned int timer_resolution;	/* timer resolution */
1534
1535          /* -- DMA -- */
1536          unsigned char *dma_area;	/* DMA area */
1537          dma_addr_t dma_addr;		/* physical bus address (not accessible from main CPU) */
1538          size_t dma_bytes;		/* size of DMA area */
1539
1540          struct snd_dma_buffer *dma_buffer_p;	/* allocated buffer */
1541
1542  #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
1543          /* -- OSS things -- */
1544          struct snd_pcm_oss_runtime oss;
1545  #endif
1546  };
1547
1548
1549For the operators (callbacks) of each sound driver, most of these
1550records are supposed to be read-only. Only the PCM middle-layer changes
1551/ updates them. The exceptions are the hardware description (hw) DMA
1552buffer information and the private data. Besides, if you use the
1553standard managed buffer allocation mode, you don't need to set the
1554DMA buffer information by yourself.
1555
1556In the sections below, important records are explained.
1557
1558Hardware Description
1559~~~~~~~~~~~~~~~~~~~~
1560
1561The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
1562the fundamental hardware configuration. Above all, you'll need to define this
1563in the `PCM open callback`_. Note that the runtime instance holds a copy of
1564the descriptor, not a pointer to the existing descriptor. That is,
1565in the open callback, you can modify the copied descriptor
1566(``runtime->hw``) as you need. For example, if the maximum number of
1567channels is 1 only on some chip models, you can still use the same
1568hardware descriptor and change the channels_max later::
1569
1570          struct snd_pcm_runtime *runtime = substream->runtime;
1571          ...
1572          runtime->hw = snd_mychip_playback_hw; /* common definition */
1573          if (chip->model == VERY_OLD_ONE)
1574                  runtime->hw.channels_max = 1;
1575
1576Typically, you'll have a hardware descriptor as below::
1577
1578  static struct snd_pcm_hardware snd_mychip_playback_hw = {
1579          .info = (SNDRV_PCM_INFO_MMAP |
1580                   SNDRV_PCM_INFO_INTERLEAVED |
1581                   SNDRV_PCM_INFO_BLOCK_TRANSFER |
1582                   SNDRV_PCM_INFO_MMAP_VALID),
1583          .formats =          SNDRV_PCM_FMTBIT_S16_LE,
1584          .rates =            SNDRV_PCM_RATE_8000_48000,
1585          .rate_min =         8000,
1586          .rate_max =         48000,
1587          .channels_min =     2,
1588          .channels_max =     2,
1589          .buffer_bytes_max = 32768,
1590          .period_bytes_min = 4096,
1591          .period_bytes_max = 32768,
1592          .periods_min =      1,
1593          .periods_max =      1024,
1594  };
1595
1596-  The ``info`` field contains the type and capabilities of this
1597   PCM. The bit flags are defined in ``<sound/asound.h>`` as
1598   ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
1599   mmap is supported and which interleaving formats are
1600   supported. When the hardware supports mmap, add the
1601   ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
1602   interleaved or the non-interleaved formats, the
1603   ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
1604   flag must be set, respectively. If both are supported, you can set
1605   both, too.
1606
1607   In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
1608   specified for the OSS mmap mode. Usually both are set. Of course,
1609   ``MMAP_VALID`` is set only if mmap is really supported.
1610
1611   The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
1612   ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM
1613   supports the “pause” operation, while the ``RESUME`` bit means that
1614   the PCM supports the full “suspend/resume” operation. If the
1615   ``PAUSE`` flag is set, the ``trigger`` callback below must handle
1616   the corresponding (pause push/release) commands. The suspend/resume
1617   trigger commands can be defined even without the ``RESUME``
1618   flag. See the `Power Management`_ section for details.
1619
1620   When the PCM substreams can be synchronized (typically,
1621   synchronized start/stop of a playback and a capture stream), you
1622   can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
1623   need to check the linked-list of PCM substreams in the trigger
1624   callback. This will be described in a later section.
1625
1626-  The ``formats`` field contains the bit-flags of supported formats
1627   (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
1628   format, give all or'ed bits. In the example above, the signed 16bit
1629   little-endian format is specified.
1630
1631-  The ``rates`` field contains the bit-flags of supported rates
1632   (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
1633   pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits
1634   are provided only for typical rates. If your chip supports
1635   unconventional rates, you need to add the ``KNOT`` bit and set up
1636   the hardware constraint manually (explained later).
1637
1638-  ``rate_min`` and ``rate_max`` define the minimum and maximum sample
1639   rate. This should correspond somehow to ``rates`` bits.
1640
1641-  ``channels_min`` and ``channels_max`` define, as you might have already
1642   expected, the minimum and maximum number of channels.
1643
1644-  ``buffer_bytes_max`` defines the maximum buffer size in
1645   bytes. There is no ``buffer_bytes_min`` field, since it can be
1646   calculated from the minimum period size and the minimum number of
1647   periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max``
1648   define the minimum and maximum size of the period in bytes.
1649   ``periods_max`` and ``periods_min`` define the maximum and minimum
1650   number of periods in the buffer.
1651
1652   The “period” is a term that corresponds to a fragment in the OSS
1653   world. The period defines the point at which a PCM interrupt is
1654   generated. This point strongly depends on the hardware. Generally,
1655   a smaller period size will give you more interrupts, which results
1656   in being able to fill/drain the buffer more timely. In the case of
1657   capture, this size defines the input latency. On the other hand,
1658   the whole buffer size defines the output latency for the playback
1659   direction.
1660
1661-  There is also a field ``fifo_size``. This specifies the size of the
1662   hardware FIFO, but currently it is neither used by the drivers nor
1663   in the alsa-lib. So, you can ignore this field.
1664
1665PCM Configurations
1666~~~~~~~~~~~~~~~~~~
1667
1668Ok, let's go back again to the PCM runtime records. The most
1669frequently referred records in the runtime instance are the PCM
1670configurations. The PCM configurations are stored in the runtime
1671instance after the application sends ``hw_params`` data via
1672alsa-lib. There are many fields copied from hw_params and sw_params
1673structs. For example, ``format`` holds the format type chosen by the
1674application. This field contains the enum value
1675``SNDRV_PCM_FORMAT_XXX``.
1676
1677One thing to be noted is that the configured buffer and period sizes
1678are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
1679channels \* samples-size``. For conversion between frames and bytes,
1680you can use the :c:func:`frames_to_bytes()` and
1681:c:func:`bytes_to_frames()` helper functions::
1682
1683  period_bytes = frames_to_bytes(runtime, runtime->period_size);
1684
1685Also, many software parameters (sw_params) are stored in frames, too.
1686Please check the type of the field. ``snd_pcm_uframes_t`` is for
1687frames as unsigned integer while ``snd_pcm_sframes_t`` is for
1688frames as signed integer.
1689
1690DMA Buffer Information
1691~~~~~~~~~~~~~~~~~~~~~~
1692
1693The DMA buffer is defined by the following four fields: ``dma_area``,
1694``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area``
1695holds the buffer pointer (the logical address). You can call
1696:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
1697the physical address of the buffer. This field is specified only when
1698the buffer is a linear buffer. ``dma_bytes`` holds the size of the
1699buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator.
1700
1701If you use either the managed buffer allocation mode or the standard
1702API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
1703these fields are set by the ALSA middle layer, and you should *not*
1704change them by yourself. You can read them but not write them. On the
1705other hand, if you want to allocate the buffer by yourself, you'll
1706need to manage it in the hw_params callback. At least, ``dma_bytes`` is
1707mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
1708your driver doesn't support mmap, this field is not
1709necessary. ``dma_addr`` is also optional. You can use dma_private as
1710you like, too.
1711
1712Running Status
1713~~~~~~~~~~~~~~
1714
1715The running status can be referred via ``runtime->status``. This is
1716a pointer to a struct snd_pcm_mmap_status record.
1717For example, you can get the current
1718DMA hardware pointer via ``runtime->status->hw_ptr``.
1719
1720The DMA application pointer can be referred via ``runtime->control``,
1721which points to a struct snd_pcm_mmap_control record.
1722However, accessing this value directly is not recommended.
1723
1724Private Data
1725~~~~~~~~~~~~
1726
1727You can allocate a record for the substream and store it in
1728``runtime->private_data``. Usually, this is done in the `PCM open
1729callback`_. Don't mix this with ``pcm->private_data``. The
1730``pcm->private_data`` usually points to the chip instance assigned
1731statically at creation time of the PCM device, while
1732``runtime->private_data``
1733points to a dynamic data structure created in the PCM open
1734callback::
1735
1736  static int snd_xxx_open(struct snd_pcm_substream *substream)
1737  {
1738          struct my_pcm_data *data;
1739          ....
1740          data = kmalloc(sizeof(*data), GFP_KERNEL);
1741          substream->runtime->private_data = data;
1742          ....
1743  }
1744
1745
1746The allocated object must be released in the `close callback`_.
1747
1748Operators
1749---------
1750
1751OK, now let me give details about each PCM callback (``ops``). In
1752general, every callback must return 0 if successful, or a negative
1753error number such as ``-EINVAL``. To choose an appropriate error
1754number, it is advised to check what value other parts of the kernel
1755return when the same kind of request fails.
1756
1757Each callback function takes at least one argument containing a
1758struct snd_pcm_substream pointer. To retrieve the chip
1759record from the given substream instance, you can use the following
1760macro::
1761
1762  int xxx(...) {
1763          struct mychip *chip = snd_pcm_substream_chip(substream);
1764          ....
1765  }
1766
1767The macro reads ``substream->private_data``, which is a copy of
1768``pcm->private_data``. You can override the former if you need to
1769assign different data records per PCM substream. For example, the
1770cmi8330 driver assigns different ``private_data`` for playback and
1771capture directions, because it uses two different codecs (SB- and
1772AD-compatible) for different directions.
1773
1774PCM open callback
1775~~~~~~~~~~~~~~~~~
1776
1777::
1778
1779  static int snd_xxx_open(struct snd_pcm_substream *substream);
1780
1781This is called when a PCM substream is opened.
1782
1783At least, here you have to initialize the ``runtime->hw``
1784record. Typically, this is done like this::
1785
1786  static int snd_xxx_open(struct snd_pcm_substream *substream)
1787  {
1788          struct mychip *chip = snd_pcm_substream_chip(substream);
1789          struct snd_pcm_runtime *runtime = substream->runtime;
1790
1791          runtime->hw = snd_mychip_playback_hw;
1792          return 0;
1793  }
1794
1795where ``snd_mychip_playback_hw`` is the pre-defined hardware
1796description.
1797
1798You can allocate private data in this callback, as described in the
1799`Private Data`_ section.
1800
1801If the hardware configuration needs more constraints, set the hardware
1802constraints here, too. See Constraints_ for more details.
1803
1804close callback
1805~~~~~~~~~~~~~~
1806
1807::
1808
1809  static int snd_xxx_close(struct snd_pcm_substream *substream);
1810
1811
1812Obviously, this is called when a PCM substream is closed.
1813
1814Any private instance for a PCM substream allocated in the ``open``
1815callback will be released here::
1816
1817  static int snd_xxx_close(struct snd_pcm_substream *substream)
1818  {
1819          ....
1820          kfree(substream->runtime->private_data);
1821          ....
1822  }
1823
1824ioctl callback
1825~~~~~~~~~~~~~~
1826
1827This is used for any special call to PCM ioctls. But usually you can
1828leave it NULL, then the PCM core calls the generic ioctl callback
1829function :c:func:`snd_pcm_lib_ioctl()`.  If you need to deal with a
1830unique setup of channel info or reset procedure, you can pass your own
1831callback function here.
1832
1833hw_params callback
1834~~~~~~~~~~~~~~~~~~~
1835
1836::
1837
1838  static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
1839                               struct snd_pcm_hw_params *hw_params);
1840
1841This is called when the hardware parameters (``hw_params``) are set up
1842by the application, that is, once when the buffer size, the period
1843size, the format, etc. are defined for the PCM substream.
1844
1845Many hardware setups should be done in this callback, including the
1846allocation of buffers.
1847
1848Parameters to be initialized are retrieved by the
1849:c:func:`params_xxx()` macros.
1850
1851When you choose managed buffer allocation mode for the substream,
1852a buffer is already allocated before this callback gets
1853called. Alternatively, you can call a helper function below for
1854allocating the buffer::
1855
1856  snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
1857
1858:c:func:`snd_pcm_lib_malloc_pages()` is available only when the
1859DMA buffers have been pre-allocated. See the section `Buffer Types`_
1860for more details.
1861
1862Note that this one and the ``prepare`` callback may be called multiple
1863times per initialization. For example, the OSS emulation may call these
1864callbacks at each change via its ioctl.
1865
1866Thus, you need to be careful not to allocate the same buffers many
1867times, which will lead to memory leaks! Calling the helper function
1868above many times is OK. It will release the previous buffer
1869automatically when it was already allocated.
1870
1871Another note is that this callback is non-atomic (schedulable) by
1872default, i.e. when no ``nonatomic`` flag set. This is important,
1873because the ``trigger`` callback is atomic (non-schedulable). That is,
1874mutexes or any schedule-related functions are not available in the
1875``trigger`` callback. Please see the subsection Atomicity_ for
1876details.
1877
1878hw_free callback
1879~~~~~~~~~~~~~~~~~
1880
1881::
1882
1883  static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
1884
1885This is called to release the resources allocated via
1886``hw_params``.
1887
1888This function is always called before the close callback is called.
1889Also, the callback may be called multiple times, too. Keep track
1890whether each resource was already released.
1891
1892When you have chosen managed buffer allocation mode for the PCM
1893substream, the allocated PCM buffer will be automatically released
1894after this callback gets called.  Otherwise you'll have to release the
1895buffer manually.  Typically, when the buffer was allocated from the
1896pre-allocated pool, you can use the standard API function
1897:c:func:`snd_pcm_lib_malloc_pages()` like::
1898
1899  snd_pcm_lib_free_pages(substream);
1900
1901prepare callback
1902~~~~~~~~~~~~~~~~
1903
1904::
1905
1906  static int snd_xxx_prepare(struct snd_pcm_substream *substream);
1907
1908This callback is called when the PCM is “prepared”. You can set the
1909format type, sample rate, etc. here. The difference from ``hw_params``
1910is that the ``prepare`` callback will be called each time
1911:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
1912underruns, etc.
1913
1914Note that this callback is non-atomic. You can use
1915schedule-related functions safely in this callback.
1916
1917In this and the following callbacks, you can refer to the values via
1918the runtime record, ``substream->runtime``. For example, to get the
1919current rate, format or channels, access to ``runtime->rate``,
1920``runtime->format`` or ``runtime->channels``, respectively. The
1921physical address of the allocated buffer is set to
1922``runtime->dma_area``. The buffer and period sizes are in
1923``runtime->buffer_size`` and ``runtime->period_size``, respectively.
1924
1925Be careful that this callback will be called many times at each setup,
1926too.
1927
1928trigger callback
1929~~~~~~~~~~~~~~~~
1930
1931::
1932
1933  static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
1934
1935This is called when the PCM is started, stopped or paused.
1936
1937The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX``
1938defined in ``<sound/pcm.h>``. At least, the ``START``
1939and ``STOP`` commands must be defined in this callback::
1940
1941  switch (cmd) {
1942  case SNDRV_PCM_TRIGGER_START:
1943          /* do something to start the PCM engine */
1944          break;
1945  case SNDRV_PCM_TRIGGER_STOP:
1946          /* do something to stop the PCM engine */
1947          break;
1948  default:
1949          return -EINVAL;
1950  }
1951
1952When the PCM supports the pause operation (given in the info field of
1953the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
1954must be handled here, too. The former is the command to pause the PCM,
1955and the latter to restart the PCM again.
1956
1957When the PCM supports the suspend/resume operation, regardless of full
1958or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
1959commands must be handled, too. These commands are issued when the
1960power-management status is changed. Obviously, the ``SUSPEND`` and
1961``RESUME`` commands suspend and resume the PCM substream, and usually,
1962they are identical to the ``STOP`` and ``START`` commands, respectively.
1963See the `Power Management`_ section for details.
1964
1965As mentioned, this callback is atomic by default unless the ``nonatomic``
1966flag set, and you cannot call functions which may sleep. The
1967``trigger`` callback should be as minimal as possible, just really
1968triggering the DMA. The other stuff should be initialized in
1969``hw_params`` and ``prepare`` callbacks properly beforehand.
1970
1971sync_stop callback
1972~~~~~~~~~~~~~~~~~~
1973
1974::
1975
1976  static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
1977
1978This callback is optional, and NULL can be passed.  It's called after
1979the PCM core stops the stream, before it changes the stream state via
1980``prepare``, ``hw_params`` or ``hw_free``.
1981Since the IRQ handler might be still pending, we need to wait until
1982the pending task finishes before moving to the next step; otherwise it
1983might lead to a crash due to resource conflicts or access to freed
1984resources.  A typical behavior is to call a synchronization function
1985like :c:func:`synchronize_irq()` here.
1986
1987For the majority of drivers that need only a call of
1988:c:func:`synchronize_irq()`, there is a simpler setup, too.
1989While keeping the ``sync_stop`` PCM callback NULL, the driver can set
1990the ``card->sync_irq`` field to the returned interrupt number after
1991requesting an IRQ, instead.   Then PCM core will call
1992:c:func:`synchronize_irq()` with the given IRQ appropriately.
1993
1994If the IRQ handler is released by the card destructor, you don't need
1995to clear ``card->sync_irq``, as the card itself is being released.
1996So, usually you'll need to add just a single line for assigning
1997``card->sync_irq`` in the driver code unless the driver re-acquires
1998the IRQ.  When the driver frees and re-acquires the IRQ dynamically
1999(e.g. for suspend/resume), it needs to clear and re-set
2000``card->sync_irq`` again appropriately.
2001
2002pointer callback
2003~~~~~~~~~~~~~~~~
2004
2005::
2006
2007  static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
2008
2009This callback is called when the PCM middle layer inquires the current
2010hardware position in the buffer. The position must be returned in
2011frames, ranging from 0 to ``buffer_size - 1``.
2012
2013This is usually called from the buffer-update routine in the PCM
2014middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
2015is called by the interrupt routine. Then the PCM middle layer updates
2016the position and calculates the available space, and wakes up the
2017sleeping poll threads, etc.
2018
2019This callback is also atomic by default.
2020
2021copy_user, copy_kernel and fill_silence ops
2022~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2023
2024These callbacks are not mandatory, and can be omitted in most cases.
2025These callbacks are used when the hardware buffer cannot be in the
2026normal memory space. Some chips have their own buffer in the hardware
2027which is not mappable. In such a case, you have to transfer the data
2028manually from the memory buffer to the hardware buffer. Or, if the
2029buffer is non-contiguous on both physical and virtual memory spaces,
2030these callbacks must be defined, too.
2031
2032If these two callbacks are defined, copy and set-silence operations
2033are done by them. The details will be described in the later section
2034`Buffer and Memory Management`_.
2035
2036ack callback
2037~~~~~~~~~~~~
2038
2039This callback is also not mandatory. This callback is called when the
2040``appl_ptr`` is updated in read or write operations. Some drivers like
2041emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
2042internal buffer, and this callback is useful only for such a purpose.
2043
2044The callback function may return 0 or a negative error. When the
2045return value is ``-EPIPE``, PCM core treats that as a buffer XRUN,
2046and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically.
2047
2048This callback is atomic by default.
2049
2050page callback
2051~~~~~~~~~~~~~
2052
2053This callback is optional too. The mmap calls this callback to get the
2054page fault address.
2055
2056You need no special callback for the standard SG-buffer or vmalloc-
2057buffer. Hence this callback should be rarely used.
2058
2059mmap callback
2060~~~~~~~~~~~~~
2061
2062This is another optional callback for controlling mmap behavior.
2063When defined, the PCM core calls this callback when a page is
2064memory-mapped, instead of using the standard helper.
2065If you need special handling (due to some architecture or
2066device-specific issues), implement everything here as you like.
2067
2068
2069PCM Interrupt Handler
2070---------------------
2071
2072The remainder of the PCM stuff is the PCM interrupt handler. The role
2073of the PCM
2074interrupt handler in the sound driver is to update the buffer position
2075and to tell the PCM middle layer when the buffer position goes across
2076the specified period boundary. To inform about this, call the
2077:c:func:`snd_pcm_period_elapsed()` function.
2078
2079There are several ways sound chips can generate interrupts.
2080
2081Interrupts at the period (fragment) boundary
2082~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2083
2084This is the most frequently found type: the hardware generates an
2085interrupt at each period boundary. In this case, you can call
2086:c:func:`snd_pcm_period_elapsed()` at each interrupt.
2087
2088:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
2089its argument. Thus, you need to keep the substream pointer accessible
2090from the chip instance. For example, define ``substream`` field in the
2091chip record to hold the current running substream pointer, and set the
2092pointer value at ``open`` callback (and reset at ``close`` callback).
2093
2094If you acquire a spinlock in the interrupt handler, and the lock is used
2095in other PCM callbacks, too, then you have to release the lock before
2096calling :c:func:`snd_pcm_period_elapsed()`, because
2097:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks
2098inside.
2099
2100Typical code would look like::
2101
2102
2103      static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2104      {
2105              struct mychip *chip = dev_id;
2106              spin_lock(&chip->lock);
2107              ....
2108              if (pcm_irq_invoked(chip)) {
2109                      /* call updater, unlock before it */
2110                      spin_unlock(&chip->lock);
2111                      snd_pcm_period_elapsed(chip->substream);
2112                      spin_lock(&chip->lock);
2113                      /* acknowledge the interrupt if necessary */
2114              }
2115              ....
2116              spin_unlock(&chip->lock);
2117              return IRQ_HANDLED;
2118      }
2119
2120Also, when the device can detect a buffer underrun/overrun, the driver
2121can notify the XRUN status to the PCM core by calling
2122:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets
2123the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
2124outside the PCM stream lock, hence it can't be called from the atomic
2125callback.
2126
2127
2128High frequency timer interrupts
2129~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2130
2131This happens when the hardware doesn't generate interrupts at the period
2132boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
2133or ymfpci drivers). In this case, you need to check the current hardware
2134position and accumulate the processed sample length at each interrupt.
2135When the accumulated size exceeds the period size, call
2136:c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
2137
2138Typical code would look as follows::
2139
2140
2141      static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
2142      {
2143              struct mychip *chip = dev_id;
2144              spin_lock(&chip->lock);
2145              ....
2146              if (pcm_irq_invoked(chip)) {
2147                      unsigned int last_ptr, size;
2148                      /* get the current hardware pointer (in frames) */
2149                      last_ptr = get_hw_ptr(chip);
2150                      /* calculate the processed frames since the
2151                       * last update
2152                       */
2153                      if (last_ptr < chip->last_ptr)
2154                              size = runtime->buffer_size + last_ptr
2155                                       - chip->last_ptr;
2156                      else
2157                              size = last_ptr - chip->last_ptr;
2158                      /* remember the last updated point */
2159                      chip->last_ptr = last_ptr;
2160                      /* accumulate the size */
2161                      chip->size += size;
2162                      /* over the period boundary? */
2163                      if (chip->size >= runtime->period_size) {
2164                              /* reset the accumulator */
2165                              chip->size %= runtime->period_size;
2166                              /* call updater */
2167                              spin_unlock(&chip->lock);
2168                              snd_pcm_period_elapsed(substream);
2169                              spin_lock(&chip->lock);
2170                      }
2171                      /* acknowledge the interrupt if necessary */
2172              }
2173              ....
2174              spin_unlock(&chip->lock);
2175              return IRQ_HANDLED;
2176      }
2177
2178
2179
2180On calling :c:func:`snd_pcm_period_elapsed()`
2181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2182
2183In both cases, even if more than one period has elapsed, you don't have
2184to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
2185once. And the PCM layer will check the current hardware pointer and
2186update to the latest status.
2187
2188Atomicity
2189---------
2190
2191One of the most important (and thus difficult to debug) problems in
2192kernel programming are race conditions. In the Linux kernel, they are
2193usually avoided via spin-locks, mutexes or semaphores. In general, if a
2194race condition can happen in an interrupt handler, it has to be managed
2195atomically, and you have to use a spinlock to protect the critical
2196section. If the critical section is not in interrupt handler code and if
2197taking a relatively long time to execute is acceptable, you should use
2198mutexes or semaphores instead.
2199
2200As already seen, some PCM callbacks are atomic and some are not. For
2201example, the ``hw_params`` callback is non-atomic, while the ``trigger``
2202callback is atomic. This means, the latter is called already in a
2203spinlock held by the PCM middle layer, the PCM stream lock. Please
2204take this atomicity into account when you choose a locking scheme in
2205the callbacks.
2206
2207In the atomic callbacks, you cannot use functions which may call
2208:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
2209mutexes can sleep, and hence they cannot be used inside the atomic
2210callbacks (e.g. ``trigger`` callback). To implement some delay in such a
2211callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
2212
2213All three atomic callbacks (trigger, pointer, and ack) are called with
2214local interrupts disabled.
2215
2216However, it is possible to request all PCM operations to be non-atomic.
2217This assumes that all call sites are in
2218non-atomic contexts. For example, the function
2219:c:func:`snd_pcm_period_elapsed()` is called typically from the
2220interrupt handler. But, if you set up the driver to use a threaded
2221interrupt handler, this call can be in non-atomic context, too. In such
2222a case, you can set the ``nonatomic`` field of the struct snd_pcm object
2223after creating it. When this flag is set, mutex and rwsem are used internally
2224in the PCM core instead of spin and rwlocks, so that you can call all PCM
2225functions safely in a non-atomic
2226context.
2227
2228Also, in some cases, you might need to call
2229:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
2230period gets elapsed during ``ack`` or other callback). There is a
2231variant that can be called inside the PCM stream lock
2232:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,
2233too.
2234
2235Constraints
2236-----------
2237
2238Due to physical limitations, hardware is not infinitely configurable.
2239These limitations are expressed by setting constraints.
2240
2241For example, in order to restrict the sample rates to some supported
2242values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
2243call this function in the open callback::
2244
2245      static unsigned int rates[] =
2246              {4000, 10000, 22050, 44100};
2247      static struct snd_pcm_hw_constraint_list constraints_rates = {
2248              .count = ARRAY_SIZE(rates),
2249              .list = rates,
2250              .mask = 0,
2251      };
2252
2253      static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
2254      {
2255              int err;
2256              ....
2257              err = snd_pcm_hw_constraint_list(substream->runtime, 0,
2258                                               SNDRV_PCM_HW_PARAM_RATE,
2259                                               &constraints_rates);
2260              if (err < 0)
2261                      return err;
2262              ....
2263      }
2264
2265There are many different constraints. Look at ``sound/pcm.h`` for a
2266complete list. You can even define your own constraint rules. For
2267example, let's suppose my_chip can manage a substream of 1 channel if
2268and only if the format is ``S16_LE``, otherwise it supports any format
2269specified in struct snd_pcm_hardware (or in any other
2270constraint_list). You can build a rule like this::
2271
2272      static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
2273                                            struct snd_pcm_hw_rule *rule)
2274      {
2275              struct snd_interval *c = hw_param_interval(params,
2276                            SNDRV_PCM_HW_PARAM_CHANNELS);
2277              struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2278              struct snd_interval ch;
2279
2280              snd_interval_any(&ch);
2281              if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
2282                      ch.min = ch.max = 1;
2283                      ch.integer = 1;
2284                      return snd_interval_refine(c, &ch);
2285              }
2286              return 0;
2287      }
2288
2289
2290Then you need to call this function to add your rule::
2291
2292  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
2293                      hw_rule_channels_by_format, NULL,
2294                      SNDRV_PCM_HW_PARAM_FORMAT, -1);
2295
2296The rule function is called when an application sets the PCM format, and
2297it refines the number of channels accordingly. But an application may
2298set the number of channels before setting the format. Thus you also need
2299to define the inverse rule::
2300
2301      static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
2302                                            struct snd_pcm_hw_rule *rule)
2303      {
2304              struct snd_interval *c = hw_param_interval(params,
2305                    SNDRV_PCM_HW_PARAM_CHANNELS);
2306              struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
2307              struct snd_mask fmt;
2308
2309              snd_mask_any(&fmt);    /* Init the struct */
2310              if (c->min < 2) {
2311                      fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
2312                      return snd_mask_refine(f, &fmt);
2313              }
2314              return 0;
2315      }
2316
2317
2318... and in the open callback::
2319
2320  snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
2321                      hw_rule_format_by_channels, NULL,
2322                      SNDRV_PCM_HW_PARAM_CHANNELS, -1);
2323
2324One typical usage of the hw constraints is to align the buffer size
2325with the period size.  By default, ALSA PCM core doesn't enforce the
2326buffer size to be aligned with the period size.  For example, it'd be
2327possible to have a combination like 256 period bytes with 999 buffer
2328bytes.
2329
2330Many device chips, however, require the buffer to be a multiple of
2331periods.  In such a case, call
2332:c:func:`snd_pcm_hw_constraint_integer()` for
2333``SNDRV_PCM_HW_PARAM_PERIODS``::
2334
2335  snd_pcm_hw_constraint_integer(substream->runtime,
2336                                SNDRV_PCM_HW_PARAM_PERIODS);
2337
2338This assures that the number of periods is integer, hence the buffer
2339size is aligned with the period size.
2340
2341The hw constraint is a very powerful mechanism to define the
2342preferred PCM configuration, and there are relevant helpers.
2343I won't give more details here, rather I would like to say, “Luke, use
2344the source.”
2345
2346Control Interface
2347=================
2348
2349General
2350-------
2351
2352The control interface is used widely for many switches, sliders, etc.
2353which are accessed from user-space. Its most important use is the mixer
2354interface. In other words, since ALSA 0.9.x, all the mixer stuff is
2355implemented on the control kernel API.
2356
2357ALSA has a well-defined AC97 control module. If your chip supports only
2358the AC97 and nothing else, you can skip this section.
2359
2360The control API is defined in ``<sound/control.h>``. Include this file
2361if you want to add your own controls.
2362
2363Definition of Controls
2364----------------------
2365
2366To create a new control, you need to define the following three
2367callbacks: ``info``, ``get`` and ``put``. Then, define a
2368struct snd_kcontrol_new record, such as::
2369
2370
2371      static struct snd_kcontrol_new my_control = {
2372              .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
2373              .name = "PCM Playback Switch",
2374              .index = 0,
2375              .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
2376              .private_value = 0xffff,
2377              .info = my_control_info,
2378              .get = my_control_get,
2379              .put = my_control_put
2380      };
2381
2382
2383The ``iface`` field specifies the control type,
2384``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
2385for global controls that are not logically part of the mixer. If the
2386control is closely associated with some specific device on the sound
2387card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
2388and specify the device number with the ``device`` and ``subdevice``
2389fields.
2390
2391The ``name`` is the name identifier string. Since ALSA 0.9.x, the
2392control name is very important, because its role is classified from
2393its name. There are pre-defined standard control names. The details
2394are described in the `Control Names`_ subsection.
2395
2396The ``index`` field holds the index number of this control. If there
2397are several different controls with the same name, they can be
2398distinguished by the index number. This is the case when several
2399codecs exist on the card. If the index is zero, you can omit the
2400definition above.
2401
2402The ``access`` field contains the access type of this control. Give
2403the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
2404there. The details will be explained in the `Access Flags`_
2405subsection.
2406
2407The ``private_value`` field contains an arbitrary long integer value
2408for this record. When using the generic ``info``, ``get`` and ``put``
2409callbacks, you can pass a value through this field. If several small
2410numbers are necessary, you can combine them in bitwise. Or, it's
2411possible to store a pointer (casted to unsigned long) of some record in
2412this field, too.
2413
2414The ``tlv`` field can be used to provide metadata about the control;
2415see the `Metadata`_ subsection.
2416
2417The other three are `Control Callbacks`_.
2418
2419Control Names
2420-------------
2421
2422There are some standards to define the control names. A control is
2423usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
2424
2425The first, ``SOURCE``, specifies the source of the control, and is a
2426string such as “Master”, “PCM”, “CD” and “Line”. There are many
2427pre-defined sources.
2428
2429The second, ``DIRECTION``, is one of the following strings according to
2430the direction of the control: “Playback”, “Capture”, “Bypass Playback”
2431and “Bypass Capture”. Or, it can be omitted, meaning both playback and
2432capture directions.
2433
2434The third, ``FUNCTION``, is one of the following strings according to
2435the function of the control: “Switch”, “Volume” and “Route”.
2436
2437The example of control names are, thus, “Master Capture Switch” or “PCM
2438Playback Volume”.
2439
2440There are some exceptions:
2441
2442Global capture and playback
2443~~~~~~~~~~~~~~~~~~~~~~~~~~~
2444
2445“Capture Source”, “Capture Switch” and “Capture Volume” are used for the
2446global capture (input) source, switch and volume. Similarly, “Playback
2447Switch” and “Playback Volume” are used for the global output gain switch
2448and volume.
2449
2450Tone-controls
2451~~~~~~~~~~~~~
2452
2453tone-control switch and volumes are specified like “Tone Control - XXX”,
2454e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
2455Center”.
2456
24573D controls
2458~~~~~~~~~~~
2459
24603D-control switches and volumes are specified like “3D Control - XXX”,
2461e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
2462
2463Mic boost
2464~~~~~~~~~
2465
2466Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
2467
2468More precise information can be found in
2469``Documentation/sound/designs/control-names.rst``.
2470
2471Access Flags
2472------------
2473
2474The access flag is the bitmask which specifies the access type of the
2475given control. The default access type is
2476``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
2477allowed to this control. When the access flag is omitted (i.e. = 0), it
2478is considered as ``READWRITE`` access by default.
2479
2480When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
2481instead. In this case, you don't have to define the ``put`` callback.
2482Similarly, when the control is write-only (although it's a rare case),
2483you can use the ``WRITE`` flag instead, and you don't need the ``get``
2484callback.
2485
2486If the control value changes frequently (e.g. the VU meter),
2487``VOLATILE`` flag should be given. This means that the control may be
2488changed without `Change notification`_. Applications should poll such
2489a control constantly.
2490
2491When the control may be updated, but currently has no effect on anything,
2492setting the ``INACTIVE`` flag may be appropriate. For example, PCM
2493controls should be inactive while no PCM device is open.
2494
2495There are ``LOCK`` and ``OWNER`` flags to change the write permissions.
2496
2497Control Callbacks
2498-----------------
2499
2500info callback
2501~~~~~~~~~~~~~
2502
2503The ``info`` callback is used to get detailed information on this
2504control. This must store the values of the given
2505struct snd_ctl_elem_info object. For example,
2506for a boolean control with a single element::
2507
2508
2509      static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
2510                              struct snd_ctl_elem_info *uinfo)
2511      {
2512              uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
2513              uinfo->count = 1;
2514              uinfo->value.integer.min = 0;
2515              uinfo->value.integer.max = 1;
2516              return 0;
2517      }
2518
2519
2520
2521The ``type`` field specifies the type of the control. There are
2522``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
2523``INTEGER64``. The ``count`` field specifies the number of elements in
2524this control. For example, a stereo volume would have count = 2. The
2525``value`` field is a union, and the values stored depend on the
2526type. The boolean and integer types are identical.
2527
2528The enumerated type is a bit different from the others. You'll need to
2529set the string for the selectec item index::
2530
2531  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2532                          struct snd_ctl_elem_info *uinfo)
2533  {
2534          static char *texts[4] = {
2535                  "First", "Second", "Third", "Fourth"
2536          };
2537          uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
2538          uinfo->count = 1;
2539          uinfo->value.enumerated.items = 4;
2540          if (uinfo->value.enumerated.item > 3)
2541                  uinfo->value.enumerated.item = 3;
2542          strcpy(uinfo->value.enumerated.name,
2543                 texts[uinfo->value.enumerated.item]);
2544          return 0;
2545  }
2546
2547The above callback can be simplified with a helper function,
2548:c:func:`snd_ctl_enum_info()`. The final code looks like below.
2549(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
2550it's a matter of taste.)
2551
2552::
2553
2554  static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
2555                          struct snd_ctl_elem_info *uinfo)
2556  {
2557          static char *texts[4] = {
2558                  "First", "Second", "Third", "Fourth"
2559          };
2560          return snd_ctl_enum_info(uinfo, 1, 4, texts);
2561  }
2562
2563
2564Some common info callbacks are available for your convenience:
2565:c:func:`snd_ctl_boolean_mono_info()` and
2566:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
2567is an info callback for a mono channel boolean item, just like
2568:c:func:`snd_myctl_mono_info()` above, and the latter is for a
2569stereo channel boolean item.
2570
2571get callback
2572~~~~~~~~~~~~
2573
2574This callback is used to read the current value of the control, so it
2575can be returned to user-space.
2576
2577For example::
2578
2579      static int snd_myctl_get(struct snd_kcontrol *kcontrol,
2580                               struct snd_ctl_elem_value *ucontrol)
2581      {
2582              struct mychip *chip = snd_kcontrol_chip(kcontrol);
2583              ucontrol->value.integer.value[0] = get_some_value(chip);
2584              return 0;
2585      }
2586
2587
2588
2589The ``value`` field depends on the type of control as well as on the
2590info callback. For example, the sb driver uses this field to store the
2591register offset, the bit-shift and the bit-mask. The ``private_value``
2592field is set as follows::
2593
2594  .private_value = reg | (shift << 16) | (mask << 24)
2595
2596and is retrieved in callbacks like::
2597
2598  static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
2599                                    struct snd_ctl_elem_value *ucontrol)
2600  {
2601          int reg = kcontrol->private_value & 0xff;
2602          int shift = (kcontrol->private_value >> 16) & 0xff;
2603          int mask = (kcontrol->private_value >> 24) & 0xff;
2604          ....
2605  }
2606
2607In the ``get`` callback, you have to fill all the elements if the
2608control has more than one element, i.e. ``count > 1``. In the example
2609above, we filled only one element (``value.integer.value[0]``) since
2610``count = 1`` is assumed.
2611
2612put callback
2613~~~~~~~~~~~~
2614
2615This callback is used to write a value coming from user-space.
2616
2617For example::
2618
2619      static int snd_myctl_put(struct snd_kcontrol *kcontrol,
2620                               struct snd_ctl_elem_value *ucontrol)
2621      {
2622              struct mychip *chip = snd_kcontrol_chip(kcontrol);
2623              int changed = 0;
2624              if (chip->current_value !=
2625                   ucontrol->value.integer.value[0]) {
2626                      change_current_value(chip,
2627                                  ucontrol->value.integer.value[0]);
2628                      changed = 1;
2629              }
2630              return changed;
2631      }
2632
2633
2634
2635As seen above, you have to return 1 if the value is changed. If the
2636value is not changed, return 0 instead. If any fatal error happens,
2637return a negative error code as usual.
2638
2639As in the ``get`` callback, when the control has more than one
2640element, all elements must be evaluated in this callback, too.
2641
2642Callbacks are not atomic
2643~~~~~~~~~~~~~~~~~~~~~~~~
2644
2645All these three callbacks are not-atomic.
2646
2647Control Constructor
2648-------------------
2649
2650When everything is ready, finally we can create a new control. To create
2651a control, there are two functions to be called,
2652:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
2653
2654In the simplest way, you can do it like this::
2655
2656  err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
2657  if (err < 0)
2658          return err;
2659
2660where ``my_control`` is the struct snd_kcontrol_new object defined above,
2661and chip is the object pointer to be passed to kcontrol->private_data which
2662can be referred to in callbacks.
2663
2664:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
2665:c:func:`snd_ctl_add()` assigns the given control component to the
2666card.
2667
2668Change Notification
2669-------------------
2670
2671If you need to change and update a control in the interrupt routine, you
2672can call :c:func:`snd_ctl_notify()`. For example::
2673
2674  snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
2675
2676This function takes the card pointer, the event-mask, and the control id
2677pointer for the notification. The event-mask specifies the types of
2678notification, for example, in the above example, the change of control
2679values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
2680to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
2681for hardware volume interrupts.
2682
2683Metadata
2684--------
2685
2686To provide information about the dB values of a mixer control, use one of
2687the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
2688variable containing this information, set the ``tlv.p`` field to point to
2689this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
2690in the ``access`` field; like this::
2691
2692  static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
2693
2694  static struct snd_kcontrol_new my_control = {
2695          ...
2696          .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
2697                    SNDRV_CTL_ELEM_ACCESS_TLV_READ,
2698          ...
2699          .tlv.p = db_scale_my_control,
2700  };
2701
2702
2703The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
2704about a mixer control where each step in the control's value changes the
2705dB value by a constant dB amount. The first parameter is the name of the
2706variable to be defined. The second parameter is the minimum value, in
2707units of 0.01 dB. The third parameter is the step size, in units of 0.01
2708dB. Set the fourth parameter to 1 if the minimum value actually mutes
2709the control.
2710
2711The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
2712about a mixer control where the control's value affects the output
2713linearly. The first parameter is the name of the variable to be defined.
2714The second parameter is the minimum value, in units of 0.01 dB. The
2715third parameter is the maximum value, in units of 0.01 dB. If the
2716minimum value mutes the control, set the second parameter to
2717``TLV_DB_GAIN_MUTE``.
2718
2719API for AC97 Codec
2720==================
2721
2722General
2723-------
2724
2725The ALSA AC97 codec layer is a well-defined one, and you don't have to
2726write much code to control it. Only low-level control routines are
2727necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
2728
2729Full Code Example
2730-----------------
2731
2732::
2733
2734      struct mychip {
2735              ....
2736              struct snd_ac97 *ac97;
2737              ....
2738      };
2739
2740      static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2741                                                 unsigned short reg)
2742      {
2743              struct mychip *chip = ac97->private_data;
2744              ....
2745              /* read a register value here from the codec */
2746              return the_register_value;
2747      }
2748
2749      static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2750                                       unsigned short reg, unsigned short val)
2751      {
2752              struct mychip *chip = ac97->private_data;
2753              ....
2754              /* write the given register value to the codec */
2755      }
2756
2757      static int snd_mychip_ac97(struct mychip *chip)
2758      {
2759              struct snd_ac97_bus *bus;
2760              struct snd_ac97_template ac97;
2761              int err;
2762              static struct snd_ac97_bus_ops ops = {
2763                      .write = snd_mychip_ac97_write,
2764                      .read = snd_mychip_ac97_read,
2765              };
2766
2767              err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
2768              if (err < 0)
2769                      return err;
2770              memset(&ac97, 0, sizeof(ac97));
2771              ac97.private_data = chip;
2772              return snd_ac97_mixer(bus, &ac97, &chip->ac97);
2773      }
2774
2775
2776AC97 Constructor
2777----------------
2778
2779To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
2780with an ``ac97_bus_ops_t`` record with callback functions::
2781
2782  struct snd_ac97_bus *bus;
2783  static struct snd_ac97_bus_ops ops = {
2784        .write = snd_mychip_ac97_write,
2785        .read = snd_mychip_ac97_read,
2786  };
2787
2788  snd_ac97_bus(card, 0, &ops, NULL, &pbus);
2789
2790The bus record is shared among all belonging ac97 instances.
2791
2792And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template
2793record together with the bus pointer created above::
2794
2795  struct snd_ac97_template ac97;
2796  int err;
2797
2798  memset(&ac97, 0, sizeof(ac97));
2799  ac97.private_data = chip;
2800  snd_ac97_mixer(bus, &ac97, &chip->ac97);
2801
2802where chip->ac97 is a pointer to a newly created ``ac97_t``
2803instance. In this case, the chip pointer is set as the private data,
2804so that the read/write callback functions can refer to this chip
2805instance. This instance is not necessarily stored in the chip
2806record. If you need to change the register values from the driver, or
2807need the suspend/resume of ac97 codecs, keep this pointer to pass to
2808the corresponding functions.
2809
2810AC97 Callbacks
2811--------------
2812
2813The standard callbacks are ``read`` and ``write``. Obviously they
2814correspond to the functions for read and write accesses to the
2815hardware low-level codes.
2816
2817The ``read`` callback returns the register value specified in the
2818argument::
2819
2820  static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
2821                                             unsigned short reg)
2822  {
2823          struct mychip *chip = ac97->private_data;
2824          ....
2825          return the_register_value;
2826  }
2827
2828Here, the chip can be cast from ``ac97->private_data``.
2829
2830Meanwhile, the ``write`` callback is used to set the register
2831value::
2832
2833  static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
2834                       unsigned short reg, unsigned short val)
2835
2836
2837These callbacks are non-atomic like the control API callbacks.
2838
2839There are also other callbacks: ``reset``, ``wait`` and ``init``.
2840
2841The ``reset`` callback is used to reset the codec. If the chip
2842requires a special kind of reset, you can define this callback.
2843
2844The ``wait`` callback is used to add some waiting time in the standard
2845initialization of the codec. If the chip requires the extra waiting
2846time, define this callback.
2847
2848The ``init`` callback is used for additional initialization of the
2849codec.
2850
2851Updating Registers in The Driver
2852--------------------------------
2853
2854If you need to access to the codec from the driver, you can call the
2855following functions: :c:func:`snd_ac97_write()`,
2856:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
2857:c:func:`snd_ac97_update_bits()`.
2858
2859Both :c:func:`snd_ac97_write()` and
2860:c:func:`snd_ac97_update()` functions are used to set a value to
2861the given register (``AC97_XXX``). The difference between them is that
2862:c:func:`snd_ac97_update()` doesn't write a value if the given
2863value has been already set, while :c:func:`snd_ac97_write()`
2864always rewrites the value::
2865
2866  snd_ac97_write(ac97, AC97_MASTER, 0x8080);
2867  snd_ac97_update(ac97, AC97_MASTER, 0x8080);
2868
2869:c:func:`snd_ac97_read()` is used to read the value of the given
2870register. For example::
2871
2872  value = snd_ac97_read(ac97, AC97_MASTER);
2873
2874:c:func:`snd_ac97_update_bits()` is used to update some bits in
2875the given register::
2876
2877  snd_ac97_update_bits(ac97, reg, mask, value);
2878
2879Also, there is a function to change the sample rate (of a given register
2880such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
2881codec: :c:func:`snd_ac97_set_rate()`::
2882
2883  snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
2884
2885
2886The following registers are available to set the rate:
2887``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
2888``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
2889specified, the register is not really changed but the corresponding
2890IEC958 status bits will be updated.
2891
2892Clock Adjustment
2893----------------
2894
2895In some chips, the clock of the codec isn't 48000 but using a PCI clock
2896(to save a quartz!). In this case, change the field ``bus->clock`` to
2897the corresponding value. For example, intel8x0 and es1968 drivers have
2898their own function to read from the clock.
2899
2900Proc Files
2901----------
2902
2903The ALSA AC97 interface will create a proc file such as
2904``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
2905can refer to these files to see the current status and registers of
2906the codec.
2907
2908Multiple Codecs
2909---------------
2910
2911When there are several codecs on the same card, you need to call
2912:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
2913greater. The ``num`` field specifies the codec number.
2914
2915If you set up multiple codecs, you either need to write different
2916callbacks for each codec or check ``ac97->num`` in the callback
2917routines.
2918
2919MIDI (MPU401-UART) Interface
2920============================
2921
2922General
2923-------
2924
2925Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
2926soundcard supports the standard MPU401-UART interface, most likely you
2927can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
2928``<sound/mpu401.h>``.
2929
2930Some soundchips have a similar but slightly different implementation of
2931mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
2932
2933MIDI Constructor
2934----------------
2935
2936To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`::
2937
2938  struct snd_rawmidi *rmidi;
2939  snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
2940                      irq, &rmidi);
2941
2942
2943The first argument is the card pointer, and the second is the index of
2944this component. You can create up to 8 rawmidi devices.
2945
2946The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
2947it's not a special one, you can use ``MPU401_HW_MPU401``.
2948
2949The 4th argument is the I/O port address. Many backward-compatible
2950MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
2951PCI I/O region. It depends on the chip design.
2952
2953The 5th argument is a bitflag for additional information. When the I/O
2954port address above is part of the PCI I/O region, the MPU401 I/O port
2955might have been already allocated (reserved) by the driver itself. In
2956such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
2957mpu401-uart layer will allocate the I/O ports by itself.
2958
2959When the controller supports only the input or output MIDI stream, pass
2960the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
2961respectively. Then the rawmidi instance is created as a single stream.
2962
2963``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
2964(via readb and writeb) instead of iob and outb. In this case, you have
2965to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
2966
2967When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
2968the default interrupt handler. The driver needs to call
2969:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
2970processing the output stream in the irq handler.
2971
2972If the MPU-401 interface shares its interrupt with the other logical
2973devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
2974`below <MIDI Interrupt Handler_>`__).
2975
2976Usually, the port address corresponds to the command port and port + 1
2977corresponds to the data port. If not, you may change the ``cport``
2978field of struct snd_mpu401 manually afterward.
2979However, struct snd_mpu401 pointer is
2980not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
2981need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly::
2982
2983  struct snd_mpu401 *mpu;
2984  mpu = rmidi->private_data;
2985
2986and reset the ``cport`` as you like::
2987
2988  mpu->cport = my_own_control_port;
2989
2990The 6th argument specifies the ISA irq number that will be allocated. If
2991no interrupt is to be allocated (because your code is already allocating
2992a shared interrupt, or because the device does not use interrupts), pass
2993-1 instead. For a MPU-401 device without an interrupt, a polling timer
2994will be used instead.
2995
2996MIDI Interrupt Handler
2997----------------------
2998
2999When the interrupt is allocated in
3000:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
3001handler is automatically used, hence you don't have anything else to do
3002than creating the mpu401 stuff. Otherwise, you have to set
3003``MPU401_INFO_IRQ_HOOK``, and call
3004:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
3005interrupt handler when it has determined that a UART interrupt has
3006occurred.
3007
3008In this case, you need to pass the private_data of the returned rawmidi
3009object from :c:func:`snd_mpu401_uart_new()` as the second
3010argument of :c:func:`snd_mpu401_uart_interrupt()`::
3011
3012  snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
3013
3014
3015RawMIDI Interface
3016=================
3017
3018Overview
3019--------
3020
3021The raw MIDI interface is used for hardware MIDI ports that can be
3022accessed as a byte stream. It is not used for synthesizer chips that do
3023not directly understand MIDI.
3024
3025ALSA handles file and buffer management. All you have to do is to write
3026some code to move data between the buffer and the hardware.
3027
3028The rawmidi API is defined in ``<sound/rawmidi.h>``.
3029
3030RawMIDI Constructor
3031-------------------
3032
3033To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
3034function::
3035
3036  struct snd_rawmidi *rmidi;
3037  err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
3038  if (err < 0)
3039          return err;
3040  rmidi->private_data = chip;
3041  strcpy(rmidi->name, "My MIDI");
3042  rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
3043                      SNDRV_RAWMIDI_INFO_INPUT |
3044                      SNDRV_RAWMIDI_INFO_DUPLEX;
3045
3046The first argument is the card pointer, the second argument is the ID
3047string.
3048
3049The third argument is the index of this component. You can create up to
30508 rawmidi devices.
3051
3052The fourth and fifth arguments are the number of output and input
3053substreams, respectively, of this device (a substream is the equivalent
3054of a MIDI port).
3055
3056Set the ``info_flags`` field to specify the capabilities of the
3057device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
3058output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
3059input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
3060output and input at the same time.
3061
3062After the rawmidi device is created, you need to set the operators
3063(callbacks) for each substream. There are helper functions to set the
3064operators for all the substreams of a device::
3065
3066  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
3067  snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
3068
3069The operators are usually defined like this::
3070
3071  static struct snd_rawmidi_ops snd_mymidi_output_ops = {
3072          .open =    snd_mymidi_output_open,
3073          .close =   snd_mymidi_output_close,
3074          .trigger = snd_mymidi_output_trigger,
3075  };
3076
3077These callbacks are explained in the `RawMIDI Callbacks`_ section.
3078
3079If there are more than one substream, you should give a unique name to
3080each of them::
3081
3082  struct snd_rawmidi_substream *substream;
3083  list_for_each_entry(substream,
3084                      &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
3085                      list {
3086          sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
3087  }
3088  /* same for SNDRV_RAWMIDI_STREAM_INPUT */
3089
3090RawMIDI Callbacks
3091-----------------
3092
3093In all the callbacks, the private data that you've set for the rawmidi
3094device can be accessed as ``substream->rmidi->private_data``.
3095
3096If there is more than one port, your callbacks can determine the port
3097index from the struct snd_rawmidi_substream data passed to each
3098callback::
3099
3100  struct snd_rawmidi_substream *substream;
3101  int index = substream->number;
3102
3103RawMIDI open callback
3104~~~~~~~~~~~~~~~~~~~~~
3105
3106::
3107
3108      static int snd_xxx_open(struct snd_rawmidi_substream *substream);
3109
3110
3111This is called when a substream is opened. You can initialize the
3112hardware here, but you shouldn't start transmitting/receiving data yet.
3113
3114RawMIDI close callback
3115~~~~~~~~~~~~~~~~~~~~~~
3116
3117::
3118
3119      static int snd_xxx_close(struct snd_rawmidi_substream *substream);
3120
3121Guess what.
3122
3123The ``open`` and ``close`` callbacks of a rawmidi device are
3124serialized with a mutex, and can sleep.
3125
3126Rawmidi trigger callback for output substreams
3127~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3128
3129::
3130
3131      static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
3132
3133
3134This is called with a nonzero ``up`` parameter when there is some data
3135in the substream buffer that must be transmitted.
3136
3137To read data from the buffer, call
3138:c:func:`snd_rawmidi_transmit_peek()`. It will return the number
3139of bytes that have been read; this will be less than the number of bytes
3140requested when there are no more data in the buffer. After the data have
3141been transmitted successfully, call
3142:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
3143substream buffer::
3144
3145  unsigned char data;
3146  while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
3147          if (snd_mychip_try_to_transmit(data))
3148                  snd_rawmidi_transmit_ack(substream, 1);
3149          else
3150                  break; /* hardware FIFO full */
3151  }
3152
3153If you know beforehand that the hardware will accept data, you can use
3154the :c:func:`snd_rawmidi_transmit()` function which reads some
3155data and removes them from the buffer at once::
3156
3157  while (snd_mychip_transmit_possible()) {
3158          unsigned char data;
3159          if (snd_rawmidi_transmit(substream, &data, 1) != 1)
3160                  break; /* no more data */
3161          snd_mychip_transmit(data);
3162  }
3163
3164If you know beforehand how many bytes you can accept, you can use a
3165buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
3166
3167The ``trigger`` callback must not sleep. If the hardware FIFO is full
3168before the substream buffer has been emptied, you have to continue
3169transmitting data later, either in an interrupt handler, or with a
3170timer if the hardware doesn't have a MIDI transmit interrupt.
3171
3172The ``trigger`` callback is called with a zero ``up`` parameter when
3173the transmission of data should be aborted.
3174
3175RawMIDI trigger callback for input substreams
3176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3177
3178::
3179
3180      static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
3181
3182
3183This is called with a nonzero ``up`` parameter to enable receiving data,
3184or with a zero ``up`` parameter do disable receiving data.
3185
3186The ``trigger`` callback must not sleep; the actual reading of data
3187from the device is usually done in an interrupt handler.
3188
3189When data reception is enabled, your interrupt handler should call
3190:c:func:`snd_rawmidi_receive()` for all received data::
3191
3192  void snd_mychip_midi_interrupt(...)
3193  {
3194          while (mychip_midi_available()) {
3195                  unsigned char data;
3196                  data = mychip_midi_read();
3197                  snd_rawmidi_receive(substream, &data, 1);
3198          }
3199  }
3200
3201
3202drain callback
3203~~~~~~~~~~~~~~
3204
3205::
3206
3207      static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
3208
3209
3210This is only used with output substreams. This function should wait
3211until all data read from the substream buffer have been transmitted.
3212This ensures that the device can be closed and the driver unloaded
3213without losing data.
3214
3215This callback is optional. If you do not set ``drain`` in the struct
3216snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
3217instead.
3218
3219Miscellaneous Devices
3220=====================
3221
3222FM OPL3
3223-------
3224
3225The FM OPL3 is still used in many chips (mainly for backward
3226compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
3227is defined in ``<sound/opl3.h>``.
3228
3229FM registers can be directly accessed through the direct-FM API, defined
3230in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
3231accessed through the Hardware-Dependent Device direct-FM extension API,
3232whereas in OSS compatible mode, FM registers can be accessed with the
3233OSS direct-FM compatible API in ``/dev/dmfmX`` device.
3234
3235To create the OPL3 component, you have two functions to call. The first
3236one is a constructor for the ``opl3_t`` instance::
3237
3238  struct snd_opl3 *opl3;
3239  snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
3240                  integrated, &opl3);
3241
3242The first argument is the card pointer, the second one is the left port
3243address, and the third is the right port address. In most cases, the
3244right port is placed at the left port + 2.
3245
3246The fourth argument is the hardware type.
3247
3248When the left and right ports have been already allocated by the card
3249driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
3250the opl3 module will allocate the specified ports by itself.
3251
3252When the accessing the hardware requires special method instead of the
3253standard I/O access, you can create opl3 instance separately with
3254:c:func:`snd_opl3_new()`::
3255
3256  struct snd_opl3 *opl3;
3257  snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
3258
3259Then set ``command``, ``private_data`` and ``private_free`` for the
3260private access function, the private data and the destructor. The
3261``l_port`` and ``r_port`` are not necessarily set. Only the command
3262must be set properly. You can retrieve the data from the
3263``opl3->private_data`` field.
3264
3265After creating the opl3 instance via :c:func:`snd_opl3_new()`,
3266call :c:func:`snd_opl3_init()` to initialize the chip to the
3267proper state. Note that :c:func:`snd_opl3_create()` always calls
3268it internally.
3269
3270If the opl3 instance is created successfully, then create a hwdep device
3271for this opl3::
3272
3273  struct snd_hwdep *opl3hwdep;
3274  snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
3275
3276The first argument is the ``opl3_t`` instance you created, and the
3277second is the index number, usually 0.
3278
3279The third argument is the index-offset for the sequencer client assigned
3280to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
3281always takes 0).
3282
3283Hardware-Dependent Devices
3284--------------------------
3285
3286Some chips need user-space access for special controls or for loading
3287the micro code. In such a case, you can create a hwdep
3288(hardware-dependent) device. The hwdep API is defined in
3289``<sound/hwdep.h>``. You can find examples in opl3 driver or
3290``isa/sb/sb16_csp.c``.
3291
3292The creation of the ``hwdep`` instance is done via
3293:c:func:`snd_hwdep_new()`::
3294
3295  struct snd_hwdep *hw;
3296  snd_hwdep_new(card, "My HWDEP", 0, &hw);
3297
3298where the third argument is the index number.
3299
3300You can then pass any pointer value to the ``private_data``. If you
3301assign private data, you should define a destructor, too. The
3302destructor function is set in the ``private_free`` field::
3303
3304  struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
3305  hw->private_data = p;
3306  hw->private_free = mydata_free;
3307
3308and the implementation of the destructor would be::
3309
3310  static void mydata_free(struct snd_hwdep *hw)
3311  {
3312          struct mydata *p = hw->private_data;
3313          kfree(p);
3314  }
3315
3316The arbitrary file operations can be defined for this instance. The file
3317operators are defined in the ``ops`` table. For example, assume that
3318this chip needs an ioctl::
3319
3320  hw->ops.open = mydata_open;
3321  hw->ops.ioctl = mydata_ioctl;
3322  hw->ops.release = mydata_release;
3323
3324And implement the callback functions as you like.
3325
3326IEC958 (S/PDIF)
3327---------------
3328
3329Usually the controls for IEC958 devices are implemented via the control
3330interface. There is a macro to compose a name string for IEC958
3331controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
3332``<include/asound.h>``.
3333
3334There are some standard controls for IEC958 status bits. These controls
3335use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
3336fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
3337callback, you don't specify the value field for this type (the count
3338field must be set, though).
3339
3340“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
3341status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
3342returns the bitmask for professional mode. They are read-only controls.
3343
3344Meanwhile, “IEC958 Playback Default” control is defined for getting and
3345setting the current default IEC958 bits.
3346
3347Due to historical reasons, both variants of the Playback Mask and the
3348Playback Default controls can be implemented on either a
3349``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
3350Drivers should expose the mask and default on the same iface though.
3351
3352In addition, you can define the control switches to enable/disable or to
3353set the raw bit mode. The implementation will depend on the chip, but
3354the control should be named as “IEC958 xxx”, preferably using the
3355:c:func:`SNDRV_CTL_NAME_IEC958()` macro.
3356
3357You can find several cases, for example, ``pci/emu10k1``,
3358``pci/ice1712``, or ``pci/cmipci.c``.
3359
3360Buffer and Memory Management
3361============================
3362
3363Buffer Types
3364------------
3365
3366ALSA provides several different buffer allocation functions depending on
3367the bus and the architecture. All these have a consistent API. The
3368allocation of physically-contiguous pages is done via the
3369:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
3370type.
3371
3372The allocation of pages with fallback is done via
3373:c:func:`snd_dma_alloc_pages_fallback()`. This function tries
3374to allocate the specified number of pages, but if not enough pages are
3375available, it tries to reduce the request size until enough space
3376is found, down to one page.
3377
3378To release the pages, call the :c:func:`snd_dma_free_pages()`
3379function.
3380
3381Usually, ALSA drivers try to allocate and reserve a large contiguous
3382physical space at the time the module is loaded for later use. This
3383is called “pre-allocation”. As already written, you can call the
3384following function at PCM instance construction time (in the case of PCI
3385bus)::
3386
3387  snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
3388                                        &pci->dev, size, max);
3389
3390where ``size`` is the byte size to be pre-allocated and ``max`` is
3391the maximum size settable via the ``prealloc`` proc file. The
3392allocator will try to get an area as large as possible within the
3393given size.
3394
3395The second argument (type) and the third argument (device pointer) are
3396dependent on the bus. For normal devices, pass the device pointer
3397(typically identical as ``card->dev``) to the third argument with
3398``SNDRV_DMA_TYPE_DEV`` type.
3399
3400A continuous buffer unrelated to the
3401bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
3402You can pass NULL to the device pointer in that case, which is the
3403default mode implying to allocate with the ``GFP_KERNEL`` flag.
3404If you need a restricted (lower) address, set up the coherent DMA mask
3405bits for the device, and pass the device pointer, like the normal
3406device memory allocations.  For this type, it's still allowed to pass
3407NULL to the device pointer, too, if no address restriction is needed.
3408
3409For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
3410device pointer (see the `Non-Contiguous Buffers`_ section).
3411
3412Once the buffer is pre-allocated, you can use the allocator in the
3413``hw_params`` callback::
3414
3415  snd_pcm_lib_malloc_pages(substream, size);
3416
3417Note that you have to pre-allocate to use this function.
3418
3419But most drivers use the "managed buffer allocation mode" instead
3420of manual allocation and release.
3421This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
3422instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`::
3423
3424  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
3425                                 &pci->dev, size, max);
3426
3427where the passed arguments are identical for both functions.
3428The difference in the managed mode is that PCM core will call
3429:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
3430the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
3431after the PCM ``hw_free`` callback automatically.  So the driver
3432doesn't have to call these functions explicitly in its callback any
3433longer.  This allows many drivers to have NULL ``hw_params`` and
3434``hw_free`` entries.
3435
3436External Hardware Buffers
3437-------------------------
3438
3439Some chips have their own hardware buffers and DMA transfer from the
3440host memory is not available. In such a case, you need to either 1)
3441copy/set the audio data directly to the external hardware buffer, or 2)
3442make an intermediate buffer and copy/set the data from it to the
3443external hardware buffer in interrupts (or in tasklets, preferably).
3444
3445The first case works fine if the external hardware buffer is large
3446enough. This method doesn't need any extra buffers and thus is more
3447efficient. You need to define the ``copy_user`` and ``copy_kernel``
3448callbacks for the data transfer, in addition to the ``fill_silence``
3449callback for playback. However, there is a drawback: it cannot be
3450mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
3451
3452The second case allows for mmap on the buffer, although you have to
3453handle an interrupt or a tasklet to transfer the data from the
3454intermediate buffer to the hardware buffer. You can find an example in
3455the vxpocket driver.
3456
3457Another case is when the chip uses a PCI memory-map region for the
3458buffer instead of the host memory. In this case, mmap is available only
3459on certain architectures like the Intel one. In non-mmap mode, the data
3460cannot be transferred as in the normal way. Thus you need to define the
3461``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
3462as in the cases above. Examples are found in ``rme32.c`` and
3463``rme96.c``.
3464
3465The implementation of the ``copy_user``, ``copy_kernel`` and
3466``silence`` callbacks depends upon whether the hardware supports
3467interleaved or non-interleaved samples. The ``copy_user`` callback is
3468defined like below, a bit differently depending on whether the direction
3469is playback or capture::
3470
3471  static int playback_copy_user(struct snd_pcm_substream *substream,
3472               int channel, unsigned long pos,
3473               void __user *src, unsigned long count);
3474  static int capture_copy_user(struct snd_pcm_substream *substream,
3475               int channel, unsigned long pos,
3476               void __user *dst, unsigned long count);
3477
3478In the case of interleaved samples, the second argument (``channel``) is
3479not used. The third argument (``pos``) specifies the position in bytes.
3480
3481The meaning of the fourth argument is different between playback and
3482capture. For playback, it holds the source data pointer, and for
3483capture, it's the destination data pointer.
3484
3485The last argument is the number of bytes to be copied.
3486
3487What you have to do in this callback is again different between playback
3488and capture directions. In the playback case, you copy the given amount
3489of data (``count``) at the specified pointer (``src``) to the specified
3490offset (``pos``) in the hardware buffer. When coded like memcpy-like
3491way, the copy would look like::
3492
3493  my_memcpy_from_user(my_buffer + pos, src, count);
3494
3495For the capture direction, you copy the given amount of data (``count``)
3496at the specified offset (``pos``) in the hardware buffer to the
3497specified pointer (``dst``)::
3498
3499  my_memcpy_to_user(dst, my_buffer + pos, count);
3500
3501Here the functions are named ``from_user`` and ``to_user`` because
3502it's the user-space buffer that is passed to these callbacks.  That
3503is, the callback is supposed to copy data from/to the user-space
3504directly to/from the hardware buffer.
3505
3506Careful readers might notice that these callbacks receive the
3507arguments in bytes, not in frames like other callbacks.  It's because
3508this makes coding easier like in the examples above, and also it makes
3509it easier to unify both the interleaved and non-interleaved cases, as
3510explained below.
3511
3512In the case of non-interleaved samples, the implementation will be a bit
3513more complicated.  The callback is called for each channel, passed in
3514the second argument, so in total it's called N times per transfer.
3515
3516The meaning of the other arguments are almost the same as in the
3517interleaved case.  The callback is supposed to copy the data from/to
3518the given user-space buffer, but only for the given channel. For
3519details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c``
3520as examples.
3521
3522The above callbacks are the copies from/to the user-space buffer.  There
3523are some cases where we want to copy from/to the kernel-space buffer
3524instead.  In such a case, the ``copy_kernel`` callback is called.  It'd
3525look like::
3526
3527  static int playback_copy_kernel(struct snd_pcm_substream *substream,
3528               int channel, unsigned long pos,
3529               void *src, unsigned long count);
3530  static int capture_copy_kernel(struct snd_pcm_substream *substream,
3531               int channel, unsigned long pos,
3532               void *dst, unsigned long count);
3533
3534As found easily, the only difference is that the buffer pointer is
3535without a ``__user`` prefix; that is, a kernel-buffer pointer is passed
3536in the fourth argument.  Correspondingly, the implementation would be
3537a version without the user-copy, such as::
3538
3539  my_memcpy(my_buffer + pos, src, count);
3540
3541Usually for the playback, another callback ``fill_silence`` is
3542defined.  It's implemented in a similar way as the copy callbacks
3543above::
3544
3545  static int silence(struct snd_pcm_substream *substream, int channel,
3546                     unsigned long pos, unsigned long count);
3547
3548The meanings of arguments are the same as in the ``copy_user`` and
3549``copy_kernel`` callbacks, although there is no buffer pointer
3550argument. In the case of interleaved samples, the channel argument has
3551no meaning, as for the ``copy_*`` callbacks.
3552
3553The role of the ``fill_silence`` callback is to set the given amount
3554(``count``) of silence data at the specified offset (``pos``) in the
3555hardware buffer. Suppose that the data format is signed (that is, the
3556silent-data is 0), and the implementation using a memset-like function
3557would look like::
3558
3559  my_memset(my_buffer + pos, 0, count);
3560
3561In the case of non-interleaved samples, again, the implementation
3562becomes a bit more complicated, as it's called N times per transfer
3563for each channel. See, for example, ``isa/gus/gus_pcm.c``.
3564
3565Non-Contiguous Buffers
3566----------------------
3567
3568If your hardware supports a page table as in emu10k1 or buffer
3569descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA
3570provides an interface for handling SG-buffers. The API is provided in
3571``<sound/pcm.h>``.
3572
3573For creating the SG-buffer handler, call
3574:c:func:`snd_pcm_set_managed_buffer()` or
3575:c:func:`snd_pcm_set_managed_buffer_all()` with
3576``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI
3577pre-allocations. You need to pass ``&pci->dev``, where pci is
3578the struct pci_dev pointer of the chip as well::
3579
3580  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
3581                                 &pci->dev, size, max);
3582
3583The ``struct snd_sg_buf`` instance is created as
3584``substream->dma_private`` in turn. You can cast the pointer like::
3585
3586  struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
3587
3588Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
3589handler will allocate the non-contiguous kernel pages of the given size
3590and map them as virtually contiguous memory. The virtual pointer
3591is addressed via runtime->dma_area. The physical address
3592(``runtime->dma_addr``) is set to zero, because the buffer is
3593physically non-contiguous. The physical address table is set up in
3594``sgbuf->table``. You can get the physical address at a certain offset
3595via :c:func:`snd_pcm_sgbuf_get_addr()`.
3596
3597If you need to release the SG-buffer data explicitly, call the
3598standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
3599
3600Vmalloc'ed Buffers
3601------------------
3602
3603It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
3604example, for an intermediate buffer.
3605You can simply allocate it via the standard
3606:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the
3607buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type::
3608
3609  snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
3610                                 NULL, 0, 0);
3611
3612NULL is passed as the device pointer argument, which indicates
3613that default pages (GFP_KERNEL and GFP_HIGHMEM) will be
3614allocated.
3615
3616Also, note that zero is passed as both the size and the max size
3617argument here.  Since each vmalloc call should succeed at any time,
3618we don't need to pre-allocate the buffers like other continuous
3619pages.
3620
3621Proc Interface
3622==============
3623
3624ALSA provides an easy interface for procfs. The proc files are very
3625useful for debugging. I recommend you set up proc files if you write a
3626driver and want to get a running status or register dumps. The API is
3627found in ``<sound/info.h>``.
3628
3629To create a proc file, call :c:func:`snd_card_proc_new()`::
3630
3631  struct snd_info_entry *entry;
3632  int err = snd_card_proc_new(card, "my-file", &entry);
3633
3634where the second argument specifies the name of the proc file to be
3635created. The above example will create a file ``my-file`` under the
3636card directory, e.g. ``/proc/asound/card0/my-file``.
3637
3638Like other components, the proc entry created via
3639:c:func:`snd_card_proc_new()` will be registered and released
3640automatically in the card registration and release functions.
3641
3642When the creation is successful, the function stores a new instance in
3643the pointer given in the third argument. It is initialized as a text
3644proc file for read only. To use this proc file as a read-only text file
3645as-is, set the read callback with private data via
3646:c:func:`snd_info_set_text_ops()`::
3647
3648  snd_info_set_text_ops(entry, chip, my_proc_read);
3649
3650where the second argument (``chip``) is the private data to be used in
3651the callback. The third parameter specifies the read buffer size and
3652the fourth (``my_proc_read``) is the callback function, which is
3653defined like::
3654
3655  static void my_proc_read(struct snd_info_entry *entry,
3656                           struct snd_info_buffer *buffer);
3657
3658In the read callback, use :c:func:`snd_iprintf()` for output
3659strings, which works just like normal :c:func:`printf()`. For
3660example::
3661
3662  static void my_proc_read(struct snd_info_entry *entry,
3663                           struct snd_info_buffer *buffer)
3664  {
3665          struct my_chip *chip = entry->private_data;
3666
3667          snd_iprintf(buffer, "This is my chip!\n");
3668          snd_iprintf(buffer, "Port = %ld\n", chip->port);
3669  }
3670
3671The file permissions can be changed afterwards. By default, they are
3672read only for all users. If you want to add write permission for the
3673user (root by default), do as follows::
3674
3675 entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
3676
3677and set the write buffer size and the callback::
3678
3679  entry->c.text.write = my_proc_write;
3680
3681In the write callback, you can use :c:func:`snd_info_get_line()`
3682to get a text line, and :c:func:`snd_info_get_str()` to retrieve
3683a string from the line. Some examples are found in
3684``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
3685
3686For a raw-data proc-file, set the attributes as follows::
3687
3688  static const struct snd_info_entry_ops my_file_io_ops = {
3689          .read = my_file_io_read,
3690  };
3691
3692  entry->content = SNDRV_INFO_CONTENT_DATA;
3693  entry->private_data = chip;
3694  entry->c.ops = &my_file_io_ops;
3695  entry->size = 4096;
3696  entry->mode = S_IFREG | S_IRUGO;
3697
3698For raw data, ``size`` field must be set properly. This specifies
3699the maximum size of the proc file access.
3700
3701The read/write callbacks of raw mode are more direct than the text mode.
3702You need to use a low-level I/O functions such as
3703:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the
3704data::
3705
3706  static ssize_t my_file_io_read(struct snd_info_entry *entry,
3707                              void *file_private_data,
3708                              struct file *file,
3709                              char *buf,
3710                              size_t count,
3711                              loff_t pos)
3712  {
3713          if (copy_to_user(buf, local_data + pos, count))
3714                  return -EFAULT;
3715          return count;
3716  }
3717
3718If the size of the info entry has been set up properly, ``count`` and
3719``pos`` are guaranteed to fit within 0 and the given size. You don't
3720have to check the range in the callbacks unless any other condition is
3721required.
3722
3723Power Management
3724================
3725
3726If the chip is supposed to work with suspend/resume functions, you need
3727to add power-management code to the driver. The additional code for
3728power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
3729with __maybe_unused attribute; otherwise the compiler will complain.
3730
3731If the driver *fully* supports suspend/resume that is, the device can be
3732properly resumed to its state when suspend was called, you can set the
3733``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is
3734possible when the registers of the chip can be safely saved and restored
3735to RAM. If this is set, the trigger callback is called with
3736``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
3737
3738Even if the driver doesn't support PM fully but partial suspend/resume
3739is still possible, it's still worthy to implement suspend/resume
3740callbacks. In such a case, applications would reset the status by
3741calling :c:func:`snd_pcm_prepare()` and restart the stream
3742appropriately. Hence, you can define suspend/resume callbacks below but
3743don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
3744
3745Note that the trigger with SUSPEND can always be called when
3746:c:func:`snd_pcm_suspend_all()` is called, regardless of the
3747``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
3748behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
3749``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
3750callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
3751to keep it for compatibility reasons.)
3752
3753The driver needs to define the
3754suspend/resume hooks according to the bus the device is connected to. In
3755the case of PCI drivers, the callbacks look like below::
3756
3757  static int __maybe_unused snd_my_suspend(struct device *dev)
3758  {
3759          .... /* do things for suspend */
3760          return 0;
3761  }
3762  static int __maybe_unused snd_my_resume(struct device *dev)
3763  {
3764          .... /* do things for suspend */
3765          return 0;
3766  }
3767
3768The scheme of the real suspend job is as follows:
3769
37701. Retrieve the card and the chip data.
3771
37722. Call :c:func:`snd_power_change_state()` with
3773   ``SNDRV_CTL_POWER_D3hot`` to change the power status.
3774
37753. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
3776   each codec.
3777
37784. Save the register values if necessary.
3779
37805. Stop the hardware if necessary.
3781
3782Typical code would look like::
3783
3784  static int __maybe_unused mychip_suspend(struct device *dev)
3785  {
3786          /* (1) */
3787          struct snd_card *card = dev_get_drvdata(dev);
3788          struct mychip *chip = card->private_data;
3789          /* (2) */
3790          snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
3791          /* (3) */
3792          snd_ac97_suspend(chip->ac97);
3793          /* (4) */
3794          snd_mychip_save_registers(chip);
3795          /* (5) */
3796          snd_mychip_stop_hardware(chip);
3797          return 0;
3798  }
3799
3800
3801The scheme of the real resume job is as follows:
3802
38031. Retrieve the card and the chip data.
3804
38052. Re-initialize the chip.
3806
38073. Restore the saved registers if necessary.
3808
38094. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`.
3810
38115. Restart the hardware (if any).
3812
38136. Call :c:func:`snd_power_change_state()` with
3814   ``SNDRV_CTL_POWER_D0`` to notify the processes.
3815
3816Typical code would look like::
3817
3818  static int __maybe_unused mychip_resume(struct pci_dev *pci)
3819  {
3820          /* (1) */
3821          struct snd_card *card = dev_get_drvdata(dev);
3822          struct mychip *chip = card->private_data;
3823          /* (2) */
3824          snd_mychip_reinit_chip(chip);
3825          /* (3) */
3826          snd_mychip_restore_registers(chip);
3827          /* (4) */
3828          snd_ac97_resume(chip->ac97);
3829          /* (5) */
3830          snd_mychip_restart_chip(chip);
3831          /* (6) */
3832          snd_power_change_state(card, SNDRV_CTL_POWER_D0);
3833          return 0;
3834  }
3835
3836Note that, at the time this callback gets called, the PCM stream has
3837been already suspended via its own PM ops calling
3838:c:func:`snd_pcm_suspend_all()` internally.
3839
3840OK, we have all callbacks now. Let's set them up. In the initialization
3841of the card, make sure that you can get the chip data from the card
3842instance, typically via ``private_data`` field, in case you created the
3843chip data individually::
3844
3845  static int snd_mychip_probe(struct pci_dev *pci,
3846                              const struct pci_device_id *pci_id)
3847  {
3848          ....
3849          struct snd_card *card;
3850          struct mychip *chip;
3851          int err;
3852          ....
3853          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3854                             0, &card);
3855          ....
3856          chip = kzalloc(sizeof(*chip), GFP_KERNEL);
3857          ....
3858          card->private_data = chip;
3859          ....
3860  }
3861
3862When you created the chip data with :c:func:`snd_card_new()`, it's
3863anyway accessible via ``private_data`` field::
3864
3865  static int snd_mychip_probe(struct pci_dev *pci,
3866                              const struct pci_device_id *pci_id)
3867  {
3868          ....
3869          struct snd_card *card;
3870          struct mychip *chip;
3871          int err;
3872          ....
3873          err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
3874                             sizeof(struct mychip), &card);
3875          ....
3876          chip = card->private_data;
3877          ....
3878  }
3879
3880If you need space to save the registers, allocate the buffer for it
3881here, too, since it would be fatal if you cannot allocate a memory in
3882the suspend phase. The allocated buffer should be released in the
3883corresponding destructor.
3884
3885And next, set suspend/resume callbacks to the pci_driver::
3886
3887  static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
3888
3889  static struct pci_driver driver = {
3890          .name = KBUILD_MODNAME,
3891          .id_table = snd_my_ids,
3892          .probe = snd_my_probe,
3893          .remove = snd_my_remove,
3894          .driver.pm = &snd_my_pm_ops,
3895  };
3896
3897Module Parameters
3898=================
3899
3900There are standard module options for ALSA. At least, each module should
3901have the ``index``, ``id`` and ``enable`` options.
3902
3903If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
3904cards), they should be arrays. The default initial values are defined
3905already as constants for easier programming::
3906
3907  static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
3908  static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
3909  static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
3910
3911If the module supports only a single card, they could be single
3912variables, instead. ``enable`` option is not always necessary in this
3913case, but it would be better to have a dummy option for compatibility.
3914
3915The module parameters must be declared with the standard
3916``module_param()``, ``module_param_array()`` and
3917:c:func:`MODULE_PARM_DESC()` macros.
3918
3919Typical code would look as below::
3920
3921  #define CARD_NAME "My Chip"
3922
3923  module_param_array(index, int, NULL, 0444);
3924  MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
3925  module_param_array(id, charp, NULL, 0444);
3926  MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
3927  module_param_array(enable, bool, NULL, 0444);
3928  MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
3929
3930Also, don't forget to define the module description and the license.
3931Especially, the recent modprobe requires to define the
3932module license as GPL, etc., otherwise the system is shown as “tainted”::
3933
3934  MODULE_DESCRIPTION("Sound driver for My Chip");
3935  MODULE_LICENSE("GPL");
3936
3937
3938Device-Managed Resources
3939========================
3940
3941In the examples above, all resources are allocated and released
3942manually.  But human beings are lazy in nature, especially developers
3943are lazier.  So there are some ways to automate the release part; it's
3944the (device-)managed resources aka devres or devm family.  For
3945example, an object allocated via :c:func:`devm_kmalloc()` will be
3946freed automatically at unbinding the device.
3947
3948ALSA core provides also the device-managed helper, namely,
3949:c:func:`snd_devm_card_new()` for creating a card object.
3950Call this functions instead of the normal :c:func:`snd_card_new()`,
3951and you can forget the explicit :c:func:`snd_card_free()` call, as
3952it's called automagically at error and removal paths.
3953
3954One caveat is that the call of :c:func:`snd_card_free()` would be put
3955at the beginning of the call chain only after you call
3956:c:func:`snd_card_register()`.
3957
3958Also, the ``private_free`` callback is always called at the card free,
3959so be careful to put the hardware clean-up procedure in
3960``private_free`` callback.  It might be called even before you
3961actually set up at an earlier error path.  For avoiding such an
3962invalid initialization, you can set ``private_free`` callback after
3963:c:func:`snd_card_register()` call succeeds.
3964
3965Another thing to be remarked is that you should use device-managed
3966helpers for each component as much as possible once when you manage
3967the card in that way.  Mixing up with the normal and the managed
3968resources may screw up the release order.
3969
3970
3971How To Put Your Driver Into ALSA Tree
3972=====================================
3973
3974General
3975-------
3976
3977So far, you've learned how to write the driver codes. And you might have
3978a question now: how to put my own driver into the ALSA driver tree? Here
3979(finally :) the standard procedure is described briefly.
3980
3981Suppose that you create a new PCI driver for the card “xyz”. The card
3982module name would be snd-xyz. The new driver is usually put into the
3983alsa-driver tree, ``sound/pci`` directory in the case of PCI
3984cards.
3985
3986In the following sections, the driver code is supposed to be put into
3987Linux kernel tree. The two cases are covered: a driver consisting of a
3988single source file and one consisting of several source files.
3989
3990Driver with A Single Source File
3991--------------------------------
3992
39931. Modify sound/pci/Makefile
3994
3995   Suppose you have a file xyz.c. Add the following two lines::
3996
3997     snd-xyz-objs := xyz.o
3998     obj-$(CONFIG_SND_XYZ) += snd-xyz.o
3999
40002. Create the Kconfig entry
4001
4002   Add the new entry of Kconfig for your xyz driver::
4003
4004     config SND_XYZ
4005       tristate "Foobar XYZ"
4006       depends on SND
4007       select SND_PCM
4008       help
4009         Say Y here to include support for Foobar XYZ soundcard.
4010         To compile this driver as a module, choose M here:
4011         the module will be called snd-xyz.
4012
4013The line ``select SND_PCM`` specifies that the driver xyz supports PCM.
4014In addition to SND_PCM, the following components are supported for
4015select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
4016SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
4017Add the select command for each supported component.
4018
4019Note that some selections imply the lowlevel selections. For example,
4020PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
4021includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
4022the lowlevel selections again.
4023
4024For the details of Kconfig script, refer to the kbuild documentation.
4025
4026Drivers with Several Source Files
4027---------------------------------
4028
4029Suppose that the driver snd-xyz have several source files. They are
4030located in the new subdirectory, sound/pci/xyz.
4031
40321. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
4033   as below::
4034
4035     obj-$(CONFIG_SND) += sound/pci/xyz/
4036
4037
40382. Under the directory ``sound/pci/xyz``, create a Makefile::
4039
4040         snd-xyz-objs := xyz.o abc.o def.o
4041         obj-$(CONFIG_SND_XYZ) += snd-xyz.o
4042
40433. Create the Kconfig entry
4044
4045   This procedure is as same as in the last section.
4046
4047
4048Useful Functions
4049================
4050
4051:c:func:`snd_printk()` and friends
4052----------------------------------
4053
4054.. note:: This subsection describes a few helper functions for
4055   decorating a bit more on the standard :c:func:`printk()` & co.
4056   However, in general, the use of such helpers is no longer recommended.
4057   If possible, try to stick with the standard functions like
4058   :c:func:`dev_err()` or :c:func:`pr_err()`.
4059
4060ALSA provides a verbose version of the :c:func:`printk()` function.
4061If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
4062prints the given message together with the file name and the line of the
4063caller. The ``KERN_XXX`` prefix is processed as well as the original
4064:c:func:`printk()` does, so it's recommended to add this prefix,
4065e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
4066
4067There are also :c:func:`printk()`'s for debugging.
4068:c:func:`snd_printd()` can be used for general debugging purposes.
4069If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
4070just like :c:func:`snd_printk()`. If the ALSA is compiled without
4071the debugging flag, it's ignored.
4072
4073:c:func:`snd_printdd()` is compiled in only when
4074``CONFIG_SND_DEBUG_VERBOSE`` is set.
4075
4076:c:func:`snd_BUG()`
4077-------------------
4078
4079It shows the ``BUG?`` message and stack trace as well as
4080:c:func:`snd_BUG_ON()` at the point. It's useful to show that a
4081fatal error happens there.
4082
4083When no debug flag is set, this macro is ignored.
4084
4085:c:func:`snd_BUG_ON()`
4086----------------------
4087
4088:c:func:`snd_BUG_ON()` macro is similar with
4089:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
4090it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
4091return -EINVAL;
4092
4093The macro takes an conditional expression to evaluate. When
4094``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
4095the warning message such as ``BUG? (xxx)`` normally followed by stack
4096trace. In both cases it returns the evaluated value.
4097
4098Acknowledgments
4099===============
4100
4101I would like to thank Phil Kerr for his help for improvement and
4102corrections of this document.
4103
4104Kevin Conder reformatted the original plain-text to the DocBook format.
4105
4106Giuliano Pochini corrected typos and contributed the example codes in
4107the hardware constraints section.
4108