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