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