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