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