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