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