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