Based on kernel version 2.6.29. Page generated on 2009-03-25 22:23 EST.
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> 2 3 <book> 4 <?dbhtml filename="index.html"> 5 6 <!-- ****************************************************** --> 7 <!-- Header --> 8 <!-- ****************************************************** --> 9 <bookinfo> 10 <title>Writing an ALSA Driver</title> 11 <author> 12 <firstname>Takashi</firstname> 13 <surname>Iwai</surname> 14 <affiliation> 15 <address> 16 <email>tiwai[AT]suse[DOT]de</email> 17 </address> 18 </affiliation> 19 </author> 20 21 <date>Oct 15, 2007</date> 22 <edition>0.3.7</edition> 23 24 <abstract> 25 <para> 26 This document describes how to write an ALSA (Advanced Linux 27 Sound Architecture) driver. 28 </para> 29 </abstract> 30 31 <legalnotice> 32 <para> 33 Copyright (c) 2002-2005 Takashi Iwai <email>tiwai[AT]suse[DOT]de</email> 34 </para> 35 36 <para> 37 This document is free; you can redistribute it and/or modify it 38 under the terms of the GNU General Public License as published by 39 the Free Software Foundation; either version 2 of the License, or 40 (at your option) any later version. 41 </para> 42 43 <para> 44 This document is distributed in the hope that it will be useful, 45 but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the 46 implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A 47 PARTICULAR PURPOSE</emphasis>. See the GNU General Public License 48 for more details. 49 </para> 50 51 <para> 52 You should have received a copy of the GNU General Public 53 License along with this program; if not, write to the Free 54 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 55 MA 02111-1307 USA 56 </para> 57 </legalnotice> 58 59 </bookinfo> 60 61 <!-- ****************************************************** --> 62 <!-- Preface --> 63 <!-- ****************************************************** --> 64 <preface id="preface"> 65 <title>Preface</title> 66 <para> 67 This document describes how to write an 68 <ulink url="http://www.alsa-project.org/"><citetitle> 69 ALSA (Advanced Linux Sound Architecture)</citetitle></ulink> 70 driver. The document focuses mainly on PCI soundcards. 71 In the case of other device types, the API might 72 be different, too. However, at least the ALSA kernel API is 73 consistent, and therefore it would be still a bit help for 74 writing them. 75 </para> 76 77 <para> 78 This document targets people who already have enough 79 C language skills and have basic linux kernel programming 80 knowledge. This document doesn't explain the general 81 topic of linux kernel coding and doesn't cover low-level 82 driver implementation details. It only describes 83 the standard way to write a PCI sound driver on ALSA. 84 </para> 85 86 <para> 87 If you are already familiar with the older ALSA ver.0.5.x API, you 88 can check the drivers such as <filename>sound/pci/es1938.c</filename> or 89 <filename>sound/pci/maestro3.c</filename> which have also almost the same 90 code-base in the ALSA 0.5.x tree, so you can compare the differences. 91 </para> 92 93 <para> 94 This document is still a draft version. Any feedback and 95 corrections, please!! 96 </para> 97 </preface> 98 99 100 <!-- ****************************************************** --> 101 <!-- File Tree Structure --> 102 <!-- ****************************************************** --> 103 <chapter id="file-tree"> 104 <title>File Tree Structure</title> 105 106 <section id="file-tree-general"> 107 <title>General</title> 108 <para> 109 The ALSA drivers are provided in two ways. 110 </para> 111 112 <para> 113 One is the trees provided as a tarball or via cvs from the 114 ALSA's ftp site, and another is the 2.6 (or later) Linux kernel 115 tree. To synchronize both, the ALSA driver tree is split into 116 two different trees: alsa-kernel and alsa-driver. The former 117 contains purely the source code for the Linux 2.6 (or later) 118 tree. This tree is designed only for compilation on 2.6 or 119 later environment. The latter, alsa-driver, contains many subtle 120 files for compiling ALSA drivers outside of the Linux kernel tree, 121 wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API, 122 and additional drivers which are still in development or in 123 tests. The drivers in alsa-driver tree will be moved to 124 alsa-kernel (and eventually to the 2.6 kernel tree) when they are 125 finished and confirmed to work fine. 126 </para> 127 128 <para> 129 The file tree structure of ALSA driver is depicted below. Both 130 alsa-kernel and alsa-driver have almost the same file 131 structure, except for <quote>core</quote> directory. It's 132 named as <quote>acore</quote> in alsa-driver tree. 133 134 <example> 135 <title>ALSA File Tree Structure</title> 136 <literallayout> 137 sound 138 /core 139 /oss 140 /seq 141 /oss 142 /instr 143 /ioctl32 144 /include 145 /drivers 146 /mpu401 147 /opl3 148 /i2c 149 /l3 150 /synth 151 /emux 152 /pci 153 /(cards) 154 /isa 155 /(cards) 156 /arm 157 /ppc 158 /sparc 159 /usb 160 /pcmcia /(cards) 161 /oss 162 </literallayout> 163 </example> 164 </para> 165 </section> 166 167 <section id="file-tree-core-directory"> 168 <title>core directory</title> 169 <para> 170 This directory contains the middle layer which is the heart 171 of ALSA drivers. In this directory, the native ALSA modules are 172 stored. The sub-directories contain different modules and are 173 dependent upon the kernel config. 174 </para> 175 176 <section id="file-tree-core-directory-oss"> 177 <title>core/oss</title> 178 179 <para> 180 The codes for PCM and mixer OSS emulation modules are stored 181 in this directory. The rawmidi OSS emulation is included in 182 the ALSA rawmidi code since it's quite small. The sequencer 183 code is stored in <filename>core/seq/oss</filename> directory (see 184 <link linkend="file-tree-core-directory-seq-oss"><citetitle> 185 below</citetitle></link>). 186 </para> 187 </section> 188 189 <section id="file-tree-core-directory-ioctl32"> 190 <title>core/ioctl32</title> 191 192 <para> 193 This directory contains the 32bit-ioctl wrappers for 64bit 194 architectures such like x86-64, ppc64 and sparc64. For 32bit 195 and alpha architectures, these are not compiled. 196 </para> 197 </section> 198 199 <section id="file-tree-core-directory-seq"> 200 <title>core/seq</title> 201 <para> 202 This directory and its sub-directories are for the ALSA 203 sequencer. This directory contains the sequencer core and 204 primary sequencer modules such like snd-seq-midi, 205 snd-seq-virmidi, etc. They are compiled only when 206 <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel 207 config. 208 </para> 209 </section> 210 211 <section id="file-tree-core-directory-seq-oss"> 212 <title>core/seq/oss</title> 213 <para> 214 This contains the OSS sequencer emulation codes. 215 </para> 216 </section> 217 218 <section id="file-tree-core-directory-deq-instr"> 219 <title>core/seq/instr</title> 220 <para> 221 This directory contains the modules for the sequencer 222 instrument layer. 223 </para> 224 </section> 225 </section> 226 227 <section id="file-tree-include-directory"> 228 <title>include directory</title> 229 <para> 230 This is the place for the public header files of ALSA drivers, 231 which are to be exported to user-space, or included by 232 several files at different directories. Basically, the private 233 header files should not be placed in this directory, but you may 234 still find files there, due to historical reasons :) 235 </para> 236 </section> 237 238 <section id="file-tree-drivers-directory"> 239 <title>drivers directory</title> 240 <para> 241 This directory contains code shared among different drivers 242 on different architectures. They are hence supposed not to be 243 architecture-specific. 244 For example, the dummy pcm driver and the serial MIDI 245 driver are found in this directory. In the sub-directories, 246 there is code for components which are independent from 247 bus and cpu architectures. 248 </para> 249 250 <section id="file-tree-drivers-directory-mpu401"> 251 <title>drivers/mpu401</title> 252 <para> 253 The MPU401 and MPU401-UART modules are stored here. 254 </para> 255 </section> 256 257 <section id="file-tree-drivers-directory-opl3"> 258 <title>drivers/opl3 and opl4</title> 259 <para> 260 The OPL3 and OPL4 FM-synth stuff is found here. 261 </para> 262 </section> 263 </section> 264 265 <section id="file-tree-i2c-directory"> 266 <title>i2c directory</title> 267 <para> 268 This contains the ALSA i2c components. 269 </para> 270 271 <para> 272 Although there is a standard i2c layer on Linux, ALSA has its 273 own i2c code for some cards, because the soundcard needs only a 274 simple operation and the standard i2c API is too complicated for 275 such a purpose. 276 </para> 277 278 <section id="file-tree-i2c-directory-l3"> 279 <title>i2c/l3</title> 280 <para> 281 This is a sub-directory for ARM L3 i2c. 282 </para> 283 </section> 284 </section> 285 286 <section id="file-tree-synth-directory"> 287 <title>synth directory</title> 288 <para> 289 This contains the synth middle-level modules. 290 </para> 291 292 <para> 293 So far, there is only Emu8000/Emu10k1 synth driver under 294 the <filename>synth/emux</filename> sub-directory. 295 </para> 296 </section> 297 298 <section id="file-tree-pci-directory"> 299 <title>pci directory</title> 300 <para> 301 This directory and its sub-directories hold the top-level card modules 302 for PCI soundcards and the code specific to the PCI BUS. 303 </para> 304 305 <para> 306 The drivers compiled from a single file are stored directly 307 in the pci directory, while the drivers with several source files are 308 stored on their own sub-directory (e.g. emu10k1, ice1712). 309 </para> 310 </section> 311 312 <section id="file-tree-isa-directory"> 313 <title>isa directory</title> 314 <para> 315 This directory and its sub-directories hold the top-level card modules 316 for ISA soundcards. 317 </para> 318 </section> 319 320 <section id="file-tree-arm-ppc-sparc-directories"> 321 <title>arm, ppc, and sparc directories</title> 322 <para> 323 They are used for top-level card modules which are 324 specific to one of these architectures. 325 </para> 326 </section> 327 328 <section id="file-tree-usb-directory"> 329 <title>usb directory</title> 330 <para> 331 This directory contains the USB-audio driver. In the latest version, the 332 USB MIDI driver is integrated in the usb-audio driver. 333 </para> 334 </section> 335 336 <section id="file-tree-pcmcia-directory"> 337 <title>pcmcia directory</title> 338 <para> 339 The PCMCIA, especially PCCard drivers will go here. CardBus 340 drivers will be in the pci directory, because their API is identical 341 to that of standard PCI cards. 342 </para> 343 </section> 344 345 <section id="file-tree-oss-directory"> 346 <title>oss directory</title> 347 <para> 348 The OSS/Lite source files are stored here in Linux 2.6 (or 349 later) tree. In the ALSA driver tarball, this directory is empty, 350 of course :) 351 </para> 352 </section> 353 </chapter> 354 355 356 <!-- ****************************************************** --> 357 <!-- Basic Flow for PCI Drivers --> 358 <!-- ****************************************************** --> 359 <chapter id="basic-flow"> 360 <title>Basic Flow for PCI Drivers</title> 361 362 <section id="basic-flow-outline"> 363 <title>Outline</title> 364 <para> 365 The minimum flow for PCI soundcards is as follows: 366 367 <itemizedlist> 368 <listitem><para>define the PCI ID table (see the section 369 <link linkend="pci-resource-entries"><citetitle>PCI Entries 370 </citetitle></link>).</para></listitem> 371 <listitem><para>create <function>probe()</function> callback.</para></listitem> 372 <listitem><para>create <function>remove()</function> callback.</para></listitem> 373 <listitem><para>create a <structname>pci_driver</structname> structure 374 containing the three pointers above.</para></listitem> 375 <listitem><para>create an <function>init()</function> function just calling 376 the <function>pci_register_driver()</function> to register the pci_driver table 377 defined above.</para></listitem> 378 <listitem><para>create an <function>exit()</function> function to call 379 the <function>pci_unregister_driver()</function> function.</para></listitem> 380 </itemizedlist> 381 </para> 382 </section> 383 384 <section id="basic-flow-example"> 385 <title>Full Code Example</title> 386 <para> 387 The code example is shown below. Some parts are kept 388 unimplemented at this moment but will be filled in the 389 next sections. The numbers in the comment lines of the 390 <function>snd_mychip_probe()</function> function 391 refer to details explained in the following section. 392 393 <example> 394 <title>Basic Flow for PCI Drivers - Example</title> 395 <programlisting> 396 <![CDATA[ 397 #include <linux/init.h> 398 #include <linux/pci.h> 399 #include <linux/slab.h> 400 #include <sound/core.h> 401 #include <sound/initval.h> 402 403 /* module parameters (see "Module Parameters") */ 404 /* SNDRV_CARDS: maximum number of cards supported by this module */ 405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 407 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 408 409 /* definition of the chip-specific record */ 410 struct mychip { 411 struct snd_card *card; 412 /* the rest of the implementation will be in section 413 * "PCI Resource Management" 414 */ 415 }; 416 417 /* chip-specific destructor 418 * (see "PCI Resource Management") 419 */ 420 static int snd_mychip_free(struct mychip *chip) 421 { 422 .... /* will be implemented later... */ 423 } 424 425 /* component-destructor 426 * (see "Management of Cards and Components") 427 */ 428 static int snd_mychip_dev_free(struct snd_device *device) 429 { 430 return snd_mychip_free(device->device_data); 431 } 432 433 /* chip-specific constructor 434 * (see "Management of Cards and Components") 435 */ 436 static int __devinit snd_mychip_create(struct snd_card *card, 437 struct pci_dev *pci, 438 struct mychip **rchip) 439 { 440 struct mychip *chip; 441 int err; 442 static struct snd_device_ops ops = { 443 .dev_free = snd_mychip_dev_free, 444 }; 445 446 *rchip = NULL; 447 448 /* check PCI availability here 449 * (see "PCI Resource Management") 450 */ 451 .... 452 453 /* allocate a chip-specific data with zero filled */ 454 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 455 if (chip == NULL) 456 return -ENOMEM; 457 458 chip->card = card; 459 460 /* rest of initialization here; will be implemented 461 * later, see "PCI Resource Management" 462 */ 463 .... 464 465 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 466 if (err < 0) { 467 snd_mychip_free(chip); 468 return err; 469 } 470 471 snd_card_set_dev(card, &pci->dev); 472 473 *rchip = chip; 474 return 0; 475 } 476 477 /* constructor -- see "Constructor" sub-section */ 478 static int __devinit snd_mychip_probe(struct pci_dev *pci, 479 const struct pci_device_id *pci_id) 480 { 481 static int dev; 482 struct snd_card *card; 483 struct mychip *chip; 484 int err; 485 486 /* (1) */ 487 if (dev >= SNDRV_CARDS) 488 return -ENODEV; 489 if (!enable[dev]) { 490 dev++; 491 return -ENOENT; 492 } 493 494 /* (2) */ 495 card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0); 496 if (card == NULL) 497 return -ENOMEM; 498 499 /* (3) */ 500 err = snd_mychip_create(card, pci, &chip); 501 if (err < 0) { 502 snd_card_free(card); 503 return err; 504 } 505 506 /* (4) */ 507 strcpy(card->driver, "My Chip"); 508 strcpy(card->shortname, "My Own Chip 123"); 509 sprintf(card->longname, "%s at 0x%lx irq %i", 510 card->shortname, chip->ioport, chip->irq); 511 512 /* (5) */ 513 .... /* implemented later */ 514 515 /* (6) */ 516 err = snd_card_register(card); 517 if (err < 0) { 518 snd_card_free(card); 519 return err; 520 } 521 522 /* (7) */ 523 pci_set_drvdata(pci, card); 524 dev++; 525 return 0; 526 } 527 528 /* destructor -- see the "Destructor" sub-section */ 529 static void __devexit snd_mychip_remove(struct pci_dev *pci) 530 { 531 snd_card_free(pci_get_drvdata(pci)); 532 pci_set_drvdata(pci, NULL); 533 } 534 ]]> 535 </programlisting> 536 </example> 537 </para> 538 </section> 539 540 <section id="basic-flow-constructor"> 541 <title>Constructor</title> 542 <para> 543 The real constructor of PCI drivers is the <function>probe</function> callback. 544 The <function>probe</function> callback and other component-constructors which are called 545 from the <function>probe</function> callback should be defined with 546 the <parameter>__devinit</parameter> prefix. You 547 cannot use the <parameter>__init</parameter> prefix for them, 548 because any PCI device could be a hotplug device. 549 </para> 550 551 <para> 552 In the <function>probe</function> callback, the following scheme is often used. 553 </para> 554 555 <section id="basic-flow-constructor-device-index"> 556 <title>1) Check and increment the device index.</title> 557 <para> 558 <informalexample> 559 <programlisting> 560 <![CDATA[ 561 static int dev; 562 .... 563 if (dev >= SNDRV_CARDS) 564 return -ENODEV; 565 if (!enable[dev]) { 566 dev++; 567 return -ENOENT; 568 } 569 ]]> 570 </programlisting> 571 </informalexample> 572 573 where enable[dev] is the module option. 574 </para> 575 576 <para> 577 Each time the <function>probe</function> callback is called, check the 578 availability of the device. If not available, simply increment 579 the device index and returns. dev will be incremented also 580 later (<link 581 linkend="basic-flow-constructor-set-pci"><citetitle>step 582 7</citetitle></link>). 583 </para> 584 </section> 585 586 <section id="basic-flow-constructor-create-card"> 587 <title>2) Create a card instance</title> 588 <para> 589 <informalexample> 590 <programlisting> 591 <![CDATA[ 592 struct snd_card *card; 593 .... 594 card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0); 595 ]]> 596 </programlisting> 597 </informalexample> 598 </para> 599 600 <para> 601 The details will be explained in the section 602 <link linkend="card-management-card-instance"><citetitle> 603 Management of Cards and Components</citetitle></link>. 604 </para> 605 </section> 606 607 <section id="basic-flow-constructor-create-main"> 608 <title>3) Create a main component</title> 609 <para> 610 In this part, the PCI resources are allocated. 611 612 <informalexample> 613 <programlisting> 614 <![CDATA[ 615 struct mychip *chip; 616 .... 617 err = snd_mychip_create(card, pci, &chip); 618 if (err < 0) { 619 snd_card_free(card); 620 return err; 621 } 622 ]]> 623 </programlisting> 624 </informalexample> 625 626 The details will be explained in the section <link 627 linkend="pci-resource"><citetitle>PCI Resource 628 Management</citetitle></link>. 629 </para> 630 </section> 631 632 <section id="basic-flow-constructor-main-component"> 633 <title>4) Set the driver ID and name strings.</title> 634 <para> 635 <informalexample> 636 <programlisting> 637 <![CDATA[ 638 strcpy(card->driver, "My Chip"); 639 strcpy(card->shortname, "My Own Chip 123"); 640 sprintf(card->longname, "%s at 0x%lx irq %i", 641 card->shortname, chip->ioport, chip->irq); 642 ]]> 643 </programlisting> 644 </informalexample> 645 646 The driver field holds the minimal ID string of the 647 chip. This is used by alsa-lib's configurator, so keep it 648 simple but unique. 649 Even the same driver can have different driver IDs to 650 distinguish the functionality of each chip type. 651 </para> 652 653 <para> 654 The shortname field is a string shown as more verbose 655 name. The longname field contains the information 656 shown in <filename>/proc/asound/cards</filename>. 657 </para> 658 </section> 659 660 <section id="basic-flow-constructor-create-other"> 661 <title>5) Create other components, such as mixer, MIDI, etc.</title> 662 <para> 663 Here you define the basic components such as 664 <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>, 665 mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>), 666 MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>), 667 and other interfaces. 668 Also, if you want a <link linkend="proc-interface"><citetitle>proc 669 file</citetitle></link>, define it here, too. 670 </para> 671 </section> 672 673 <section id="basic-flow-constructor-register-card"> 674 <title>6) Register the card instance.</title> 675 <para> 676 <informalexample> 677 <programlisting> 678 <![CDATA[ 679 err = snd_card_register(card); 680 if (err < 0) { 681 snd_card_free(card); 682 return err; 683 } 684 ]]> 685 </programlisting> 686 </informalexample> 687 </para> 688 689 <para> 690 Will be explained in the section <link 691 linkend="card-management-registration"><citetitle>Management 692 of Cards and Components</citetitle></link>, too. 693 </para> 694 </section> 695 696 <section id="basic-flow-constructor-set-pci"> 697 <title>7) Set the PCI driver data and return zero.</title> 698 <para> 699 <informalexample> 700 <programlisting> 701 <![CDATA[ 702 pci_set_drvdata(pci, card); 703 dev++; 704 return 0; 705 ]]> 706 </programlisting> 707 </informalexample> 708 709 In the above, the card record is stored. This pointer is 710 used in the remove callback and power-management 711 callbacks, too. 712 </para> 713 </section> 714 </section> 715 716 <section id="basic-flow-destructor"> 717 <title>Destructor</title> 718 <para> 719 The destructor, remove callback, simply releases the card 720 instance. Then the ALSA middle layer will release all the 721 attached components automatically. 722 </para> 723 724 <para> 725 It would be typically like the following: 726 727 <informalexample> 728 <programlisting> 729 <![CDATA[ 730 static void __devexit snd_mychip_remove(struct pci_dev *pci) 731 { 732 snd_card_free(pci_get_drvdata(pci)); 733 pci_set_drvdata(pci, NULL); 734 } 735 ]]> 736 </programlisting> 737 </informalexample> 738 739 The above code assumes that the card pointer is set to the PCI 740 driver data. 741 </para> 742 </section> 743 744 <section id="basic-flow-header-files"> 745 <title>Header Files</title> 746 <para> 747 For the above example, at least the following include files 748 are necessary. 749 750 <informalexample> 751 <programlisting> 752 <![CDATA[ 753 #include <linux/init.h> 754 #include <linux/pci.h> 755 #include <linux/slab.h> 756 #include <sound/core.h> 757 #include <sound/initval.h> 758 ]]> 759 </programlisting> 760 </informalexample> 761 762 where the last one is necessary only when module options are 763 defined in the source file. If the code is split into several 764 files, the files without module options don't need them. 765 </para> 766 767 <para> 768 In addition to these headers, you'll need 769 <filename><linux/interrupt.h></filename> for interrupt 770 handling, and <filename><asm/io.h></filename> for I/O 771 access. If you use the <function>mdelay()</function> or 772 <function>udelay()</function> functions, you'll need to include 773 <filename><linux/delay.h></filename> too. 774 </para> 775 776 <para> 777 The ALSA interfaces like the PCM and control APIs are defined in other 778 <filename><sound/xxx.h></filename> header files. 779 They have to be included after 780 <filename><sound/core.h></filename>. 781 </para> 782 783 </section> 784 </chapter> 785 786 787 <!-- ****************************************************** --> 788 <!-- Management of Cards and Components --> 789 <!-- ****************************************************** --> 790 <chapter id="card-management"> 791 <title>Management of Cards and Components</title> 792 793 <section id="card-management-card-instance"> 794 <title>Card Instance</title> 795 <para> 796 For each soundcard, a <quote>card</quote> record must be allocated. 797 </para> 798 799 <para> 800 A card record is the headquarters of the soundcard. It manages 801 the whole list of devices (components) on the soundcard, such as 802 PCM, mixers, MIDI, synthesizer, and so on. Also, the card 803 record holds the ID and the name strings of the card, manages 804 the root of proc files, and controls the power-management states 805 and hotplug disconnections. The component list on the card 806 record is used to manage the correct release of resources at 807 destruction. 808 </para> 809 810 <para> 811 As mentioned above, to create a card instance, call 812 <function>snd_card_new()</function>. 813 814 <informalexample> 815 <programlisting> 816 <![CDATA[ 817 struct snd_card *card; 818 card = snd_card_new(index, id, module, extra_size); 819 ]]> 820 </programlisting> 821 </informalexample> 822 </para> 823 824 <para> 825 The function takes four arguments, the card-index number, the 826 id string, the module pointer (usually 827 <constant>THIS_MODULE</constant>), 828 and the size of extra-data space. The last argument is used to 829 allocate card->private_data for the 830 chip-specific data. Note that these data 831 are allocated by <function>snd_card_new()</function>. 832 </para> 833 </section> 834 835 <section id="card-management-component"> 836 <title>Components</title> 837 <para> 838 After the card is created, you can attach the components 839 (devices) to the card instance. In an ALSA driver, a component is 840 represented as a struct <structname>snd_device</structname> object. 841 A component can be a PCM instance, a control interface, a raw 842 MIDI interface, etc. Each such instance has one component 843 entry. 844 </para> 845 846 <para> 847 A component can be created via 848 <function>snd_device_new()</function> function. 849 850 <informalexample> 851 <programlisting> 852 <![CDATA[ 853 snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); 854 ]]> 855 </programlisting> 856 </informalexample> 857 </para> 858 859 <para> 860 This takes the card pointer, the device-level 861 (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the 862 callback pointers (<parameter>&ops</parameter>). The 863 device-level defines the type of components and the order of 864 registration and de-registration. For most components, the 865 device-level is already defined. For a user-defined component, 866 you can use <constant>SNDRV_DEV_LOWLEVEL</constant>. 867 </para> 868 869 <para> 870 This function itself doesn't allocate the data space. The data 871 must be allocated manually beforehand, and its pointer is passed 872 as the argument. This pointer is used as the 873 (<parameter>chip</parameter> identifier in the above example) 874 for the instance. 875 </para> 876 877 <para> 878 Each pre-defined ALSA component such as ac97 and pcm calls 879 <function>snd_device_new()</function> inside its 880 constructor. The destructor for each component is defined in the 881 callback pointers. Hence, you don't need to take care of 882 calling a destructor for such a component. 883 </para> 884 885 <para> 886 If you wish to create your own component, you need to 887 set the destructor function to the dev_free callback in 888 the <parameter>ops</parameter>, so that it can be released 889 automatically via <function>snd_card_free()</function>. 890 The next example will show an implementation of chip-specific 891 data. 892 </para> 893 </section> 894 895 <section id="card-management-chip-specific"> 896 <title>Chip-Specific Data</title> 897 <para> 898 Chip-specific information, e.g. the I/O port address, its 899 resource pointer, or the irq number, is stored in the 900 chip-specific record. 901 902 <informalexample> 903 <programlisting> 904 <![CDATA[ 905 struct mychip { 906 .... 907 }; 908 ]]> 909 </programlisting> 910 </informalexample> 911 </para> 912 913 <para> 914 In general, there are two ways of allocating the chip record. 915 </para> 916 917 <section id="card-management-chip-specific-snd-card-new"> 918 <title>1. Allocating via <function>snd_card_new()</function>.</title> 919 <para> 920 As mentioned above, you can pass the extra-data-length 921 to the 4th argument of <function>snd_card_new()</function>, i.e. 922 923 <informalexample> 924 <programlisting> 925 <![CDATA[ 926 card = snd_card_new(index[dev], id[dev], THIS_MODULE, sizeof(struct mychip)); 927 ]]> 928 </programlisting> 929 </informalexample> 930 931 struct <structname>mychip</structname> is the type of the chip record. 932 </para> 933 934 <para> 935 In return, the allocated record can be accessed as 936 937 <informalexample> 938 <programlisting> 939 <![CDATA[ 940 struct mychip *chip = card->private_data; 941 ]]> 942 </programlisting> 943 </informalexample> 944 945 With this method, you don't have to allocate twice. 946 The record is released together with the card instance. 947 </para> 948 </section> 949 950 <section id="card-management-chip-specific-allocate-extra"> 951 <title>2. Allocating an extra device.</title> 952 953 <para> 954 After allocating a card instance via 955 <function>snd_card_new()</function> (with 956 <constant>NULL</constant> on the 4th arg), call 957 <function>kzalloc()</function>. 958 959 <informalexample> 960 <programlisting> 961 <![CDATA[ 962 struct snd_card *card; 963 struct mychip *chip; 964 card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL); 965 ..... 966 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 967 ]]> 968 </programlisting> 969 </informalexample> 970 </para> 971 972 <para> 973 The chip record should have the field to hold the card 974 pointer at least, 975 976 <informalexample> 977 <programlisting> 978 <![CDATA[ 979 struct mychip { 980 struct snd_card *card; 981 .... 982 }; 983 ]]> 984 </programlisting> 985 </informalexample> 986 </para> 987 988 <para> 989 Then, set the card pointer in the returned chip instance. 990 991 <informalexample> 992 <programlisting> 993 <![CDATA[ 994 chip->card = card; 995 ]]> 996 </programlisting> 997 </informalexample> 998 </para> 999 1000 <para> 1001 Next, initialize the fields, and register this chip 1002 record as a low-level device with a specified 1003 <parameter>ops</parameter>, 1004 1005 <informalexample> 1006 <programlisting> 1007 <![CDATA[ 1008 static struct snd_device_ops ops = { 1009 .dev_free = snd_mychip_dev_free, 1010 }; 1011 .... 1012 snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 1013 ]]> 1014 </programlisting> 1015 </informalexample> 1016 1017 <function>snd_mychip_dev_free()</function> is the 1018 device-destructor function, which will call the real 1019 destructor. 1020 </para> 1021 1022 <para> 1023 <informalexample> 1024 <programlisting> 1025 <![CDATA[ 1026 static int snd_mychip_dev_free(struct snd_device *device) 1027 { 1028 return snd_mychip_free(device->device_data); 1029 } 1030 ]]> 1031 </programlisting> 1032 </informalexample> 1033 1034 where <function>snd_mychip_free()</function> is the real destructor. 1035 </para> 1036 </section> 1037 </section> 1038 1039 <section id="card-management-registration"> 1040 <title>Registration and Release</title> 1041 <para> 1042 After all components are assigned, register the card instance 1043 by calling <function>snd_card_register()</function>. Access 1044 to the device files is enabled at this point. That is, before 1045 <function>snd_card_register()</function> is called, the 1046 components are safely inaccessible from external side. If this 1047 call fails, exit the probe function after releasing the card via 1048 <function>snd_card_free()</function>. 1049 </para> 1050 1051 <para> 1052 For releasing the card instance, you can call simply 1053 <function>snd_card_free()</function>. As mentioned earlier, all 1054 components are released automatically by this call. 1055 </para> 1056 1057 <para> 1058 As further notes, the destructors (both 1059 <function>snd_mychip_dev_free</function> and 1060 <function>snd_mychip_free</function>) cannot be defined with 1061 the <parameter>__devexit</parameter> prefix, because they may be 1062 called from the constructor, too, at the false path. 1063 </para> 1064 1065 <para> 1066 For a device which allows hotplugging, you can use 1067 <function>snd_card_free_when_closed</function>. This one will 1068 postpone the destruction until all devices are closed. 1069 </para> 1070 1071 </section> 1072 1073 </chapter> 1074 1075 1076 <!-- ****************************************************** --> 1077 <!-- PCI Resource Management --> 1078 <!-- ****************************************************** --> 1079 <chapter id="pci-resource"> 1080 <title>PCI Resource Management</title> 1081 1082 <section id="pci-resource-example"> 1083 <title>Full Code Example</title> 1084 <para> 1085 In this section, we'll complete the chip-specific constructor, 1086 destructor and PCI entries. Example code is shown first, 1087 below. 1088 1089 <example> 1090 <title>PCI Resource Management Example</title> 1091 <programlisting> 1092 <![CDATA[ 1093 struct mychip { 1094 struct snd_card *card; 1095 struct pci_dev *pci; 1096 1097 unsigned long port; 1098 int irq; 1099 }; 1100 1101 static int snd_mychip_free(struct mychip *chip) 1102 { 1103 /* disable hardware here if any */ 1104 .... /* (not implemented in this document) */ 1105 1106 /* release the irq */ 1107 if (chip->irq >= 0) 1108 free_irq(chip->irq, chip); 1109 /* release the I/O ports & memory */ 1110 pci_release_regions(chip->pci); 1111 /* disable the PCI entry */ 1112 pci_disable_device(chip->pci); 1113 /* release the data */ 1114 kfree(chip); 1115 return 0; 1116 } 1117 1118 /* chip-specific constructor */ 1119 static int __devinit snd_mychip_create(struct snd_card *card, 1120 struct pci_dev *pci, 1121 struct mychip **rchip) 1122 { 1123 struct mychip *chip; 1124 int err; 1125 static struct snd_device_ops ops = { 1126 .dev_free = snd_mychip_dev_free, 1127 }; 1128 1129 *rchip = NULL; 1130 1131 /* initialize the PCI entry */ 1132 err = pci_enable_device(pci); 1133 if (err < 0) 1134 return err; 1135 /* check PCI availability (28bit DMA) */ 1136 if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 || 1137 pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) { 1138 printk(KERN_ERR "error to set 28bit mask DMA\n"); 1139 pci_disable_device(pci); 1140 return -ENXIO; 1141 } 1142 1143 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 1144 if (chip == NULL) { 1145 pci_disable_device(pci); 1146 return -ENOMEM; 1147 } 1148 1149 /* initialize the stuff */ 1150 chip->card = card; 1151 chip->pci = pci; 1152 chip->irq = -1; 1153 1154 /* (1) PCI resource allocation */ 1155 err = pci_request_regions(pci, "My Chip"); 1156 if (err < 0) { 1157 kfree(chip); 1158 pci_disable_device(pci); 1159 return err; 1160 } 1161 chip->port = pci_resource_start(pci, 0); 1162 if (request_irq(pci->irq, snd_mychip_interrupt, 1163 IRQF_SHARED, "My Chip", chip)) { 1164 printk(KERN_ERR "cannot grab irq %d\n", pci->irq); 1165 snd_mychip_free(chip); 1166 return -EBUSY; 1167 } 1168 chip->irq = pci->irq; 1169 1170 /* (2) initialization of the chip hardware */ 1171 .... /* (not implemented in this document) */ 1172 1173 err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 1174 if (err < 0) { 1175 snd_mychip_free(chip); 1176 return err; 1177 } 1178 1179 snd_card_set_dev(card, &pci->dev); 1180 1181 *rchip = chip; 1182 return 0; 1183 } 1184 1185 /* PCI IDs */ 1186 static struct pci_device_id snd_mychip_ids[] = { 1187 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, 1188 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, 1189 .... 1190 { 0, } 1191 }; 1192 MODULE_DEVICE_TABLE(pci, snd_mychip_ids); 1193 1194 /* pci_driver definition */ 1195 static struct pci_driver driver = { 1196 .name = "My Own Chip", 1197 .id_table = snd_mychip_ids, 1198 .probe = snd_mychip_probe, 1199 .remove = __devexit_p(snd_mychip_remove), 1200 }; 1201 1202 /* module initialization */ 1203 static int __init alsa_card_mychip_init(void) 1204 { 1205 return pci_register_driver(&driver); 1206 } 1207 1208 /* module clean up */ 1209 static void __exit alsa_card_mychip_exit(void) 1210 { 1211 pci_unregister_driver(&driver); 1212 } 1213 1214 module_init(alsa_card_mychip_init) 1215 module_exit(alsa_card_mychip_exit) 1216 1217 EXPORT_NO_SYMBOLS; /* for old kernels only */ 1218 ]]> 1219 </programlisting> 1220 </example> 1221 </para> 1222 </section> 1223 1224 <section id="pci-resource-some-haftas"> 1225 <title>Some Hafta's</title> 1226 <para> 1227 The allocation of PCI resources is done in the 1228 <function>probe()</function> function, and usually an extra 1229 <function>xxx_create()</function> function is written for this 1230 purpose. 1231 </para> 1232 1233 <para> 1234 In the case of PCI devices, you first have to call 1235 the <function>pci_enable_device()</function> function before 1236 allocating resources. Also, you need to set the proper PCI DMA 1237 mask to limit the accessed I/O range. In some cases, you might 1238 need to call <function>pci_set_master()</function> function, 1239 too. 1240 </para> 1241 1242 <para> 1243 Suppose the 28bit mask, and the code to be added would be like: 1244 1245 <informalexample> 1246 <programlisting> 1247 <![CDATA[ 1248 err = pci_enable_device(pci); 1249 if (err < 0) 1250 return err; 1251 if (pci_set_dma_mask(pci, DMA_28BIT_MASK) < 0 || 1252 pci_set_consistent_dma_mask(pci, DMA_28BIT_MASK) < 0) { 1253 printk(KERN_ERR "error to set 28bit mask DMA\n"); 1254 pci_disable_device(pci); 1255 return -ENXIO; 1256 } 1257 1258 ]]> 1259 </programlisting> 1260 </informalexample> 1261 </para> 1262 </section> 1263 1264 <section id="pci-resource-resource-allocation"> 1265 <title>Resource Allocation</title> 1266 <para> 1267 The allocation of I/O ports and irqs is done via standard kernel 1268 functions. Unlike ALSA ver.0.5.x., there are no helpers for 1269 that. And these resources must be released in the destructor 1270 function (see below). Also, on ALSA 0.9.x, you don't need to 1271 allocate (pseudo-)DMA for PCI like in ALSA 0.5.x. 1272 </para> 1273 1274 <para> 1275 Now assume that the PCI device has an I/O port with 8 bytes 1276 and an interrupt. Then struct <structname>mychip</structname> will have the 1277 following fields: 1278 1279 <informalexample> 1280 <programlisting> 1281 <![CDATA[ 1282 struct mychip { 1283 struct snd_card *card; 1284 1285 unsigned long port; 1286 int irq; 1287 }; 1288 ]]> 1289 </programlisting> 1290 </informalexample> 1291 </para> 1292 1293 <para> 1294 For an I/O port (and also a memory region), you need to have 1295 the resource pointer for the standard resource management. For 1296 an irq, you have to keep only the irq number (integer). But you 1297 need to initialize this number as -1 before actual allocation, 1298 since irq 0 is valid. The port address and its resource pointer 1299 can be initialized as null by 1300 <function>kzalloc()</function> automatically, so you 1301 don't have to take care of resetting them. 1302 </para> 1303 1304 <para> 1305 The allocation of an I/O port is done like this: 1306 1307 <informalexample> 1308 <programlisting> 1309 <![CDATA[ 1310 err = pci_request_regions(pci, "My Chip"); 1311 if (err < 0) { 1312 kfree(chip); 1313 pci_disable_device(pci); 1314 return err; 1315 } 1316 chip->port = pci_resource_start(pci, 0); 1317 ]]> 1318 </programlisting> 1319 </informalexample> 1320 </para> 1321 1322 <para> 1323 <!-- obsolete --> 1324 It will reserve the I/O port region of 8 bytes of the given 1325 PCI device. The returned value, chip->res_port, is allocated 1326 via <function>kmalloc()</function> by 1327 <function>request_region()</function>. The pointer must be 1328 released via <function>kfree()</function>, but there is a 1329 problem with this. This issue will be explained later. 1330 </para> 1331 1332 <para> 1333 The allocation of an interrupt source is done like this: 1334 1335 <informalexample> 1336 <programlisting> 1337 <![CDATA[ 1338 if (request_irq(pci->irq, snd_mychip_interrupt, 1339 IRQF_SHARED, "My Chip", chip)) { 1340 printk(KERN_ERR "cannot grab irq %d\n", pci->irq); 1341 snd_mychip_free(chip); 1342 return -EBUSY; 1343 } 1344 chip->irq = pci->irq; 1345 ]]> 1346 </programlisting> 1347 </informalexample> 1348 1349 where <function>snd_mychip_interrupt()</function> is the 1350 interrupt handler defined <link 1351 linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>. 1352 Note that chip->irq should be defined 1353 only when <function>request_irq()</function> succeeded. 1354 </para> 1355 1356 <para> 1357 On the PCI bus, interrupts can be shared. Thus, 1358 <constant>IRQF_SHARED</constant> is used as the interrupt flag of 1359 <function>request_irq()</function>. 1360 </para> 1361 1362 <para> 1363 The last argument of <function>request_irq()</function> is the 1364 data pointer passed to the interrupt handler. Usually, the 1365 chip-specific record is used for that, but you can use what you 1366 like, too. 1367 </para> 1368 1369 <para> 1370 I won't give details about the interrupt handler at this 1371 point, but at least its appearance can be explained now. The 1372 interrupt handler looks usually like the following: 1373 1374 <informalexample> 1375 <programlisting> 1376 <![CDATA[ 1377 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 1378 { 1379 struct mychip *chip = dev_id; 1380 .... 1381 return IRQ_HANDLED; 1382 } 1383 ]]> 1384 </programlisting> 1385 </informalexample> 1386 </para> 1387 1388 <para> 1389 Now let's write the corresponding destructor for the resources 1390 above. The role of destructor is simple: disable the hardware 1391 (if already activated) and release the resources. So far, we 1392 have no hardware part, so the disabling code is not written here. 1393 </para> 1394 1395 <para> 1396 To release the resources, the <quote>check-and-release</quote> 1397 method is a safer way. For the interrupt, do like this: 1398 1399 <informalexample> 1400 <programlisting> 1401 <![CDATA[ 1402 if (chip->irq >= 0) 1403 free_irq(chip->irq, chip); 1404 ]]> 1405 </programlisting> 1406 </informalexample> 1407 1408 Since the irq number can start from 0, you should initialize 1409 chip->irq with a negative value (e.g. -1), so that you can 1410 check the validity of the irq number as above. 1411 </para> 1412 1413 <para> 1414 When you requested I/O ports or memory regions via 1415 <function>pci_request_region()</function> or 1416 <function>pci_request_regions()</function> like in this example, 1417 release the resource(s) using the corresponding function, 1418 <function>pci_release_region()</function> or 1419 <function>pci_release_regions()</function>. 1420 1421 <informalexample> 1422 <programlisting> 1423 <![CDATA[ 1424 pci_release_regions(chip->pci); 1425 ]]> 1426 </programlisting> 1427 </informalexample> 1428 </para> 1429 1430 <para> 1431 When you requested manually via <function>request_region()</function> 1432 or <function>request_mem_region</function>, you can release it via 1433 <function>release_resource()</function>. Suppose that you keep 1434 the resource pointer returned from <function>request_region()</function> 1435 in chip->res_port, the release procedure looks like: 1436 1437 <informalexample> 1438 <programlisting> 1439 <![CDATA[ 1440 release_and_free_resource(chip->res_port); 1441 ]]> 1442 </programlisting> 1443 </informalexample> 1444 </para> 1445 1446 <para> 1447 Don't forget to call <function>pci_disable_device()</function> 1448 before the end. 1449 </para> 1450 1451 <para> 1452 And finally, release the chip-specific record. 1453 1454 <informalexample> 1455 <programlisting> 1456 <![CDATA[ 1457 kfree(chip); 1458 ]]> 1459 </programlisting> 1460 </informalexample> 1461 </para> 1462 1463 <para> 1464 Again, remember that you cannot 1465 use the <parameter>__devexit</parameter> prefix for this destructor. 1466 </para> 1467 1468 <para> 1469 We didn't implement the hardware disabling part in the above. 1470 If you need to do this, please note that the destructor may be 1471 called even before the initialization of the chip is completed. 1472 It would be better to have a flag to skip hardware disabling 1473 if the hardware was not initialized yet. 1474 </para> 1475 1476 <para> 1477 When the chip-data is assigned to the card using 1478 <function>snd_device_new()</function> with 1479 <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is 1480 called at the last. That is, it is assured that all other 1481 components like PCMs and controls have already been released. 1482 You don't have to stop PCMs, etc. explicitly, but just 1483 call low-level hardware stopping. 1484 </para> 1485 1486 <para> 1487 The management of a memory-mapped region is almost as same as 1488 the management of an I/O port. You'll need three fields like 1489 the following: 1490 1491 <informalexample> 1492 <programlisting> 1493 <![CDATA[ 1494 struct mychip { 1495 .... 1496 unsigned long iobase_phys; 1497 void __iomem *iobase_virt; 1498 }; 1499 ]]> 1500 </programlisting> 1501 </informalexample> 1502 1503 and the allocation would be like below: 1504 1505 <informalexample> 1506 <programlisting> 1507 <![CDATA[ 1508 if ((err = pci_request_regions(pci, "My Chip")) < 0) { 1509 kfree(chip); 1510 return err; 1511 } 1512 chip->iobase_phys = pci_resource_start(pci, 0); 1513 chip->iobase_virt = ioremap_nocache(chip->iobase_phys, 1514 pci_resource_len(pci, 0)); 1515 ]]> 1516 </programlisting> 1517 </informalexample> 1518 1519 and the corresponding destructor would be: 1520 1521 <informalexample> 1522 <programlisting> 1523 <![CDATA[ 1524 static int snd_mychip_free(struct mychip *chip) 1525 { 1526 .... 1527 if (chip->iobase_virt) 1528 iounmap(chip->iobase_virt); 1529 .... 1530 pci_release_regions(chip->pci); 1531 .... 1532 } 1533 ]]> 1534 </programlisting> 1535 </informalexample> 1536 </para> 1537 1538 </section> 1539 1540 <section id="pci-resource-device-struct"> 1541 <title>Registration of Device Struct</title> 1542 <para> 1543 At some point, typically after calling <function>snd_device_new()</function>, 1544 you need to register the struct <structname>device</structname> of the chip 1545 you're handling for udev and co. ALSA provides a macro for compatibility with 1546 older kernels. Simply call like the following: 1547 <informalexample> 1548 <programlisting> 1549 <![CDATA[ 1550 snd_card_set_dev(card, &pci->dev); 1551 ]]> 1552 </programlisting> 1553 </informalexample> 1554 so that it stores the PCI's device pointer to the card. This will be 1555 referred by ALSA core functions later when the devices are registered. 1556 </para> 1557 <para> 1558 In the case of non-PCI, pass the proper device struct pointer of the BUS 1559 instead. (In the case of legacy ISA without PnP, you don't have to do 1560 anything.) 1561 </para> 1562 </section> 1563 1564 <section id="pci-resource-entries"> 1565 <title>PCI Entries</title> 1566 <para> 1567 So far, so good. Let's finish the missing PCI 1568 stuff. At first, we need a 1569 <structname>pci_device_id</structname> table for this 1570 chipset. It's a table of PCI vendor/device ID number, and some 1571 masks. 1572 </para> 1573 1574 <para> 1575 For example, 1576 1577 <informalexample> 1578 <programlisting> 1579 <![CDATA[ 1580 static struct pci_device_id snd_mychip_ids[] = { 1581 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, 1582 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, 1583 .... 1584 { 0, } 1585 }; 1586 MODULE_DEVICE_TABLE(pci, snd_mychip_ids); 1587 ]]> 1588 </programlisting> 1589 </informalexample> 1590 </para> 1591 1592 <para> 1593 The first and second fields of 1594 the <structname>pci_device_id</structname> structure are the vendor and 1595 device IDs. If you have no reason to filter the matching 1596 devices, you can leave the remaining fields as above. The last 1597 field of the <structname>pci_device_id</structname> struct contains 1598 private data for this entry. You can specify any value here, for 1599 example, to define specific operations for supported device IDs. 1600 Such an example is found in the intel8x0 driver. 1601 </para> 1602 1603 <para> 1604 The last entry of this list is the terminator. You must 1605 specify this all-zero entry. 1606 </para> 1607 1608 <para> 1609 Then, prepare the <structname>pci_driver</structname> record: 1610 1611 <informalexample> 1612 <programlisting> 1613 <![CDATA[ 1614 static struct pci_driver driver = { 1615 .name = "My Own Chip", 1616 .id_table = snd_mychip_ids, 1617 .probe = snd_mychip_probe, 1618 .remove = __devexit_p(snd_mychip_remove), 1619 }; 1620 ]]> 1621 </programlisting> 1622 </informalexample> 1623 </para> 1624 1625 <para> 1626 The <structfield>probe</structfield> and 1627 <structfield>remove</structfield> functions have already 1628 been defined in the previous sections. 1629 The <structfield>remove</structfield> function should 1630 be defined with the 1631 <function>__devexit_p()</function> macro, so that it's not 1632 defined for built-in (and non-hot-pluggable) case. The 1633 <structfield>name</structfield> 1634 field is the name string of this device. Note that you must not 1635 use a slash <quote>/</quote> in this string. 1636 </para> 1637 1638 <para> 1639 And at last, the module entries: 1640 1641 <informalexample> 1642 <programlisting> 1643 <![CDATA[ 1644 static int __init alsa_card_mychip_init(void) 1645 { 1646 return pci_register_driver(&driver); 1647 } 1648 1649 static void __exit alsa_card_mychip_exit(void) 1650 { 1651 pci_unregister_driver(&driver); 1652 } 1653 1654 module_init(alsa_card_mychip_init) 1655 module_exit(alsa_card_mychip_exit) 1656 ]]> 1657 </programlisting> 1658 </informalexample> 1659 </para> 1660 1661 <para> 1662 Note that these module entries are tagged with 1663 <parameter>__init</parameter> and 1664 <parameter>__exit</parameter> prefixes, not 1665 <parameter>__devinit</parameter> nor 1666 <parameter>__devexit</parameter>. 1667 </para> 1668 1669 <para> 1670 Oh, one thing was forgotten. If you have no exported symbols, 1671 you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). 1672 1673 <informalexample> 1674 <programlisting> 1675 <![CDATA[ 1676 EXPORT_NO_SYMBOLS; 1677 ]]> 1678 </programlisting> 1679 </informalexample> 1680 1681 That's all! 1682 </para> 1683 </section> 1684 </chapter> 1685 1686 1687 <!-- ****************************************************** --> 1688 <!-- PCM Interface --> 1689 <!-- ****************************************************** --> 1690 <chapter id="pcm-interface"> 1691 <title>PCM Interface</title> 1692 1693 <section id="pcm-interface-general"> 1694 <title>General</title> 1695 <para> 1696 The PCM middle layer of ALSA is quite powerful and it is only 1697 necessary for each driver to implement the low-level functions 1698 to access its hardware. 1699 </para> 1700 1701 <para> 1702 For accessing to the PCM layer, you need to include 1703 <filename><sound/pcm.h></filename> first. In addition, 1704 <filename><sound/pcm_params.h></filename> might be needed 1705 if you access to some functions related with hw_param. 1706 </para> 1707 1708 <para> 1709 Each card device can have up to four pcm instances. A pcm 1710 instance corresponds to a pcm device file. The limitation of 1711 number of instances comes only from the available bit size of 1712 the Linux's device numbers. Once when 64bit device number is 1713 used, we'll have more pcm instances available. 1714 </para> 1715 1716 <para> 1717 A pcm instance consists of pcm playback and capture streams, 1718 and each pcm stream consists of one or more pcm substreams. Some 1719 soundcards support multiple playback functions. For example, 1720 emu10k1 has a PCM playback of 32 stereo substreams. In this case, at 1721 each open, a free substream is (usually) automatically chosen 1722 and opened. Meanwhile, when only one substream exists and it was 1723 already opened, the successful open will either block 1724 or error with <constant>EAGAIN</constant> according to the 1725 file open mode. But you don't have to care about such details in your 1726 driver. The PCM middle layer will take care of such work. 1727 </para> 1728 </section> 1729 1730 <section id="pcm-interface-example"> 1731 <title>Full Code Example</title> 1732 <para> 1733 The example code below does not include any hardware access 1734 routines but shows only the skeleton, how to build up the PCM 1735 interfaces. 1736 1737 <example> 1738 <title>PCM Example Code</title> 1739 <programlisting> 1740 <![CDATA[ 1741 #include <sound/pcm.h> 1742 .... 1743 1744 /* hardware definition */ 1745 static struct snd_pcm_hardware snd_mychip_playback_hw = { 1746 .info = (SNDRV_PCM_INFO_MMAP | 1747 SNDRV_PCM_INFO_INTERLEAVED | 1748 SNDRV_PCM_INFO_BLOCK_TRANSFER | 1749 SNDRV_PCM_INFO_MMAP_VALID), 1750 .formats = SNDRV_PCM_FMTBIT_S16_LE, 1751 .rates = SNDRV_PCM_RATE_8000_48000, 1752 .rate_min = 8000, 1753 .rate_max = 48000, 1754 .channels_min = 2, 1755 .channels_max = 2, 1756 .buffer_bytes_max = 32768, 1757 .period_bytes_min = 4096, 1758 .period_bytes_max = 32768, 1759 .periods_min = 1, 1760 .periods_max = 1024, 1761 }; 1762 1763 /* hardware definition */ 1764 static struct snd_pcm_hardware snd_mychip_capture_hw = { 1765 .info = (SNDRV_PCM_INFO_MMAP | 1766 SNDRV_PCM_INFO_INTERLEAVED | 1767 SNDRV_PCM_INFO_BLOCK_TRANSFER | 1768 SNDRV_PCM_INFO_MMAP_VALID), 1769 .formats = SNDRV_PCM_FMTBIT_S16_LE, 1770 .rates = SNDRV_PCM_RATE_8000_48000, 1771 .rate_min = 8000, 1772 .rate_max = 48000, 1773 .channels_min = 2, 1774 .channels_max = 2, 1775 .buffer_bytes_max = 32768, 1776 .period_bytes_min = 4096, 1777 .period_bytes_max = 32768, 1778 .periods_min = 1, 1779 .periods_max = 1024, 1780 }; 1781 1782 /* open callback */ 1783 static int snd_mychip_playback_open(struct snd_pcm_substream *substream) 1784 { 1785 struct mychip *chip = snd_pcm_substream_chip(substream); 1786 struct snd_pcm_runtime *runtime = substream->runtime; 1787 1788 runtime->hw = snd_mychip_playback_hw; 1789 /* more hardware-initialization will be done here */ 1790 .... 1791 return 0; 1792 } 1793 1794 /* close callback */ 1795 static int snd_mychip_playback_close(struct snd_pcm_substream *substream) 1796 { 1797 struct mychip *chip = snd_pcm_substream_chip(substream); 1798 /* the hardware-specific codes will be here */ 1799 .... 1800 return 0; 1801 1802 } 1803 1804 /* open callback */ 1805 static int snd_mychip_capture_open(struct snd_pcm_substream *substream) 1806 { 1807 struct mychip *chip = snd_pcm_substream_chip(substream); 1808 struct snd_pcm_runtime *runtime = substream->runtime; 1809 1810 runtime->hw = snd_mychip_capture_hw; 1811 /* more hardware-initialization will be done here */ 1812 .... 1813 return 0; 1814 } 1815 1816 /* close callback */ 1817 static int snd_mychip_capture_close(struct snd_pcm_substream *substream) 1818 { 1819 struct mychip *chip = snd_pcm_substream_chip(substream); 1820 /* the hardware-specific codes will be here */ 1821 .... 1822 return 0; 1823 1824 } 1825 1826 /* hw_params callback */ 1827 static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, 1828 struct snd_pcm_hw_params *hw_params) 1829 { 1830 return snd_pcm_lib_malloc_pages(substream, 1831 params_buffer_bytes(hw_params)); 1832 } 1833 1834 /* hw_free callback */ 1835 static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) 1836 { 1837 return snd_pcm_lib_free_pages(substream); 1838 } 1839 1840 /* prepare callback */ 1841 static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) 1842 { 1843 struct mychip *chip = snd_pcm_substream_chip(substream); 1844 struct snd_pcm_runtime *runtime = substream->runtime; 1845 1846 /* set up the hardware with the current configuration 1847 * for example... 1848 */ 1849 mychip_set_sample_format(chip, runtime->format); 1850 mychip_set_sample_rate(chip, runtime->rate); 1851 mychip_set_channels(chip, runtime->channels); 1852 mychip_set_dma_setup(chip, runtime->dma_addr, 1853 chip->buffer_size, 1854 chip->period_size); 1855 return 0; 1856 } 1857 1858 /* trigger callback */ 1859 static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, 1860 int cmd) 1861 { 1862 switch (cmd) { 1863 case SNDRV_PCM_TRIGGER_START: 1864 /* do something to start the PCM engine */ 1865 .... 1866 break; 1867 case SNDRV_PCM_TRIGGER_STOP: 1868 /* do something to stop the PCM engine */ 1869 .... 1870 break; 1871 default: 1872 return -EINVAL; 1873 } 1874 } 1875 1876 /* pointer callback */ 1877 static snd_pcm_uframes_t 1878 snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) 1879 { 1880 struct mychip *chip = snd_pcm_substream_chip(substream); 1881 unsigned int current_ptr; 1882 1883 /* get the current hardware pointer */ 1884 current_ptr = mychip_get_hw_pointer(chip); 1885 return current_ptr; 1886 } 1887 1888 /* operators */ 1889 static struct snd_pcm_ops snd_mychip_playback_ops = { 1890 .open = snd_mychip_playback_open, 1891 .close = snd_mychip_playback_close, 1892 .ioctl = snd_pcm_lib_ioctl, 1893 .hw_params = snd_mychip_pcm_hw_params, 1894 .hw_free = snd_mychip_pcm_hw_free, 1895 .prepare = snd_mychip_pcm_prepare, 1896 .trigger = snd_mychip_pcm_trigger, 1897 .pointer = snd_mychip_pcm_pointer, 1898 }; 1899 1900 /* operators */ 1901 static struct snd_pcm_ops snd_mychip_capture_ops = { 1902 .open = snd_mychip_capture_open, 1903 .close = snd_mychip_capture_close, 1904 .ioctl = snd_pcm_lib_ioctl, 1905 .hw_params = snd_mychip_pcm_hw_params, 1906 .hw_free = snd_mychip_pcm_hw_free, 1907 .prepare = snd_mychip_pcm_prepare, 1908 .trigger = snd_mychip_pcm_trigger, 1909 .pointer = snd_mychip_pcm_pointer, 1910 }; 1911 1912 /* 1913 * definitions of capture are omitted here... 1914 */ 1915 1916 /* create a pcm device */ 1917 static int __devinit snd_mychip_new_pcm(struct mychip *chip) 1918 { 1919 struct snd_pcm *pcm; 1920 int err; 1921 1922 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); 1923 if (err < 0) 1924 return err; 1925 pcm->private_data = chip; 1926 strcpy(pcm->name, "My Chip"); 1927 chip->pcm = pcm; 1928 /* set operators */ 1929 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, 1930 &snd_mychip_playback_ops); 1931 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, 1932 &snd_mychip_capture_ops); 1933 /* pre-allocation of buffers */ 1934 /* NOTE: this may fail */ 1935 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, 1936 snd_dma_pci_data(chip->pci), 1937 64*1024, 64*1024); 1938 return 0; 1939 } 1940 ]]> 1941 </programlisting> 1942 </example> 1943 </para> 1944 </section> 1945 1946 <section id="pcm-interface-constructor"> 1947 <title>Constructor</title> 1948 <para> 1949 A pcm instance is allocated by the <function>snd_pcm_new()</function> 1950 function. It would be better to create a constructor for pcm, 1951 namely, 1952 1953 <informalexample> 1954 <programlisting> 1955 <![CDATA[ 1956 static int __devinit snd_mychip_new_pcm(struct mychip *chip) 1957 { 1958 struct snd_pcm *pcm; 1959 int err; 1960 1961 err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); 1962 if (err < 0) 1963 return err; 1964 pcm->private_data = chip; 1965 strcpy(pcm->name, "My Chip"); 1966 chip->pcm = pcm; 1967 .... 1968 return 0; 1969 } 1970 ]]> 1971 </programlisting> 1972 </informalexample> 1973 </para> 1974 1975 <para> 1976 The <function>snd_pcm_new()</function> function takes four 1977 arguments. The first argument is the card pointer to which this 1978 pcm is assigned, and the second is the ID string. 1979 </para> 1980 1981 <para> 1982 The third argument (<parameter>index</parameter>, 0 in the 1983 above) is the index of this new pcm. It begins from zero. If 1984 you create more than one pcm instances, specify the 1985 different numbers in this argument. For example, 1986 <parameter>index</parameter> = 1 for the second PCM device. 1987 </para> 1988 1989 <para> 1990 The fourth and fifth arguments are the number of substreams 1991 for playback and capture, respectively. Here 1 is used for 1992 both arguments. When no playback or capture substreams are available, 1993 pass 0 to the corresponding argument. 1994 </para> 1995 1996 <para> 1997 If a chip supports multiple playbacks or captures, you can 1998 specify more numbers, but they must be handled properly in 1999 open/close, etc. callbacks. When you need to know which 2000 substream you are referring to, then it can be obtained from 2001 struct <structname>snd_pcm_substream</structname> data passed to each callback 2002 as follows: 2003 2004 <informalexample> 2005 <programlisting> 2006 <![CDATA[ 2007 struct snd_pcm_substream *substream; 2008 int index = substream->number; 2009 ]]> 2010 </programlisting> 2011 </informalexample> 2012 </para> 2013 2014 <para> 2015 After the pcm is created, you need to set operators for each 2016 pcm stream. 2017 2018 <informalexample> 2019 <programlisting> 2020 <![CDATA[ 2021 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, 2022 &snd_mychip_playback_ops); 2023 snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, 2024 &snd_mychip_capture_ops); 2025 ]]> 2026 </programlisting> 2027 </informalexample> 2028 </para> 2029 2030 <para> 2031 The operators are defined typically like this: 2032 2033 <informalexample> 2034 <programlisting> 2035 <![CDATA[ 2036 static struct snd_pcm_ops snd_mychip_playback_ops = { 2037 .open = snd_mychip_pcm_open, 2038 .close = snd_mychip_pcm_close, 2039 .ioctl = snd_pcm_lib_ioctl, 2040 .hw_params = snd_mychip_pcm_hw_params, 2041 .hw_free = snd_mychip_pcm_hw_free, 2042 .prepare = snd_mychip_pcm_prepare, 2043 .trigger = snd_mychip_pcm_trigger, 2044 .pointer = snd_mychip_pcm_pointer, 2045 }; 2046 ]]> 2047 </programlisting> 2048 </informalexample> 2049 2050 All the callbacks are described in the 2051 <link linkend="pcm-interface-operators"><citetitle> 2052 Operators</citetitle></link> subsection. 2053 </para> 2054 2055 <para> 2056 After setting the operators, you probably will want to 2057 pre-allocate the buffer. For the pre-allocation, simply call 2058 the following: 2059 2060 <informalexample> 2061 <programlisting> 2062 <![CDATA[ 2063 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, 2064 snd_dma_pci_data(chip->pci), 2065 64*1024, 64*1024); 2066 ]]> 2067 </programlisting> 2068 </informalexample> 2069 2070 It will allocate a buffer up to 64kB as default. 2071 Buffer management details will be described in the later section <link 2072 linkend="buffer-and-memory"><citetitle>Buffer and Memory 2073 Management</citetitle></link>. 2074 </para> 2075 2076 <para> 2077 Additionally, you can set some extra information for this pcm 2078 in pcm->info_flags. 2079 The available values are defined as 2080 <constant>SNDRV_PCM_INFO_XXX</constant> in 2081 <filename><sound/asound.h></filename>, which is used for 2082 the hardware definition (described later). When your soundchip 2083 supports only half-duplex, specify like this: 2084 2085 <informalexample> 2086 <programlisting> 2087 <![CDATA[ 2088 pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; 2089 ]]> 2090 </programlisting> 2091 </informalexample> 2092 </para> 2093 </section> 2094 2095 <section id="pcm-interface-destructor"> 2096 <title>... And the Destructor?</title> 2097 <para> 2098 The destructor for a pcm instance is not always 2099 necessary. Since the pcm device will be released by the middle 2100 layer code automatically, you don't have to call the destructor 2101 explicitly. 2102 </para> 2103 2104 <para> 2105 The destructor would be necessary if you created 2106 special records internally and needed to release them. In such a 2107 case, set the destructor function to 2108 pcm->private_free: 2109 2110 <example> 2111 <title>PCM Instance with a Destructor</title> 2112 <programlisting> 2113 <![CDATA[ 2114 static void mychip_pcm_free(struct snd_pcm *pcm) 2115 { 2116 struct mychip *chip = snd_pcm_chip(pcm); 2117 /* free your own data */ 2118 kfree(chip->my_private_pcm_data); 2119 /* do what you like else */ 2120 .... 2121 } 2122 2123 static int __devinit snd_mychip_new_pcm(struct mychip *chip) 2124 { 2125 struct snd_pcm *pcm; 2126 .... 2127 /* allocate your own data */ 2128 chip->my_private_pcm_data = kmalloc(...); 2129 /* set the destructor */ 2130 pcm->private_data = chip; 2131 pcm->private_free = mychip_pcm_free; 2132 .... 2133 } 2134 ]]> 2135 </programlisting> 2136 </example> 2137 </para> 2138 </section> 2139 2140 <section id="pcm-interface-runtime"> 2141 <title>Runtime Pointer - The Chest of PCM Information</title> 2142 <para> 2143 When the PCM substream is opened, a PCM runtime instance is 2144 allocated and assigned to the substream. This pointer is 2145 accessible via <constant>substream->runtime</constant>. 2146 This runtime pointer holds most information you need 2147 to control the PCM: the copy of hw_params and sw_params configurations, the buffer 2148 pointers, mmap records, spinlocks, etc. 2149 </para> 2150 2151 <para> 2152 The definition of runtime instance is found in 2153 <filename><sound/pcm.h></filename>. Here are 2154 the contents of this file: 2155 <informalexample> 2156 <programlisting> 2157 <![CDATA[ 2158 struct _snd_pcm_runtime { 2159 /* -- Status -- */ 2160 struct snd_pcm_substream *trigger_master; 2161 snd_timestamp_t trigger_tstamp; /* trigger timestamp */ 2162 int overrange; 2163 snd_pcm_uframes_t avail_max; 2164 snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ 2165 snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ 2166 2167 /* -- HW params -- */ 2168 snd_pcm_access_t access; /* access mode */ 2169 snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ 2170 snd_pcm_subformat_t subformat; /* subformat */ 2171 unsigned int rate; /* rate in Hz */ 2172 unsigned int channels; /* channels */ 2173 snd_pcm_uframes_t period_size; /* period size */ 2174 unsigned int periods; /* periods */ 2175 snd_pcm_uframes_t buffer_size; /* buffer size */ 2176 unsigned int tick_time; /* tick time */ 2177 snd_pcm_uframes_t min_align; /* Min alignment for the format */ 2178 size_t byte_align; 2179 unsigned int frame_bits; 2180 unsigned int sample_bits; 2181 unsigned int info; 2182 unsigned int rate_num; 2183 unsigned int rate_den; 2184 2185 /* -- SW params -- */ 2186 struct timespec tstamp_mode; /* mmap timestamp is updated */ 2187 unsigned int period_step; 2188 unsigned int sleep_min; /* min ticks to sleep */ 2189 snd_pcm_uframes_t start_threshold; 2190 snd_pcm_uframes_t stop_threshold; 2191 snd_pcm_uframes_t silence_threshold; /* Silence filling happens when 2192 noise is nearest than this */ 2193 snd_pcm_uframes_t silence_size; /* Silence filling size */ 2194 snd_pcm_uframes_t boundary; /* pointers wrap point */ 2195 2196 snd_pcm_uframes_t silenced_start; 2197 snd_pcm_uframes_t silenced_size; 2198 2199 snd_pcm_sync_id_t sync; /* hardware synchronization ID */ 2200 2201 /* -- mmap -- */ 2202 volatile struct snd_pcm_mmap_status *status; 2203 volatile struct snd_pcm_mmap_control *control; 2204 atomic_t mmap_count; 2205 2206 /* -- locking / scheduling -- */ 2207 spinlock_t lock; 2208 wait_queue_head_t sleep; 2209 struct timer_list tick_timer; 2210 struct fasync_struct *fasync; 2211 2212 /* -- private section -- */ 2213 void *private_data; 2214 void (*private_free)(struct snd_pcm_runtime *runtime); 2215 2216 /* -- hardware description -- */ 2217 struct snd_pcm_hardware hw; 2218 struct snd_pcm_hw_constraints hw_constraints; 2219 2220 /* -- interrupt callbacks -- */ 2221 void (*transfer_ack_begin)(struct snd_pcm_substream *substream); 2222 void (*transfer_ack_end)(struct snd_pcm_substream *substream); 2223 2224 /* -- timer -- */ 2225 unsigned int timer_resolution; /* timer resolution */ 2226 2227 /* -- DMA -- */ 2228 unsigned char *dma_area; /* DMA area */ 2229 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ 2230 size_t dma_bytes; /* size of DMA area */ 2231 2232 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ 2233 2234 #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) 2235 /* -- OSS things -- */ 2236 struct snd_pcm_oss_runtime oss; 2237 #endif 2238 }; 2239 ]]> 2240 </programlisting> 2241 </informalexample> 2242 </para> 2243 2244 <para> 2245 For the operators (callbacks) of each sound driver, most of 2246 these records are supposed to be read-only. Only the PCM 2247 middle-layer changes / updates them. The exceptions are 2248 the hardware description (hw), interrupt callbacks 2249 (transfer_ack_xxx), DMA buffer information, and the private 2250 data. Besides, if you use the standard buffer allocation 2251 method via <function>snd_pcm_lib_malloc_pages()</function>, 2252 you don't need to set the DMA buffer information by yourself. 2253 </para> 2254 2255 <para> 2256 In the sections below, important records are explained. 2257 </para> 2258 2259 <section id="pcm-interface-runtime-hw"> 2260 <title>Hardware Description</title> 2261 <para> 2262 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>) 2263 contains the definitions of the fundamental hardware 2264 configuration. Above all, you'll need to define this in 2265 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2266 the open callback</citetitle></link>. 2267 Note that the runtime instance holds the copy of the 2268 descriptor, not the pointer to the existing descriptor. That 2269 is, in the open callback, you can modify the copied descriptor 2270 (<constant>runtime->hw</constant>) as you need. For example, if the maximum 2271 number of channels is 1 only on some chip models, you can 2272 still use the same hardware descriptor and change the 2273 channels_max later: 2274 <informalexample> 2275 <programlisting> 2276 <![CDATA[ 2277 struct snd_pcm_runtime *runtime = substream->runtime; 2278 ... 2279 runtime->hw = snd_mychip_playback_hw; /* common definition */ 2280 if (chip->model == VERY_OLD_ONE) 2281 runtime->hw.channels_max = 1; 2282 ]]> 2283 </programlisting> 2284 </informalexample> 2285 </para> 2286 2287 <para> 2288 Typically, you'll have a hardware descriptor as below: 2289 <informalexample> 2290 <programlisting> 2291 <![CDATA[ 2292 static struct snd_pcm_hardware snd_mychip_playback_hw = { 2293 .info = (SNDRV_PCM_INFO_MMAP | 2294 SNDRV_PCM_INFO_INTERLEAVED | 2295 SNDRV_PCM_INFO_BLOCK_TRANSFER | 2296 SNDRV_PCM_INFO_MMAP_VALID), 2297 .formats = SNDRV_PCM_FMTBIT_S16_LE, 2298 .rates = SNDRV_PCM_RATE_8000_48000, 2299 .rate_min = 8000, 2300 .rate_max = 48000, 2301 .channels_min = 2, 2302 .channels_max = 2, 2303 .buffer_bytes_max = 32768, 2304 .period_bytes_min = 4096, 2305 .period_bytes_max = 32768, 2306 .periods_min = 1, 2307 .periods_max = 1024, 2308 }; 2309 ]]> 2310 </programlisting> 2311 </informalexample> 2312 </para> 2313 2314 <para> 2315 <itemizedlist> 2316 <listitem><para> 2317 The <structfield>info</structfield> field contains the type and 2318 capabilities of this pcm. The bit flags are defined in 2319 <filename><sound/asound.h></filename> as 2320 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you 2321 have to specify whether the mmap is supported and which 2322 interleaved format is supported. 2323 When the is supported, add the 2324 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the 2325 hardware supports the interleaved or the non-interleaved 2326 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or 2327 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must 2328 be set, respectively. If both are supported, you can set both, 2329 too. 2330 </para> 2331 2332 <para> 2333 In the above example, <constant>MMAP_VALID</constant> and 2334 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap 2335 mode. Usually both are set. Of course, 2336 <constant>MMAP_VALID</constant> is set only if the mmap is 2337 really supported. 2338 </para> 2339 2340 <para> 2341 The other possible flags are 2342 <constant>SNDRV_PCM_INFO_PAUSE</constant> and 2343 <constant>SNDRV_PCM_INFO_RESUME</constant>. The 2344 <constant>PAUSE</constant> bit means that the pcm supports the 2345 <quote>pause</quote> operation, while the 2346 <constant>RESUME</constant> bit means that the pcm supports 2347 the full <quote>suspend/resume</quote> operation. 2348 If the <constant>PAUSE</constant> flag is set, 2349 the <structfield>trigger</structfield> callback below 2350 must handle the corresponding (pause push/release) commands. 2351 The suspend/resume trigger commands can be defined even without 2352 the <constant>RESUME</constant> flag. See <link 2353 linkend="power-management"><citetitle> 2354 Power Management</citetitle></link> section for details. 2355 </para> 2356 2357 <para> 2358 When the PCM substreams can be synchronized (typically, 2359 synchronized start/stop of a playback and a capture streams), 2360 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, 2361 too. In this case, you'll need to check the linked-list of 2362 PCM substreams in the trigger callback. This will be 2363 described in the later section. 2364 </para> 2365 </listitem> 2366 2367 <listitem> 2368 <para> 2369 <structfield>formats</structfield> field contains the bit-flags 2370 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>). 2371 If the hardware supports more than one format, give all or'ed 2372 bits. In the example above, the signed 16bit little-endian 2373 format is specified. 2374 </para> 2375 </listitem> 2376 2377 <listitem> 2378 <para> 2379 <structfield>rates</structfield> field contains the bit-flags of 2380 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>). 2381 When the chip supports continuous rates, pass 2382 <constant>CONTINUOUS</constant> bit additionally. 2383 The pre-defined rate bits are provided only for typical 2384 rates. If your chip supports unconventional rates, you need to add 2385 the <constant>KNOT</constant> bit and set up the hardware 2386 constraint manually (explained later). 2387 </para> 2388 </listitem> 2389 2390 <listitem> 2391 <para> 2392 <structfield>rate_min</structfield> and 2393 <structfield>rate_max</structfield> define the minimum and 2394 maximum sample rate. This should correspond somehow to 2395 <structfield>rates</structfield> bits. 2396 </para> 2397 </listitem> 2398 2399 <listitem> 2400 <para> 2401 <structfield>channel_min</structfield> and 2402 <structfield>channel_max</structfield> 2403 define, as you might already expected, the minimum and maximum 2404 number of channels. 2405 </para> 2406 </listitem> 2407 2408 <listitem> 2409 <para> 2410 <structfield>buffer_bytes_max</structfield> defines the 2411 maximum buffer size in bytes. There is no 2412 <structfield>buffer_bytes_min</structfield> field, since 2413 it can be calculated from the minimum period size and the 2414 minimum number of periods. 2415 Meanwhile, <structfield>period_bytes_min</structfield> and 2416 define the minimum and maximum size of the period in bytes. 2417 <structfield>periods_max</structfield> and 2418 <structfield>periods_min</structfield> define the maximum and 2419 minimum number of periods in the buffer. 2420 </para> 2421 2422 <para> 2423 The <quote>period</quote> is a term that corresponds to 2424 a fragment in the OSS world. The period defines the size at 2425 which a PCM interrupt is generated. This size strongly 2426 depends on the hardware. 2427 Generally, the smaller period size will give you more 2428 interrupts, that is, more controls. 2429 In the case of capture, this size defines the input latency. 2430 On the other hand, the whole buffer size defines the 2431 output latency for the playback direction. 2432 </para> 2433 </listitem> 2434 2435 <listitem> 2436 <para> 2437 There is also a field <structfield>fifo_size</structfield>. 2438 This specifies the size of the hardware FIFO, but currently it 2439 is neither used in the driver nor in the alsa-lib. So, you 2440 can ignore this field. 2441 </para> 2442 </listitem> 2443 </itemizedlist> 2444 </para> 2445 </section> 2446 2447 <section id="pcm-interface-runtime-config"> 2448 <title>PCM Configurations</title> 2449 <para> 2450 Ok, let's go back again to the PCM runtime records. 2451 The most frequently referred records in the runtime instance are 2452 the PCM configurations. 2453 The PCM configurations are stored in the runtime instance 2454 after the application sends <type>hw_params</type> data via 2455 alsa-lib. There are many fields copied from hw_params and 2456 sw_params structs. For example, 2457 <structfield>format</structfield> holds the format type 2458 chosen by the application. This field contains the enum value 2459 <constant>SNDRV_PCM_FORMAT_XXX</constant>. 2460 </para> 2461 2462 <para> 2463 One thing to be noted is that the configured buffer and period 2464 sizes are stored in <quote>frames</quote> in the runtime. 2465 In the ALSA world, 1 frame = channels * samples-size. 2466 For conversion between frames and bytes, you can use the 2467 <function>frames_to_bytes()</function> and 2468 <function>bytes_to_frames()</function> helper functions. 2469 <informalexample> 2470 <programlisting> 2471 <![CDATA[ 2472 period_bytes = frames_to_bytes(runtime, runtime->period_size); 2473 ]]> 2474 </programlisting> 2475 </informalexample> 2476 </para> 2477 2478 <para> 2479 Also, many software parameters (sw_params) are 2480 stored in frames, too. Please check the type of the field. 2481 <type>snd_pcm_uframes_t</type> is for the frames as unsigned 2482 integer while <type>snd_pcm_sframes_t</type> is for the frames 2483 as signed integer. 2484 </para> 2485 </section> 2486 2487 <section id="pcm-interface-runtime-dma"> 2488 <title>DMA Buffer Information</title> 2489 <para> 2490 The DMA buffer is defined by the following four fields, 2491 <structfield>dma_area</structfield>, 2492 <structfield>dma_addr</structfield>, 2493 <structfield>dma_bytes</structfield> and 2494 <structfield>dma_private</structfield>. 2495 The <structfield>dma_area</structfield> holds the buffer 2496 pointer (the logical address). You can call 2497 <function>memcpy</function> from/to 2498 this pointer. Meanwhile, <structfield>dma_addr</structfield> 2499 holds the physical address of the buffer. This field is 2500 specified only when the buffer is a linear buffer. 2501 <structfield>dma_bytes</structfield> holds the size of buffer 2502 in bytes. <structfield>dma_private</structfield> is used for 2503 the ALSA DMA allocator. 2504 </para> 2505 2506 <para> 2507 If you use a standard ALSA function, 2508 <function>snd_pcm_lib_malloc_pages()</function>, for 2509 allocating the buffer, these fields are set by the ALSA middle 2510 layer, and you should <emphasis>not</emphasis> change them by 2511 yourself. You can read them but not write them. 2512 On the other hand, if you want to allocate the buffer by 2513 yourself, you'll need to manage it in hw_params callback. 2514 At least, <structfield>dma_bytes</structfield> is mandatory. 2515 <structfield>dma_area</structfield> is necessary when the 2516 buffer is mmapped. If your driver doesn't support mmap, this 2517 field is not necessary. <structfield>dma_addr</structfield> 2518 is also optional. You can use 2519 <structfield>dma_private</structfield> as you like, too. 2520 </para> 2521 </section> 2522 2523 <section id="pcm-interface-runtime-status"> 2524 <title>Running Status</title> 2525 <para> 2526 The running status can be referred via <constant>runtime->status</constant>. 2527 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname> 2528 record. For example, you can get the current DMA hardware 2529 pointer via <constant>runtime->status->hw_ptr</constant>. 2530 </para> 2531 2532 <para> 2533 The DMA application pointer can be referred via 2534 <constant>runtime->control</constant>, which points to the 2535 struct <structname>snd_pcm_mmap_control</structname> record. 2536 However, accessing directly to this value is not recommended. 2537 </para> 2538 </section> 2539 2540 <section id="pcm-interface-runtime-private"> 2541 <title>Private Data</title> 2542 <para> 2543 You can allocate a record for the substream and store it in 2544 <constant>runtime->private_data</constant>. Usually, this 2545 is done in 2546 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2547 the open callback</citetitle></link>. 2548 Don't mix this with <constant>pcm->private_data</constant>. 2549 The <constant>pcm->private_data</constant> usually points to the 2550 chip instance assigned statically at the creation of PCM, while the 2551 <constant>runtime->private_data</constant> points to a dynamic 2552 data structure created at the PCM open callback. 2553 2554 <informalexample> 2555 <programlisting> 2556 <![CDATA[ 2557 static int snd_xxx_open(struct snd_pcm_substream *substream) 2558 { 2559 struct my_pcm_data *data; 2560 .... 2561 data = kmalloc(sizeof(*data), GFP_KERNEL); 2562 substream->runtime->private_data = data; 2563 .... 2564 } 2565 ]]> 2566 </programlisting> 2567 </informalexample> 2568 </para> 2569 2570 <para> 2571 The allocated object must be released in 2572 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2573 the close callback</citetitle></link>. 2574 </para> 2575 </section> 2576 2577 <section id="pcm-interface-runtime-intr"> 2578 <title>Interrupt Callbacks</title> 2579 <para> 2580 The field <structfield>transfer_ack_begin</structfield> and 2581 <structfield>transfer_ack_end</structfield> are called at 2582 the beginning and at the end of 2583 <function>snd_pcm_period_elapsed()</function>, respectively. 2584 </para> 2585 </section> 2586 2587 </section> 2588 2589 <section id="pcm-interface-operators"> 2590 <title>Operators</title> 2591 <para> 2592 OK, now let me give details about each pcm callback 2593 (<parameter>ops</parameter>). In general, every callback must 2594 return 0 if successful, or a negative error number 2595 such as <constant>-EINVAL</constant>. To choose an appropriate 2596 error number, it is advised to check what value other parts of 2597 the kernel return when the same kind of request fails. 2598 </para> 2599 2600 <para> 2601 The callback function takes at least the argument with 2602 <structname>snd_pcm_substream</structname> pointer. To retrieve 2603 the chip record from the given substream instance, you can use the 2604 following macro. 2605 2606 <informalexample> 2607 <programlisting> 2608 <![CDATA[ 2609 int xxx() { 2610 struct mychip *chip = snd_pcm_substream_chip(substream); 2611 .... 2612 } 2613 ]]> 2614 </programlisting> 2615 </informalexample> 2616 2617 The macro reads <constant>substream->private_data</constant>, 2618 which is a copy of <constant>pcm->private_data</constant>. 2619 You can override the former if you need to assign different data 2620 records per PCM substream. For example, the cmi8330 driver assigns 2621 different private_data for playback and capture directions, 2622 because it uses two different codecs (SB- and AD-compatible) for 2623 different directions. 2624 </para> 2625 2626 <section id="pcm-interface-operators-open-callback"> 2627 <title>open callback</title> 2628 <para> 2629 <informalexample> 2630 <programlisting> 2631 <![CDATA[ 2632 static int snd_xxx_open(struct snd_pcm_substream *substream); 2633 ]]> 2634 </programlisting> 2635 </informalexample> 2636 2637 This is called when a pcm substream is opened. 2638 </para> 2639 2640 <para> 2641 At least, here you have to initialize the runtime->hw 2642 record. Typically, this is done by like this: 2643 2644 <informalexample> 2645 <programlisting> 2646 <![CDATA[ 2647 static int snd_xxx_open(struct snd_pcm_substream *substream) 2648 { 2649 struct mychip *chip = snd_pcm_substream_chip(substream); 2650 struct snd_pcm_runtime *runtime = substream->runtime; 2651 2652 runtime->hw = snd_mychip_playback_hw; 2653 return 0; 2654 } 2655 ]]> 2656 </programlisting> 2657 </informalexample> 2658 2659 where <parameter>snd_mychip_playback_hw</parameter> is the 2660 pre-defined hardware description. 2661 </para> 2662 2663 <para> 2664 You can allocate a private data in this callback, as described 2665 in <link linkend="pcm-interface-runtime-private"><citetitle> 2666 Private Data</citetitle></link> section. 2667 </para> 2668 2669 <para> 2670 If the hardware configuration needs more constraints, set the 2671 hardware constraints here, too. 2672 See <link linkend="pcm-interface-constraints"><citetitle> 2673 Constraints</citetitle></link> for more details. 2674 </para> 2675 </section> 2676 2677 <section id="pcm-interface-operators-close-callback"> 2678 <title>close callback</title> 2679 <para> 2680 <informalexample> 2681 <programlisting> 2682 <![CDATA[ 2683 static int snd_xxx_close(struct snd_pcm_substream *substream); 2684 ]]> 2685 </programlisting> 2686 </informalexample> 2687 2688 Obviously, this is called when a pcm substream is closed. 2689 </para> 2690 2691 <para> 2692 Any private instance for a pcm substream allocated in the 2693 open callback will be released here. 2694 2695 <informalexample> 2696 <programlisting> 2697 <![CDATA[ 2698 static int snd_xxx_close(struct snd_pcm_substream *substream) 2699 { 2700 .... 2701 kfree(substream->runtime->private_data); 2702 .... 2703 } 2704 ]]> 2705 </programlisting> 2706 </informalexample> 2707 </para> 2708 </section> 2709 2710 <section id="pcm-interface-operators-ioctl-callback"> 2711 <title>ioctl callback</title> 2712 <para> 2713 This is used for any special call to pcm ioctls. But 2714 usually you can pass a generic ioctl callback, 2715 <function>snd_pcm_lib_ioctl</function>. 2716 </para> 2717 </section> 2718 2719 <section id="pcm-interface-operators-hw-params-callback"> 2720 <title>hw_params callback</title> 2721 <para> 2722 <informalexample> 2723 <programlisting> 2724 <![CDATA[ 2725 static int snd_xxx_hw_params(struct snd_pcm_substream *substream, 2726 struct snd_pcm_hw_params *hw_params); 2727 ]]> 2728 </programlisting> 2729 </informalexample> 2730 </para> 2731 2732 <para> 2733 This is called when the hardware parameter 2734 (<structfield>hw_params</structfield>) is set 2735 up by the application, 2736 that is, once when the buffer size, the period size, the 2737 format, etc. are defined for the pcm substream. 2738 </para> 2739 2740 <para> 2741 Many hardware setups should be done in this callback, 2742 including the allocation of buffers. 2743 </para> 2744 2745 <para> 2746 Parameters to be initialized are retrieved by 2747 <function>params_xxx()</function> macros. To allocate 2748 buffer, you can call a helper function, 2749 2750 <informalexample> 2751 <programlisting> 2752 <![CDATA[ 2753 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); 2754 ]]> 2755 </programlisting> 2756 </informalexample> 2757 2758 <function>snd_pcm_lib_malloc_pages()</function> is available 2759 only when the DMA buffers have been pre-allocated. 2760 See the section <link 2761 linkend="buffer-and-memory-buffer-types"><citetitle> 2762 Buffer Types</citetitle></link> for more details. 2763 </para> 2764 2765 <para> 2766 Note that this and <structfield>prepare</structfield> callbacks 2767 may be called multiple times per initialization. 2768 For example, the OSS emulation may 2769 call these callbacks at each change via its ioctl. 2770 </para> 2771 2772 <para> 2773 Thus, you need to be careful not to allocate the same buffers 2774 many times, which will lead to memory leaks! Calling the 2775 helper function above many times is OK. It will release the 2776 previous buffer automatically when it was already allocated. 2777 </para> 2778 2779 <para> 2780 Another note is that this callback is non-atomic 2781 (schedulable). This is important, because the 2782 <structfield>trigger</structfield> callback 2783 is atomic (non-schedulable). That is, mutexes or any 2784 schedule-related functions are not available in 2785 <structfield>trigger</structfield> callback. 2786 Please see the subsection 2787 <link linkend="pcm-interface-atomicity"><citetitle> 2788 Atomicity</citetitle></link> for details. 2789 </para> 2790 </section> 2791 2792 <section id="pcm-interface-operators-hw-free-callback"> 2793 <title>hw_free callback</title> 2794 <para> 2795 <informalexample> 2796 <programlisting> 2797 <![CDATA[ 2798 static int snd_xxx_hw_free(struct snd_pcm_substream *substream); 2799 ]]> 2800 </programlisting> 2801 </informalexample> 2802 </para> 2803 2804 <para> 2805 This is called to release the resources allocated via 2806 <structfield>hw_params</structfield>. For example, releasing the 2807 buffer via 2808 <function>snd_pcm_lib_malloc_pages()</function> is done by 2809 calling the following: 2810 2811 <informalexample> 2812 <programlisting> 2813 <![CDATA[ 2814 snd_pcm_lib_free_pages(substream); 2815 ]]> 2816 </programlisting> 2817 </informalexample> 2818 </para> 2819 2820 <para> 2821 This function is always called before the close callback is called. 2822 Also, the callback may be called multiple times, too. 2823 Keep track whether the resource was already released. 2824 </para> 2825 </section> 2826 2827 <section id="pcm-interface-operators-prepare-callback"> 2828 <title>prepare callback</title> 2829 <para> 2830 <informalexample> 2831 <programlisting> 2832 <![CDATA[ 2833 static int snd_xxx_prepare(struct snd_pcm_substream *substream); 2834 ]]> 2835 </programlisting> 2836 </informalexample> 2837 </para> 2838 2839 <para> 2840 This callback is called when the pcm is 2841 <quote>prepared</quote>. You can set the format type, sample 2842 rate, etc. here. The difference from 2843 <structfield>hw_params</structfield> is that the 2844 <structfield>prepare</structfield> callback will be called each 2845 time 2846 <function>snd_pcm_prepare()</function> is called, i.e. when 2847 recovering after underruns, etc. 2848 </para> 2849 2850 <para> 2851 Note that this callback is now non-atomic. 2852 You can use schedule-related functions safely in this callback. 2853 </para> 2854 2855 <para> 2856 In this and the following callbacks, you can refer to the 2857 values via the runtime record, 2858 substream->runtime. 2859 For example, to get the current 2860 rate, format or channels, access to 2861 runtime->rate, 2862 runtime->format or 2863 runtime->channels, respectively. 2864 The physical address of the allocated buffer is set to 2865 runtime->dma_area. The buffer and period sizes are 2866 in runtime->buffer_size and runtime->period_size, 2867 respectively. 2868 </para> 2869 2870 <para> 2871 Be careful that this callback will be called many times at 2872 each setup, too. 2873 </para> 2874 </section> 2875 2876 <section id="pcm-interface-operators-trigger-callback"> 2877 <title>trigger callback</title> 2878 <para> 2879 <informalexample> 2880 <programlisting> 2881 <![CDATA[ 2882 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); 2883 ]]> 2884 </programlisting> 2885 </informalexample> 2886 2887 This is called when the pcm is started, stopped or paused. 2888 </para> 2889 2890 <para> 2891 Which action is specified in the second argument, 2892 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in 2893 <filename><sound/pcm.h></filename>. At least, 2894 the <constant>START</constant> and <constant>STOP</constant> 2895 commands must be defined in this callback. 2896 2897 <informalexample> 2898 <programlisting> 2899 <![CDATA[ 2900 switch (cmd) { 2901 case SNDRV_PCM_TRIGGER_START: 2902 /* do something to start the PCM engine */ 2903 break; 2904 case SNDRV_PCM_TRIGGER_STOP: 2905 /* do something to stop the PCM engine */ 2906 break; 2907 default: 2908 return -EINVAL; 2909 } 2910 ]]> 2911 </programlisting> 2912 </informalexample> 2913 </para> 2914 2915 <para> 2916 When the pcm supports the pause operation (given in the info 2917 field of the hardware table), the <constant>PAUSE_PUSE</constant> 2918 and <constant>PAUSE_RELEASE</constant> commands must be 2919 handled here, too. The former is the command to pause the pcm, 2920 and the latter to restart the pcm again. 2921 </para> 2922 2923 <para> 2924 When the pcm supports the suspend/resume operation, 2925 regardless of full or partial suspend/resume support, 2926 the <constant>SUSPEND</constant> and <constant>RESUME</constant> 2927 commands must be handled, too. 2928 These commands are issued when the power-management status is 2929 changed. Obviously, the <constant>SUSPEND</constant> and 2930 <constant>RESUME</constant> commands 2931 suspend and resume the pcm substream, and usually, they 2932 are identical to the <constant>STOP</constant> and 2933 <constant>START</constant> commands, respectively. 2934 See the <link linkend="power-management"><citetitle> 2935 Power Management</citetitle></link> section for details. 2936 </para> 2937 2938 <para> 2939 As mentioned, this callback is atomic. You cannot call 2940 functions which may sleep. 2941 The trigger callback should be as minimal as possible, 2942 just really triggering the DMA. The other stuff should be 2943 initialized hw_params and prepare callbacks properly 2944 beforehand. 2945 </para> 2946 </section> 2947 2948 <section id="pcm-interface-operators-pointer-callback"> 2949 <title>pointer callback</title> 2950 <para> 2951 <informalexample> 2952 <programlisting> 2953 <![CDATA[ 2954 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) 2955 ]]> 2956 </programlisting> 2957 </informalexample> 2958 2959 This callback is called when the PCM middle layer inquires 2960 the current hardware position on the buffer. The position must 2961 be returned in frames, 2962 ranging from 0 to buffer_size - 1. 2963 </para> 2964 2965 <para> 2966 This is called usually from the buffer-update routine in the 2967 pcm middle layer, which is invoked when 2968 <function>snd_pcm_period_elapsed()</function> is called in the 2969 interrupt routine. Then the pcm middle layer updates the 2970 position and calculates the available space, and wakes up the 2971 sleeping poll threads, etc. 2972 </para> 2973 2974 <para> 2975 This callback is also atomic. 2976 </para> 2977 </section> 2978 2979 <section id="pcm-interface-operators-copy-silence"> 2980 <title>copy and silence callbacks</title> 2981 <para> 2982 These callbacks are not mandatory, and can be omitted in 2983 most cases. These callbacks are used when the hardware buffer 2984 cannot be in the normal memory space. Some chips have their 2985 own buffer on the hardware which is not mappable. In such a 2986 case, you have to transfer the data manually from the memory 2987 buffer to the hardware buffer. Or, if the buffer is 2988 non-contiguous on both physical and virtual memory spaces, 2989 these callbacks must be defined, too. 2990 </para> 2991 2992 <para> 2993 If these two callbacks are defined, copy and set-silence 2994 operations are done by them. The detailed will be described in 2995 the later section <link 2996 linkend="buffer-and-memory"><citetitle>Buffer and Memory 2997 Management</citetitle></link>. 2998 </para> 2999 </section> 3000 3001 <section id="pcm-interface-operators-ack"> 3002 <title>ack callback</title> 3003 <para> 3004 This callback is also not mandatory. This callback is called 3005 when the appl_ptr is updated in read or write operations. 3006 Some drivers like emu10k1-fx and cs46xx need to track the 3007 current appl_ptr for the internal buffer, and this callback 3008 is useful only for such a purpose. 3009 </para> 3010 <para> 3011 This callback is atomic. 3012 </para> 3013 </section> 3014 3015 <section id="pcm-interface-operators-page-callback"> 3016 <title>page callback</title> 3017 3018 <para> 3019 This callback is optional too. This callback is used 3020 mainly for non-contiguous buffers. The mmap calls this 3021 callback to get the page address. Some examples will be 3022 explained in the later section <link 3023 linkend="buffer-and-memory"><citetitle>Buffer and Memory 3024 Management</citetitle></link>, too. 3025 </para> 3026 </section> 3027 </section> 3028 3029 <section id="pcm-interface-interrupt-handler"> 3030 <title>Interrupt Handler</title> 3031 <para> 3032 The rest of pcm stuff is the PCM interrupt handler. The 3033 role of PCM interrupt handler in the sound driver is to update 3034 the buffer position and to tell the PCM middle layer when the 3035 buffer position goes across the prescribed period size. To 3036 inform this, call the <function>snd_pcm_period_elapsed()</function> 3037 function. 3038 </para> 3039 3040 <para> 3041 There are several types of sound chips to generate the interrupts. 3042 </para> 3043 3044 <section id="pcm-interface-interrupt-handler-boundary"> 3045 <title>Interrupts at the period (fragment) boundary</title> 3046 <para> 3047 This is the most frequently found type: the hardware 3048 generates an interrupt at each period boundary. 3049 In this case, you can call 3050 <function>snd_pcm_period_elapsed()</function> at each 3051 interrupt. 3052 </para> 3053 3054 <para> 3055 <function>snd_pcm_period_elapsed()</function> takes the 3056 substream pointer as its argument. Thus, you need to keep the 3057 substream pointer accessible from the chip instance. For 3058 example, define substream field in the chip record to hold the 3059 current running substream pointer, and set the pointer value 3060 at open callback (and reset at close callback). 3061 </para> 3062 3063 <para> 3064 If you acquire a spinlock in the interrupt handler, and the 3065 lock is used in other pcm callbacks, too, then you have to 3066 release the lock before calling 3067 <function>snd_pcm_period_elapsed()</function>, because 3068 <function>snd_pcm_period_elapsed()</function> calls other pcm 3069 callbacks inside. 3070 </para> 3071 3072 <para> 3073 Typical code would be like: 3074 3075 <example> 3076 <title>Interrupt Handler Case #1</title> 3077 <programlisting> 3078 <![CDATA[ 3079 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 3080 { 3081 struct mychip *chip = dev_id; 3082 spin_lock(&chip->lock); 3083 .... 3084 if (pcm_irq_invoked(chip)) { 3085 /* call updater, unlock before it */ 3086 spin_unlock(&chip->lock); 3087 snd_pcm_period_elapsed(chip->substream); 3088 spin_lock(&chip->lock); 3089 /* acknowledge the interrupt if necessary */ 3090 } 3091 .... 3092 spin_unlock(&chip->lock); 3093 return IRQ_HANDLED; 3094 } 3095 ]]> 3096 </programlisting> 3097 </example> 3098 </para> 3099 </section> 3100 3101 <section id="pcm-interface-interrupt-handler-timer"> 3102 <title>High frequency timer interrupts</title> 3103 <para> 3104 This happense when the hardware doesn't generate interrupts 3105 at the period boundary but issues timer interrupts at a fixed 3106 timer rate (e.g. es1968 or ymfpci drivers). 3107 In this case, you need to check the current hardware 3108 position and accumulate the processed sample length at each 3109 interrupt. When the accumulated size exceeds the period 3110 size, call 3111 <function>snd_pcm_period_elapsed()</function> and reset the 3112 accumulator. 3113 </para> 3114 3115 <para> 3116 Typical code would be like the following. 3117 3118 <example> 3119 <title>Interrupt Handler Case #2</title> 3120 <programlisting> 3121 <![CDATA[ 3122 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 3123 { 3124 struct mychip *chip = dev_id; 3125 spin_lock(&chip->lock); 3126 .... 3127 if (pcm_irq_invoked(chip)) { 3128 unsigned int last_ptr, size; 3129 /* get the current hardware pointer (in frames) */ 3130 last_ptr = get_hw_ptr(chip); 3131 /* calculate the processed frames since the 3132 * last update 3133 */ 3134 if (last_ptr < chip->last_ptr) 3135 size = runtime->buffer_size + last_ptr 3136 - chip->last_ptr; 3137 else 3138 size = last_ptr - chip->last_ptr; 3139 /* remember the last updated point */ 3140 chip->last_ptr = last_ptr; 3141 /* accumulate the size */ 3142 chip->size += size; 3143 /* over the period boundary? */ 3144 if (chip->size >= runtime->period_size) { 3145 /* reset the accumulator */ 3146 chip->size %= runtime->period_size; 3147 /* call updater */ 3148 spin_unlock(&chip->lock); 3149 snd_pcm_period_elapsed(substream); 3150 spin_lock(&chip->lock); 3151 } 3152 /* acknowledge the interrupt if necessary */ 3153 } 3154 .... 3155 spin_unlock(&chip->lock); 3156 return IRQ_HANDLED; 3157 } 3158 ]]> 3159 </programlisting> 3160 </example> 3161 </para> 3162 </section> 3163 3164 <section id="pcm-interface-interrupt-handler-both"> 3165 <title>On calling <function>snd_pcm_period_elapsed()</function></title> 3166 <para> 3167 In both cases, even if more than one period are elapsed, you 3168 don't have to call 3169 <function>snd_pcm_period_elapsed()</function> many times. Call 3170 only once. And the pcm layer will check the current hardware 3171 pointer and update to the latest status. 3172 </para> 3173 </section> 3174 </section> 3175 3176 <section id="pcm-interface-atomicity"> 3177 <title>Atomicity</title> 3178 <para> 3179 One of the most important (and thus difficult to debug) problems 3180 in kernel programming are race conditions. 3181 In the Linux kernel, they are usually avoided via spin-locks, mutexes 3182 or semaphores. In general, if a race condition can happen 3183 in an interrupt handler, it has to be managed atomically, and you 3184 have to use a spinlock to protect the critical session. If the 3185 critical section is not in interrupt handler code and 3186 if taking a relatively long time to execute is acceptable, you 3187 should use mutexes or semaphores instead. 3188 </para> 3189 3190 <para> 3191 As already seen, some pcm callbacks are atomic and some are 3192 not. For example, the <parameter>hw_params</parameter> callback is 3193 non-atomic, while <parameter>trigger</parameter> callback is 3194 atomic. This means, the latter is called already in a spinlock 3195 held by the PCM middle layer. Please take this atomicity into 3196 account when you choose a locking scheme in the callbacks. 3197 </para> 3198 3199 <para> 3200 In the atomic callbacks, you cannot use functions which may call 3201 <function>schedule</function> or go to 3202 <function>sleep</function>. Semaphores and mutexes can sleep, 3203 and hence they cannot be used inside the atomic callbacks 3204 (e.g. <parameter>trigger</parameter> callback). 3205 To implement some delay in such a callback, please use 3206 <function>udelay()</function> or <function>mdelay()</function>. 3207 </para> 3208 3209 <para> 3210 All three atomic callbacks (trigger, pointer, and ack) are 3211 called with local interrupts disabled. 3212 </para> 3213 3214 </section> 3215 <section id="pcm-interface-constraints"> 3216 <title>Constraints</title> 3217 <para> 3218 If your chip supports unconventional sample rates, or only the 3219 limited samples, you need to set a constraint for the 3220 condition. 3221 </para> 3222 3223 <para> 3224 For example, in order to restrict the sample rates in the some 3225 supported values, use 3226 <function>snd_pcm_hw_constraint_list()</function>. 3227 You need to call this function in the open callback. 3228 3229 <example> 3230 <title>Example of Hardware Constraints</title> 3231 <programlisting> 3232 <![CDATA[ 3233 static unsigned int rates[] = 3234 {4000, 10000, 22050, 44100}; 3235 static struct snd_pcm_hw_constraint_list constraints_rates = { 3236 .count = ARRAY_SIZE(rates), 3237 .list = rates, 3238 .mask = 0, 3239 }; 3240 3241 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) 3242 { 3243 int err; 3244 .... 3245 err = snd_pcm_hw_constraint_list(substream->runtime, 0, 3246 SNDRV_PCM_HW_PARAM_RATE, 3247 &constraints_rates); 3248 if (err < 0) 3249 return err; 3250 .... 3251 } 3252 ]]> 3253 </programlisting> 3254 </example> 3255 </para> 3256 3257 <para> 3258 There are many different constraints. 3259 Look at <filename>sound/pcm.h</filename> for a complete list. 3260 You can even define your own constraint rules. 3261 For example, let's suppose my_chip can manage a substream of 1 channel 3262 if and only if the format is S16_LE, otherwise it supports any format 3263 specified in the <structname>snd_pcm_hardware</structname> structure (or in any 3264 other constraint_list). You can build a rule like this: 3265 3266 <example> 3267 <title>Example of Hardware Constraints for Channels</title> 3268 <programlisting> 3269 <![CDATA[ 3270 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, 3271 struct snd_pcm_hw_rule *rule) 3272 { 3273 struct snd_interval *c = hw_param_interval(params, 3274 SNDRV_PCM_HW_PARAM_CHANNELS); 3275 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 3276 struct snd_mask fmt; 3277 3278 snd_mask_any(&fmt); /* Init the struct */ 3279 if (c->min < 2) { 3280 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; 3281 return snd_mask_refine(f, &fmt); 3282 } 3283 return 0; 3284 } 3285 ]]> 3286 </programlisting> 3287 </example> 3288 </para> 3289 3290 <para> 3291 Then you need to call this function to add your rule: 3292 3293 <informalexample> 3294 <programlisting> 3295 <![CDATA[ 3296 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, 3297 hw_rule_channels_by_format, 0, SNDRV_PCM_HW_PARAM_FORMAT, 3298 -1); 3299 ]]> 3300 </programlisting> 3301 </informalexample> 3302 </para> 3303 3304 <para> 3305 The rule function is called when an application sets the number of 3306 channels. But an application can set the format before the number of 3307 channels. Thus you also need to define the inverse rule: 3308 3309 <example> 3310 <title>Example of Hardware Constraints for Channels</title> 3311 <programlisting> 3312 <![CDATA[ 3313 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, 3314 struct snd_pcm_hw_rule *rule) 3315 { 3316 struct snd_interval *c = hw_param_interval(params, 3317 SNDRV_PCM_HW_PARAM_CHANNELS); 3318 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 3319 struct snd_interval ch; 3320 3321 snd_interval_any(&ch); 3322 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { 3323 ch.min = ch.max = 1; 3324 ch.integer = 1; 3325 return snd_interval_refine(c, &ch); 3326 } 3327 return 0; 3328 } 3329 ]]> 3330 </programlisting> 3331 </example> 3332 </para> 3333 3334 <para> 3335 ...and in the open callback: 3336 <informalexample> 3337 <programlisting> 3338 <![CDATA[ 3339 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, 3340 hw_rule_format_by_channels, 0, SNDRV_PCM_HW_PARAM_CHANNELS, 3341 -1); 3342 ]]> 3343 </programlisting> 3344 </informalexample> 3345 </para> 3346 3347 <para> 3348 I won't give more details here, rather I 3349 would like to say, <quote>Luke, use the source.</quote> 3350 </para> 3351 </section> 3352 3353 </chapter> 3354 3355 3356 <!-- ****************************************************** --> 3357 <!-- Control Interface --> 3358 <!-- ****************************************************** --> 3359 <chapter id="control-interface"> 3360 <title>Control Interface</title> 3361 3362 <section id="control-interface-general"> 3363 <title>General</title> 3364 <para> 3365 The control interface is used widely for many switches, 3366 sliders, etc. which are accessed from user-space. Its most 3367 important use is the mixer interface. In other words, since ALSA 3368 0.9.x, all the mixer stuff is implemented on the control kernel API. 3369 </para> 3370 3371 <para> 3372 ALSA has a well-defined AC97 control module. If your chip 3373 supports only the AC97 and nothing else, you can skip this 3374 section. 3375 </para> 3376 3377 <para> 3378 The control API is defined in 3379 <filename><sound/control.h></filename>. 3380 Include this file if you want to add your own controls. 3381 </para> 3382 </section> 3383 3384 <section id="control-interface-definition"> 3385 <title>Definition of Controls</title> 3386 <para> 3387 To create a new control, you need to define the 3388 following three 3389 callbacks: <structfield>info</structfield>, 3390 <structfield>get</structfield> and 3391 <structfield>put</structfield>. Then, define a 3392 struct <structname>snd_kcontrol_new</structname> record, such as: 3393 3394 <example> 3395 <title>Definition of a Control</title> 3396 <programlisting> 3397 <![CDATA[ 3398 static struct snd_kcontrol_new my_control __devinitdata = { 3399 .iface = SNDRV_CTL_ELEM_IFACE_MIXER, 3400 .name = "PCM Playback Switch", 3401 .index = 0, 3402 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, 3403 .private_value = 0xffff, 3404 .info = my_control_info, 3405 .get = my_control_get, 3406 .put = my_control_put 3407 }; 3408 ]]> 3409 </programlisting> 3410 </example> 3411 </para> 3412 3413 <para> 3414 Most likely the control is created via 3415 <function>snd_ctl_new1()</function>, and in such a case, you can 3416 add the <parameter>__devinitdata</parameter> prefix to the 3417 definition as above. 3418 </para> 3419 3420 <para> 3421 The <structfield>iface</structfield> field specifies the control 3422 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which 3423 is usually <constant>MIXER</constant>. 3424 Use <constant>CARD</constant> for global controls that are not 3425 logically part of the mixer. 3426 If the control is closely associated with some specific device on 3427 the sound card, use <constant>HWDEP</constant>, 3428 <constant>PCM</constant>, <constant>RAWMIDI</constant>, 3429 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and 3430 specify the device number with the 3431 <structfield>device</structfield> and 3432 <structfield>subdevice</structfield> fields. 3433 </para> 3434 3435 <para> 3436 The <structfield>name</structfield> is the name identifier 3437 string. Since ALSA 0.9.x, the control name is very important, 3438 because its role is classified from its name. There are 3439 pre-defined standard control names. The details are described in 3440 the <link linkend="control-interface-control-names"><citetitle> 3441 Control Names</citetitle></link> subsection. 3442 </para> 3443 3444 <para> 3445 The <structfield>index</structfield> field holds the index number 3446 of this control. If there are several different controls with 3447 the same name, they can be distinguished by the index 3448 number. This is the case when 3449 several codecs exist on the card. If the index is zero, you can 3450 omit the definition above. 3451 </para> 3452 3453 <para> 3454 The <structfield>access</structfield> field contains the access 3455 type of this control. Give the combination of bit masks, 3456 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there. 3457 The details will be explained in 3458 the <link linkend="control-interface-access-flags"><citetitle> 3459 Access Flags</citetitle></link> subsection. 3460 </para> 3461 3462 <para> 3463 The <structfield>private_value</structfield> field contains 3464 an arbitrary long integer value for this record. When using 3465 the generic <structfield>info</structfield>, 3466 <structfield>get</structfield> and 3467 <structfield>put</structfield> callbacks, you can pass a value 3468 through this field. If several small numbers are necessary, you can 3469 combine them in bitwise. Or, it's possible to give a pointer 3470 (casted to unsigned long) of some record to this field, too. 3471 </para> 3472 3473 <para> 3474 The <structfield>tlv</structfield> field can be used to provide 3475 metadata about the control; see the 3476 <link linkend="control-interface-tlv"> 3477 <citetitle>Metadata</citetitle></link> subsection. 3478 </para> 3479 3480 <para> 3481 The other three are 3482 <link linkend="control-interface-callbacks"><citetitle> 3483 callback functions</citetitle></link>. 3484 </para> 3485 </section> 3486 3487 <section id="control-interface-control-names"> 3488 <title>Control Names</title> 3489 <para> 3490 There are some standards to define the control names. A 3491 control is usually defined from the three parts as 3492 <quote>SOURCE DIRECTION FUNCTION</quote>. 3493 </para> 3494 3495 <para> 3496 The first, <constant>SOURCE</constant>, specifies the source 3497 of the control, and is a string such as <quote>Master</quote>, 3498 <quote>PCM</quote>, <quote>CD</quote> and 3499 <quote>Line</quote>. There are many pre-defined sources. 3500 </para> 3501 3502 <para> 3503 The second, <constant>DIRECTION</constant>, is one of the 3504 following strings according to the direction of the control: 3505 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass 3506 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can 3507 be omitted, meaning both playback and capture directions. 3508 </para> 3509 3510 <para> 3511 The third, <constant>FUNCTION</constant>, is one of the 3512 following strings according to the function of the control: 3513 <quote>Switch</quote>, <quote>Volume</quote> and 3514 <quote>Route</quote>. 3515 </para> 3516 3517 <para> 3518 The example of control names are, thus, <quote>Master Capture 3519 Switch</quote> or <quote>PCM Playback Volume</quote>. 3520 </para> 3521 3522 <para> 3523 There are some exceptions: 3524 </para> 3525 3526 <section id="control-interface-control-names-global"> 3527 <title>Global capture and playback</title> 3528 <para> 3529 <quote>Capture Source</quote>, <quote>Capture Switch</quote> 3530 and <quote>Capture Volume</quote> are used for the global 3531 capture (input) source, switch and volume. Similarly, 3532 <quote>Playback Switch</quote> and <quote>Playback 3533 Volume</quote> are used for the global output gain switch and 3534 volume. 3535 </para> 3536 </section> 3537 3538 <section id="control-interface-control-names-tone"> 3539 <title>Tone-controls</title> 3540 <para> 3541 tone-control switch and volumes are specified like 3542 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control - 3543 Switch</quote>, <quote>Tone Control - Bass</quote>, 3544 <quote>Tone Control - Center</quote>. 3545 </para> 3546 </section> 3547 3548 <section id="control-interface-control-names-3d"> 3549 <title>3D controls</title> 3550 <para> 3551 3D-control switches and volumes are specified like <quote>3D 3552 Control - XXX</quote>, e.g. <quote>3D Control - 3553 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D 3554 Control - Space</quote>. 3555 </para> 3556 </section> 3557 3558 <section id="control-interface-control-names-mic"> 3559 <title>Mic boost</title> 3560 <para> 3561 Mic-boost switch is set as <quote>Mic Boost</quote> or 3562 <quote>Mic Boost (6dB)</quote>. 3563 </para> 3564 3565 <para> 3566 More precise information can be found in 3567 <filename>Documentation/sound/alsa/ControlNames.txt</filename>. 3568 </para> 3569 </section> 3570 </section> 3571 3572 <section id="control-interface-access-flags"> 3573 <title>Access Flags</title> 3574 3575 <para> 3576 The access flag is the bitmask which specifies the access type 3577 of the given control. The default access type is 3578 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 3579 which means both read and write are allowed to this control. 3580 When the access flag is omitted (i.e. = 0), it is 3581 considered as <constant>READWRITE</constant> access as default. 3582 </para> 3583 3584 <para> 3585 When the control is read-only, pass 3586 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead. 3587 In this case, you don't have to define 3588 the <structfield>put</structfield> callback. 3589 Similarly, when the control is write-only (although it's a rare 3590 case), you can use the <constant>WRITE</constant> flag instead, and 3591 you don't need the <structfield>get</structfield> callback. 3592 </para> 3593 3594 <para> 3595 If the control value changes frequently (e.g. the VU meter), 3596 <constant>VOLATILE</constant> flag should be given. This means 3597 that the control may be changed without 3598 <link linkend="control-interface-change-notification"><citetitle> 3599 notification</citetitle></link>. Applications should poll such 3600 a control constantly. 3601 </para> 3602 3603 <para> 3604 When the control is inactive, set 3605 the <constant>INACTIVE</constant> flag, too. 3606 There are <constant>LOCK</constant> and 3607 <constant>OWNER</constant> flags to change the write 3608 permissions. 3609 </para> 3610 3611 </section> 3612 3613 <section id="control-interface-callbacks"> 3614 <title>Callbacks</title> 3615 3616 <section id="control-interface-callbacks-info"> 3617 <title>info callback</title> 3618 <para> 3619 The <structfield>info</structfield> callback is used to get 3620 detailed information on this control. This must store the 3621 values of the given struct <structname>snd_ctl_elem_info</structname> 3622 object. For example, for a boolean control with a single 3623 element: 3624 3625 <example> 3626 <title>Example of info callback</title> 3627 <programlisting> 3628 <![CDATA[ 3629 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, 3630 struct snd_ctl_elem_info *uinfo) 3631 { 3632 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; 3633 uinfo->count = 1; 3634 uinfo->value.integer.min = 0; 3635 uinfo->value.integer.max = 1; 3636 return 0; 3637 } 3638 ]]> 3639 </programlisting> 3640 </example> 3641 </para> 3642 3643 <para> 3644 The <structfield>type</structfield> field specifies the type 3645 of the control. There are <constant>BOOLEAN</constant>, 3646 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>, 3647 <constant>BYTES</constant>, <constant>IEC958</constant> and 3648 <constant>INTEGER64</constant>. The 3649 <structfield>count</structfield> field specifies the 3650 number of elements in this control. For example, a stereo 3651 volume would have count = 2. The 3652 <structfield>value</structfield> field is a union, and 3653 the values stored are depending on the type. The boolean and 3654 integer types are identical. 3655 </para> 3656 3657 <para> 3658 The enumerated type is a bit different from others. You'll 3659 need to set the string for the currently given item index. 3660 3661 <informalexample> 3662 <programlisting> 3663 <![CDATA[ 3664 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 3665 struct snd_ctl_elem_info *uinfo) 3666 { 3667 static char *texts[4] = { 3668 "First", "Second", "Third", "Fourth" 3669 }; 3670 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; 3671 uinfo->count = 1; 3672 uinfo->value.enumerated.items = 4; 3673 if (uinfo->value.enumerated.item > 3) 3674 uinfo->value.enumerated.item = 3; 3675 strcpy(uinfo->value.enumerated.name, 3676 texts[uinfo->value.enumerated.item]); 3677 return 0; 3678 } 3679 ]]> 3680 </programlisting> 3681 </informalexample> 3682 </para> 3683 3684 <para> 3685 Some common info callbacks are available for your convenience: 3686 <function>snd_ctl_boolean_mono_info()</function> and 3687 <function>snd_ctl_boolean_stereo_info()</function>. 3688 Obviously, the former is an info callback for a mono channel 3689 boolean item, just like <function>snd_myctl_mono_info</function> 3690 above, and the latter is for a stereo channel boolean item. 3691 </para> 3692 3693 </section> 3694 3695 <section id="control-interface-callbacks-get"> 3696 <title>get callback</title> 3697 3698 <para> 3699 This callback is used to read the current value of the 3700 control and to return to user-space. 3701 </para> 3702 3703 <para> 3704 For example, 3705 3706 <example> 3707 <title>Example of get callback</title> 3708 <programlisting> 3709 <![CDATA[ 3710 static int snd_myctl_get(struct snd_kcontrol *kcontrol, 3711 struct snd_ctl_elem_value *ucontrol) 3712 { 3713 struct mychip *chip = snd_kcontrol_chip(kcontrol); 3714 ucontrol->value.integer.value[0] = get_some_value(chip); 3715 return 0; 3716 } 3717 ]]> 3718 </programlisting> 3719 </example> 3720 </para> 3721 3722 <para> 3723 The <structfield>value</structfield> field depends on 3724 the type of control as well as on the info callback. For example, 3725 the sb driver uses this field to store the register offset, 3726 the bit-shift and the bit-mask. The 3727 <structfield>private_value</structfield> field is set as follows: 3728 <informalexample> 3729 <programlisting> 3730 <![CDATA[ 3731 .private_value = reg | (shift << 16) | (mask << 24) 3732 ]]> 3733 </programlisting> 3734 </informalexample> 3735 and is retrieved in callbacks like 3736 <informalexample> 3737 <programlisting> 3738 <![CDATA[ 3739 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, 3740 struct snd_ctl_elem_value *ucontrol) 3741 { 3742 int reg = kcontrol->private_value & 0xff; 3743 int shift = (kcontrol->private_value >> 16) & 0xff; 3744 int mask = (kcontrol->private_value >> 24) & 0xff; 3745 .... 3746 } 3747 ]]> 3748 </programlisting> 3749 </informalexample> 3750 </para> 3751 3752 <para> 3753 In the <structfield>get</structfield> callback, 3754 you have to fill all the elements if the 3755 control has more than one elements, 3756 i.e. <structfield>count</structfield> > 1. 3757 In the example above, we filled only one element 3758 (<structfield>value.integer.value[0]</structfield>) since it's 3759 assumed as <structfield>count</structfield> = 1. 3760 </para> 3761 </section> 3762 3763 <section id="control-interface-callbacks-put"> 3764 <title>put callback</title> 3765 3766 <para> 3767 This callback is used to write a value from user-space. 3768 </para> 3769 3770 <para> 3771 For example, 3772 3773 <example> 3774 <title>Example of put callback</title> 3775 <programlisting> 3776 <![CDATA[ 3777 static int snd_myctl_put(struct snd_kcontrol *kcontrol, 3778 struct snd_ctl_elem_value *ucontrol) 3779 { 3780 struct mychip *chip = snd_kcontrol_chip(kcontrol); 3781 int changed = 0; 3782 if (chip->current_value != 3783 ucontrol->value.integer.value[0]) { 3784 change_current_value(chip, 3785 ucontrol->value.integer.value[0]); 3786 changed = 1; 3787 } 3788 return changed; 3789 } 3790 ]]> 3791 </programlisting> 3792 </example> 3793 3794 As seen above, you have to return 1 if the value is 3795 changed. If the value is not changed, return 0 instead. 3796 If any fatal error happens, return a negative error code as 3797 usual. 3798 </para> 3799 3800 <para> 3801 As in the <structfield>get</structfield> callback, 3802 when the control has more than one elements, 3803 all elements must be evaluated in this callback, too. 3804 </para> 3805 </section> 3806 3807 <section id="control-interface-callbacks-all"> 3808 <title>Callbacks are not atomic</title> 3809 <para> 3810 All these three callbacks are basically not atomic. 3811 </para> 3812 </section> 3813 </section> 3814 3815 <section id="control-interface-constructor"> 3816 <title>Constructor</title> 3817 <para> 3818 When everything is ready, finally we can create a new 3819 control. To create a control, there are two functions to be 3820 called, <function>snd_ctl_new1()</function> and 3821 <function>snd_ctl_add()</function>. 3822 </para> 3823 3824 <para> 3825 In the simplest way, you can do like this: 3826 3827 <informalexample> 3828 <programlisting> 3829 <![CDATA[ 3830 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); 3831 if (err < 0) 3832 return err; 3833 ]]> 3834 </programlisting> 3835 </informalexample> 3836 3837 where <parameter>my_control</parameter> is the 3838 struct <structname>snd_kcontrol_new</structname> object defined above, and chip 3839 is the object pointer to be passed to 3840 kcontrol->private_data 3841 which can be referred to in callbacks. 3842 </para> 3843 3844 <para> 3845 <function>snd_ctl_new1()</function> allocates a new 3846 <structname>snd_kcontrol</structname> instance (that's why the definition 3847 of <parameter>my_control</parameter> can be with 3848 the <parameter>__devinitdata</parameter> 3849 prefix), and <function>snd_ctl_add</function> assigns the given 3850 control component to the card. 3851 </para> 3852 </section> 3853 3854 <section id="control-interface-change-notification"> 3855 <title>Change Notification</title> 3856 <para> 3857 If you need to change and update a control in the interrupt 3858 routine, you can call <function>snd_ctl_notify()</function>. For 3859 example, 3860 3861 <informalexample> 3862 <programlisting> 3863 <![CDATA[ 3864 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); 3865 ]]> 3866 </programlisting> 3867 </informalexample> 3868 3869 This function takes the card pointer, the event-mask, and the 3870 control id pointer for the notification. The event-mask 3871 specifies the types of notification, for example, in the above 3872 example, the change of control values is notified. 3873 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname> 3874 to be notified. 3875 You can find some examples in <filename>es1938.c</filename> or 3876 <filename>es1968.c</filename> for hardware volume interrupts. 3877 </para> 3878 </section> 3879 3880 <section id="control-interface-tlv"> 3881 <title>Metadata</title> 3882 <para> 3883 To provide information about the dB values of a mixer control, use 3884 on of the <constant>DECLARE_TLV_xxx</constant> macros from 3885 <filename><sound/tlv.h></filename> to define a variable 3886 containing this information, set the<structfield>tlv.p 3887 </structfield> field to point to this variable, and include the 3888 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the 3889 <structfield>access</structfield> field; like this: 3890 <informalexample> 3891 <programlisting> 3892 <![CDATA[ 3893 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); 3894 3895 static struct snd_kcontrol_new my_control __devinitdata = { 3896 ... 3897 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | 3898 SNDRV_CTL_ELEM_ACCESS_TLV_READ, 3899 ... 3900 .tlv.p = db_scale_my_control, 3901 }; 3902 ]]> 3903 </programlisting> 3904 </informalexample> 3905 </para> 3906 3907 <para> 3908 The <function>DECLARE_TLV_DB_SCALE</function> macro defines 3909 information about a mixer control where each step in the control's 3910 value changes the dB value by a constant dB amount. 3911 The first parameter is the name of the variable to be defined. 3912 The second parameter is the minimum value, in units of 0.01 dB. 3913 The third parameter is the step size, in units of 0.01 dB. 3914 Set the fourth parameter to 1 if the minimum value actually mutes 3915 the control. 3916 </para> 3917 3918 <para> 3919 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines 3920 information about a mixer control where the control's value affects 3921 the output linearly. 3922 The first parameter is the name of the variable to be defined. 3923 The second parameter is the minimum value, in units of 0.01 dB. 3924 The third parameter is the maximum value, in units of 0.01 dB. 3925 If the minimum value mutes the control, set the second parameter to 3926 <constant>TLV_DB_GAIN_MUTE</constant>. 3927 </para> 3928 </section> 3929 3930 </chapter> 3931 3932 3933 <!-- ****************************************************** --> 3934 <!-- API for AC97 Codec --> 3935 <!-- ****************************************************** --> 3936 <chapter id="api-ac97"> 3937 <title>API for AC97 Codec</title> 3938 3939 <section> 3940 <title>General</title> 3941 <para> 3942 The ALSA AC97 codec layer is a well-defined one, and you don't 3943 have to write much code to control it. Only low-level control 3944 routines are necessary. The AC97 codec API is defined in 3945 <filename><sound/ac97_codec.h></filename>. 3946 </para> 3947 </section> 3948 3949 <section id="api-ac97-example"> 3950 <title>Full Code Example</title> 3951 <para> 3952 <example> 3953 <title>Example of AC97 Interface</title> 3954 <programlisting> 3955 <![CDATA[ 3956 struct mychip { 3957 .... 3958 struct snd_ac97 *ac97; 3959 .... 3960 }; 3961 3962 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 3963 unsigned short reg) 3964 { 3965 struct mychip *chip = ac97->private_data; 3966 .... 3967 /* read a register value here from the codec */ 3968 return the_register_value; 3969 } 3970 3971 static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 3972 unsigned short reg, unsigned short val) 3973 { 3974 struct mychip *chip = ac97->private_data; 3975 .... 3976 /* write the given register value to the codec */ 3977 } 3978 3979 static int snd_mychip_ac97(struct mychip *chip) 3980 { 3981 struct snd_ac97_bus *bus; 3982 struct snd_ac97_template ac97; 3983 int err; 3984 static struct snd_ac97_bus_ops ops = { 3985 .write = snd_mychip_ac97_write, 3986 .read = snd_mychip_ac97_read, 3987 }; 3988 3989 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); 3990 if (err < 0) 3991 return err; 3992 memset(&ac97, 0, sizeof(ac97)); 3993 ac97.private_data = chip; 3994 return snd_ac97_mixer(bus, &ac97, &chip->ac97); 3995 } 3996 3997 ]]> 3998 </programlisting> 3999 </example> 4000 </para> 4001 </section> 4002 4003 <section id="api-ac97-constructor"> 4004 <title>Constructor</title> 4005 <para> 4006 To create an ac97 instance, first call <function>snd_ac97_bus</function> 4007 with an <type>ac97_bus_ops_t</type> record with callback functions. 4008 4009 <informalexample> 4010 <programlisting> 4011 <![CDATA[ 4012 struct snd_ac97_bus *bus; 4013 static struct snd_ac97_bus_ops ops = { 4014 .write = snd_mychip_ac97_write, 4015 .read = snd_mychip_ac97_read, 4016 }; 4017 4018 snd_ac97_bus(card, 0, &ops, NULL, &pbus); 4019 ]]> 4020 </programlisting> 4021 </informalexample> 4022 4023 The bus record is shared among all belonging ac97 instances. 4024 </para> 4025 4026 <para> 4027 And then call <function>snd_ac97_mixer()</function> with an 4028 struct <structname>snd_ac97_template</structname> 4029 record together with the bus pointer created above. 4030 4031 <informalexample> 4032 <programlisting> 4033 <![CDATA[ 4034 struct snd_ac97_template ac97; 4035 int err; 4036 4037 memset(&ac97, 0, sizeof(ac97)); 4038 ac97.private_data = chip; 4039 snd_ac97_mixer(bus, &ac97, &chip->ac97); 4040 ]]> 4041 </programlisting> 4042 </informalexample> 4043 4044 where chip->ac97 is a pointer to a newly created 4045 <type>ac97_t</type> instance. 4046 In this case, the chip pointer is set as the private data, so that 4047 the read/write callback functions can refer to this chip instance. 4048 This instance is not necessarily stored in the chip 4049 record. If you need to change the register values from the 4050 driver, or need the suspend/resume of ac97 codecs, keep this 4051 pointer to pass to the corresponding functions. 4052 </para> 4053 </section> 4054 4055 <section id="api-ac97-callbacks"> 4056 <title>Callbacks</title> 4057 <para> 4058 The standard callbacks are <structfield>read</structfield> and 4059 <structfield>write</structfield>. Obviously they 4060 correspond to the functions for read and write accesses to the 4061 hardware low-level codes. 4062 </para> 4063 4064 <para> 4065 The <structfield>read</structfield> callback returns the 4066 register value specified in the argument. 4067 4068 <informalexample> 4069 <programlisting> 4070 <![CDATA[ 4071 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 4072 unsigned short reg) 4073 { 4074 struct mychip *chip = ac97->private_data; 4075 .... 4076 return the_register_value; 4077 } 4078 ]]> 4079 </programlisting> 4080 </informalexample> 4081 4082 Here, the chip can be cast from ac97->private_data. 4083 </para> 4084 4085 <para> 4086 Meanwhile, the <structfield>write</structfield> callback is 4087 used to set the register value. 4088 4089 <informalexample> 4090 <programlisting> 4091 <![CDATA[ 4092 static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 4093 unsigned short reg, unsigned short val) 4094 ]]> 4095 </programlisting> 4096 </informalexample> 4097 </para> 4098 4099 <para> 4100 These callbacks are non-atomic like the control API callbacks. 4101 </para> 4102 4103 <para> 4104 There are also other callbacks: 4105 <structfield>reset</structfield>, 4106 <structfield>wait</structfield> and 4107 <structfield>init</structfield>. 4108 </para> 4109 4110 <para> 4111 The <structfield>reset</structfield> callback is used to reset 4112 the codec. If the chip requires a special kind of reset, you can 4113 define this callback. 4114 </para> 4115 4116 <para> 4117 The <structfield>wait</structfield> callback is used to 4118 add some waiting time in the standard initialization of the codec. If the 4119 chip requires the extra waiting time, define this callback. 4120 </para> 4121 4122 <para> 4123 The <structfield>init</structfield> callback is used for 4124 additional initialization of the codec. 4125 </para> 4126 </section> 4127 4128 <section id="api-ac97-updating-registers"> 4129 <title>Updating Registers in The Driver</title> 4130 <para> 4131 If you need to access to the codec from the driver, you can 4132 call the following functions: 4133 <function>snd_ac97_write()</function>, 4134 <function>snd_ac97_read()</function>, 4135 <function>snd_ac97_update()</function> and 4136 <function>snd_ac97_update_bits()</function>. 4137 </para> 4138 4139 <para> 4140 Both <function>snd_ac97_write()</function> and 4141 <function>snd_ac97_update()</function> functions are used to 4142 set a value to the given register 4143 (<constant>AC97_XXX</constant>). The difference between them is 4144 that <function>snd_ac97_update()</function> doesn't write a 4145 value if the given value has been already set, while 4146 <function>snd_ac97_write()</function> always rewrites the 4147 value. 4148 4149 <informalexample> 4150 <programlisting> 4151 <![CDATA[ 4152 snd_ac97_write(ac97, AC97_MASTER, 0x8080); 4153 snd_ac97_update(ac97, AC97_MASTER, 0x8080); 4154 ]]> 4155 </programlisting> 4156 </informalexample> 4157 </para> 4158 4159 <para> 4160 <function>snd_ac97_read()</function> is used to read the value 4161 of the given register. For example, 4162 4163 <informalexample> 4164 <programlisting> 4165 <![CDATA[ 4166 value = snd_ac97_read(ac97, AC97_MASTER); 4167 ]]> 4168 </programlisting> 4169 </informalexample> 4170 </para> 4171 4172 <para> 4173 <function>snd_ac97_update_bits()</function> is used to update 4174 some bits in the given register. 4175 4176 <informalexample> 4177 <programlisting> 4178 <![CDATA[ 4179 snd_ac97_update_bits(ac97, reg, mask, value); 4180 ]]> 4181 </programlisting> 4182 </informalexample> 4183 </para> 4184 4185 <para> 4186 Also, there is a function to change the sample rate (of a 4187 given register such as 4188 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or 4189 DRA is supported by the codec: 4190 <function>snd_ac97_set_rate()</function>. 4191 4192 <informalexample> 4193 <programlisting> 4194 <![CDATA[ 4195 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); 4196 ]]> 4197 </programlisting> 4198 </informalexample> 4199 </para> 4200 4201 <para> 4202 The following registers are available to set the rate: 4203 <constant>AC97_PCM_MIC_ADC_RATE</constant>, 4204 <constant>AC97_PCM_FRONT_DAC_RATE</constant>, 4205 <constant>AC97_PCM_LR_ADC_RATE</constant>, 4206 <constant>AC97_SPDIF</constant>. When 4207 <constant>AC97_SPDIF</constant> is specified, the register is 4208 not really changed but the corresponding IEC958 status bits will 4209 be updated. 4210 </para> 4211 </section> 4212 4213 <section id="api-ac97-clock-adjustment"> 4214 <title>Clock Adjustment</title> 4215 <para> 4216 In some chips, the clock of the codec isn't 48000 but using a 4217 PCI clock (to save a quartz!). In this case, change the field 4218 bus->clock to the corresponding 4219 value. For example, intel8x0 4220 and es1968 drivers have their own function to read from the clock. 4221 </para> 4222 </section> 4223 4224 <section id="api-ac97-proc-files"> 4225 <title>Proc Files</title> 4226 <para> 4227 The ALSA AC97 interface will create a proc file such as 4228 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and 4229 <filename>ac97#0-0+regs</filename>. You can refer to these files to 4230 see the current status and registers of the codec. 4231 </para> 4232 </section> 4233 4234 <section id="api-ac97-multiple-codecs"> 4235 <title>Multiple Codecs</title> 4236 <para> 4237 When there are several codecs on the same card, you need to 4238 call <function>snd_ac97_mixer()</function> multiple times with 4239 ac97.num=1 or greater. The <structfield>num</structfield> field 4240 specifies the codec number. 4241 </para> 4242 4243 <para> 4244 If you set up multiple codecs, you either need to write 4245 different callbacks for each codec or check 4246 ac97->num in the callback routines. 4247 </para> 4248 </section> 4249 4250 </chapter> 4251 4252 4253 <!-- ****************************************************** --> 4254 <!-- MIDI (MPU401-UART) Interface --> 4255 <!-- ****************************************************** --> 4256 <chapter id="midi-interface"> 4257 <title>MIDI (MPU401-UART) Interface</title> 4258 4259 <section id="midi-interface-general"> 4260 <title>General</title> 4261 <para> 4262 Many soundcards have built-in MIDI (MPU401-UART) 4263 interfaces. When the soundcard supports the standard MPU401-UART 4264 interface, most likely you can use the ALSA MPU401-UART API. The 4265 MPU401-UART API is defined in 4266 <filename><sound/mpu401.h></filename>. 4267 </para> 4268 4269 <para> 4270 Some soundchips have a similar but slightly different 4271 implementation of mpu401 stuff. For example, emu10k1 has its own 4272 mpu401 routines. 4273 </para> 4274 </section> 4275 4276 <section id="midi-interface-constructor"> 4277 <title>Constructor</title> 4278 <para> 4279 To create a rawmidi object, call 4280 <function>snd_mpu401_uart_new()</function>. 4281 4282 <informalexample> 4283 <programlisting> 4284 <![CDATA[ 4285 struct snd_rawmidi *rmidi; 4286 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, 4287 irq, irq_flags, &rmidi); 4288 ]]> 4289 </programlisting> 4290 </informalexample> 4291 </para> 4292 4293 <para> 4294 The first argument is the card pointer, and the second is the 4295 index of this component. You can create up to 8 rawmidi 4296 devices. 4297 </para> 4298 4299 <para> 4300 The third argument is the type of the hardware, 4301 <constant>MPU401_HW_XXX</constant>. If it's not a special one, 4302 you can use <constant>MPU401_HW_MPU401</constant>. 4303 </para> 4304 4305 <para> 4306 The 4th argument is the I/O port address. Many 4307 backward-compatible MPU401 have an I/O port such as 0x330. Or, it 4308 might be a part of its own PCI I/O region. It depends on the 4309 chip design. 4310 </para> 4311 4312 <para> 4313 The 5th argument is a bitflag for additional information. 4314 When the I/O port address above is part of the PCI I/O 4315 region, the MPU401 I/O port might have been already allocated 4316 (reserved) by the driver itself. In such a case, pass a bit flag 4317 <constant>MPU401_INFO_INTEGRATED</constant>, 4318 and the mpu401-uart layer will allocate the I/O ports by itself. 4319 </para> 4320 4321 <para> 4322 When the controller supports only the input or output MIDI stream, 4323 pass the <constant>MPU401_INFO_INPUT</constant> or 4324 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. 4325 Then the rawmidi instance is created as a single stream. 4326 </para> 4327 4328 <para> 4329 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change 4330 the access method to MMIO (via readb and writeb) instead of 4331 iob and outb. In this case, you have to pass the iomapped address 4332 to <function>snd_mpu401_uart_new()</function>. 4333 </para> 4334 4335 <para> 4336 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output 4337 stream isn't checked in the default interrupt handler. The driver 4338 needs to call <function>snd_mpu401_uart_interrupt_tx()</function> 4339 by itself to start processing the output stream in the irq handler. 4340 </para> 4341 4342 <para> 4343 Usually, the port address corresponds to the command port and 4344 port + 1 corresponds to the data port. If not, you may change 4345 the <structfield>cport</structfield> field of 4346 struct <structname>snd_mpu401</structname> manually 4347 afterward. However, <structname>snd_mpu401</structname> pointer is not 4348 returned explicitly by 4349 <function>snd_mpu401_uart_new()</function>. You need to cast 4350 rmidi->private_data to 4351 <structname>snd_mpu401</structname> explicitly, 4352 4353 <informalexample> 4354 <programlisting> 4355 <![CDATA[ 4356 struct snd_mpu401 *mpu; 4357 mpu = rmidi->private_data; 4358 ]]> 4359 </programlisting> 4360 </informalexample> 4361 4362 and reset the cport as you like: 4363 4364 <informalexample> 4365 <programlisting> 4366 <![CDATA[ 4367 mpu->cport = my_own_control_port; 4368 ]]> 4369 </programlisting> 4370 </informalexample> 4371 </para> 4372 4373 <para> 4374 The 6th argument specifies the irq number for UART. If the irq 4375 is already allocated, pass 0 to the 7th argument 4376 (<parameter>irq_flags</parameter>). Otherwise, pass the flags 4377 for irq allocation 4378 (<constant>SA_XXX</constant> bits) to it, and the irq will be 4379 reserved by the mpu401-uart layer. If the card doesn't generate 4380 UART interrupts, pass -1 as the irq number. Then a timer 4381 interrupt will be invoked for polling. 4382 </para> 4383 </section> 4384 4385 <section id="midi-interface-interrupt-handler"> 4386 <title>Interrupt Handler</title> 4387 <para> 4388 When the interrupt is allocated in 4389 <function>snd_mpu401_uart_new()</function>, the private 4390 interrupt handler is used, hence you don't have anything else to do 4391 than creating the mpu401 stuff. Otherwise, you have to call 4392 <function>snd_mpu401_uart_interrupt()</function> explicitly when 4393 a UART interrupt is invoked and checked in your own interrupt 4394 handler. 4395 </para> 4396 4397 <para> 4398 In this case, you need to pass the private_data of the 4399 returned rawmidi object from 4400 <function>snd_mpu401_uart_new()</function> as the second 4401 argument of <function>snd_mpu401_uart_interrupt()</function>. 4402 4403 <informalexample> 4404 <programlisting> 4405 <![CDATA[ 4406 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); 4407 ]]> 4408 </programlisting> 4409 </informalexample> 4410 </para> 4411 </section> 4412 4413 </chapter> 4414 4415 4416 <!-- ****************************************************** --> 4417 <!-- RawMIDI Interface --> 4418 <!-- ****************************************************** --> 4419 <chapter id="rawmidi-interface"> 4420 <title>RawMIDI Interface</title> 4421 4422 <section id="rawmidi-interface-overview"> 4423 <title>Overview</title> 4424 4425 <para> 4426 The raw MIDI interface is used for hardware MIDI ports that can 4427 be accessed as a byte stream. It is not used for synthesizer 4428 chips that do not directly understand MIDI. 4429 </para> 4430 4431 <para> 4432 ALSA handles file and buffer management. All you have to do is 4433 to write some code to move data between the buffer and the 4434 hardware. 4435 </para> 4436 4437 <para> 4438 The rawmidi API is defined in 4439 <filename><sound/rawmidi.h></filename>. 4440 </para> 4441 </section> 4442 4443 <section id="rawmidi-interface-constructor"> 4444 <title>Constructor</title> 4445 4446 <para> 4447 To create a rawmidi device, call the 4448 <function>snd_rawmidi_new</function> function: 4449 <informalexample> 4450 <programlisting> 4451 <![CDATA[ 4452 struct snd_rawmidi *rmidi; 4453 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); 4454 if (err < 0) 4455 return err; 4456 rmidi->private_data = chip; 4457 strcpy(rmidi->name, "My MIDI"); 4458 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | 4459 SNDRV_RAWMIDI_INFO_INPUT | 4460 SNDRV_RAWMIDI_INFO_DUPLEX; 4461 ]]> 4462 </programlisting> 4463 </informalexample> 4464 </para> 4465 4466 <para> 4467 The first argument is the card pointer, the second argument is 4468 the ID string. 4469 </para> 4470 4471 <para> 4472 The third argument is the index of this component. You can 4473 create up to 8 rawmidi devices. 4474 </para> 4475 4476 <para> 4477 The fourth and fifth arguments are the number of output and 4478 input substreams, respectively, of this device (a substream is 4479 the equivalent of a MIDI port). 4480 </para> 4481 4482 <para> 4483 Set the <structfield>info_flags</structfield> field to specify 4484 the capabilities of the device. 4485 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is 4486 at least one output port, 4487 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at 4488 least one input port, 4489 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device 4490 can handle output and input at the same time. 4491 </para> 4492 4493 <para> 4494 After the rawmidi device is created, you need to set the 4495 operators (callbacks) for each substream. There are helper 4496 functions to set the operators for all the substreams of a device: 4497 <informalexample> 4498 <programlisting> 4499 <![CDATA[ 4500 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); 4501 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); 4502 ]]> 4503 </programlisting> 4504 </informalexample> 4505 </para> 4506 4507 <para> 4508 The operators are usually defined like this: 4509 <informalexample> 4510 <programlisting> 4511 <![CDATA[ 4512 static struct snd_rawmidi_ops snd_mymidi_output_ops = { 4513 .open = snd_mymidi_output_open, 4514 .close = snd_mymidi_output_close, 4515 .trigger = snd_mymidi_output_trigger, 4516 }; 4517 ]]> 4518 </programlisting> 4519 </informalexample> 4520 These callbacks are explained in the <link 4521 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link> 4522 section. 4523 </para> 4524 4525 <para> 4526 If there are more than one substream, you should give a 4527 unique name to each of them: 4528 <informalexample> 4529 <programlisting> 4530 <![CDATA[ 4531 struct snd_rawmidi_substream *substream; 4532 list_for_each_entry(substream, 4533 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, 4534 list { 4535 sprintf(substream->name, "My MIDI Port %d", substream->number + 1); 4536 } 4537 /* same for SNDRV_RAWMIDI_STREAM_INPUT */ 4538 ]]> 4539 </programlisting> 4540 </informalexample> 4541 </para> 4542 </section> 4543 4544 <section id="rawmidi-interface-callbacks"> 4545 <title>Callbacks</title> 4546 4547 <para> 4548 In all the callbacks, the private data that you've set for the 4549 rawmidi device can be accessed as 4550 substream->rmidi->private_data. 4551 <!-- <code> isn't available before DocBook 4.3 --> 4552 </para> 4553 4554 <para> 4555 If there is more than one port, your callbacks can determine the 4556 port index from the struct snd_rawmidi_substream data passed to each 4557 callback: 4558 <informalexample> 4559 <programlisting> 4560 <![CDATA[ 4561 struct snd_rawmidi_substream *substream; 4562 int index = substream->number; 4563 ]]> 4564 </programlisting> 4565 </informalexample> 4566 </para> 4567 4568 <section id="rawmidi-interface-op-open"> 4569 <title><function>open</function> callback</title> 4570 4571 <informalexample> 4572 <programlisting> 4573 <![CDATA[ 4574 static int snd_xxx_open(struct snd_rawmidi_substream *substream); 4575 ]]> 4576 </programlisting> 4577 </informalexample> 4578 4579 <para> 4580 This is called when a substream is opened. 4581 You can initialize the hardware here, but you shouldn't 4582 start transmitting/receiving data yet. 4583 </para> 4584 </section> 4585 4586 <section id="rawmidi-interface-op-close"> 4587 <title><function>close</function> callback</title> 4588 4589 <informalexample> 4590 <programlisting> 4591 <![CDATA[ 4592 static int snd_xxx_close(struct snd_rawmidi_substream *substream); 4593 ]]> 4594 </programlisting> 4595 </informalexample> 4596 4597 <para> 4598 Guess what. 4599 </para> 4600 4601 <para> 4602 The <function>open</function> and <function>close</function> 4603 callbacks of a rawmidi device are serialized with a mutex, 4604 and can sleep. 4605 </para> 4606 </section> 4607 4608 <section id="rawmidi-interface-op-trigger-out"> 4609 <title><function>trigger</function> callback for output 4610 substreams</title> 4611 4612 <informalexample> 4613 <programlisting> 4614 <![CDATA[ 4615 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); 4616 ]]> 4617 </programlisting> 4618 </informalexample> 4619 4620 <para> 4621 This is called with a nonzero <parameter>up</parameter> 4622 parameter when there is some data in the substream buffer that 4623 must be transmitted. 4624 </para> 4625 4626 <para> 4627 To read data from the buffer, call 4628 <function>snd_rawmidi_transmit_peek</function>. It will 4629 return the number of bytes that have been read; this will be 4630 less than the number of bytes requested when there are no more 4631 data in the buffer. 4632 After the data have been transmitted successfully, call 4633 <function>snd_rawmidi_transmit_ack</function> to remove the 4634 data from the substream buffer: 4635 <informalexample> 4636 <programlisting> 4637 <![CDATA[ 4638 unsigned char data; 4639 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { 4640 if (snd_mychip_try_to_transmit(data)) 4641 snd_rawmidi_transmit_ack(substream, 1); 4642 else 4643 break; /* hardware FIFO full */ 4644 } 4645 ]]> 4646 </programlisting> 4647 </informalexample> 4648 </para> 4649 4650 <para> 4651 If you know beforehand that the hardware will accept data, you 4652 can use the <function>snd_rawmidi_transmit</function> function 4653 which reads some data and removes them from the buffer at once: 4654 <informalexample> 4655 <programlisting> 4656 <![CDATA[ 4657 while (snd_mychip_transmit_possible()) { 4658 unsigned char data; 4659 if (snd_rawmidi_transmit(substream, &data, 1) != 1) 4660 break; /* no more data */ 4661 snd_mychip_transmit(data); 4662 } 4663 ]]> 4664 </programlisting> 4665 </informalexample> 4666 </para> 4667 4668 <para> 4669 If you know beforehand how many bytes you can accept, you can 4670 use a buffer size greater than one with the 4671 <function>snd_rawmidi_transmit*</function> functions. 4672 </para> 4673 4674 <para> 4675 The <function>trigger</function> callback must not sleep. If 4676 the hardware FIFO is full before the substream buffer has been 4677 emptied, you have to continue transmitting data later, either 4678 in an interrupt handler, or with a timer if the hardware 4679 doesn't have a MIDI transmit interrupt. 4680 </para> 4681 4682 <para> 4683 The <function>trigger</function> callback is called with a 4684 zero <parameter>up</parameter> parameter when the transmission 4685 of data should be aborted. 4686 </para> 4687 </section> 4688 4689 <section id="rawmidi-interface-op-trigger-in"> 4690 <title><function>trigger</function> callback for input 4691 substreams</title> 4692 4693 <informalexample> 4694 <programlisting> 4695 <![CDATA[ 4696 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); 4697 ]]> 4698 </programlisting> 4699 </informalexample> 4700 4701 <para> 4702 This is called with a nonzero <parameter>up</parameter> 4703 parameter to enable receiving data, or with a zero 4704 <parameter>up</parameter> parameter do disable receiving data. 4705 </para> 4706 4707 <para> 4708 The <function>trigger</function> callback must not sleep; the 4709 actual reading of data from the device is usually done in an 4710 interrupt handler. 4711 </para> 4712 4713 <para> 4714 When data reception is enabled, your interrupt handler should 4715 call <function>snd_rawmidi_receive</function> for all received 4716 data: 4717 <informalexample> 4718 <programlisting> 4719 <![CDATA[ 4720 void snd_mychip_midi_interrupt(...) 4721 { 4722 while (mychip_midi_available()) { 4723 unsigned char data; 4724 data = mychip_midi_read(); 4725 snd_rawmidi_receive(substream, &data, 1); 4726 } 4727 } 4728 ]]> 4729 </programlisting> 4730 </informalexample> 4731 </para> 4732 </section> 4733 4734 <section id="rawmidi-interface-op-drain"> 4735 <title><function>drain</function> callback</title> 4736 4737 <informalexample> 4738 <programlisting> 4739 <![CDATA[ 4740 static void snd_xxx_drain(struct snd_rawmidi_substream *substream); 4741 ]]> 4742 </programlisting> 4743 </informalexample> 4744 4745 <para> 4746 This is only used with output substreams. This function should wait 4747 until all data read from the substream buffer have been transmitted. 4748 This ensures that the device can be closed and the driver unloaded 4749 without losing data. 4750 </para> 4751 4752 <para> 4753 This callback is optional. If you do not set 4754 <structfield>drain</structfield> in the struct snd_rawmidi_ops 4755 structure, ALSA will simply wait for 50 milliseconds 4756 instead. 4757 </para> 4758 </section> 4759 </section> 4760 4761 </chapter> 4762 4763 4764 <!-- ****************************************************** --> 4765 <!-- Miscellaneous Devices --> 4766 <!-- ****************************************************** --> 4767 <chapter id="misc-devices"> 4768 <title>Miscellaneous Devices</title> 4769 4770 <section id="misc-devices-opl3"> 4771 <title>FM OPL3</title> 4772 <para> 4773 The FM OPL3 is still used in many chips (mainly for backward 4774 compatibility). ALSA has a nice OPL3 FM control layer, too. The 4775 OPL3 API is defined in 4776 <filename><sound/opl3.h></filename>. 4777 </para> 4778 4779 <para> 4780 FM registers can be directly accessed through the direct-FM API, 4781 defined in <filename><sound/asound_fm.h></filename>. In 4782 ALSA native mode, FM registers are accessed through 4783 the Hardware-Dependant Device direct-FM extension API, whereas in 4784 OSS compatible mode, FM registers can be accessed with the OSS 4785 direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 4786 </para> 4787 4788 <para> 4789 To create the OPL3 component, you have two functions to 4790 call. The first one is a constructor for the <type>opl3_t</type> 4791 instance. 4792 4793 <informalexample> 4794 <programlisting> 4795 <![CDATA[ 4796 struct snd_opl3 *opl3; 4797 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, 4798 integrated, &opl3); 4799 ]]> 4800 </programlisting> 4801 </informalexample> 4802 </para> 4803 4804 <para> 4805 The first argument is the card pointer, the second one is the 4806 left port address, and the third is the right port address. In 4807 most cases, the right port is placed at the left port + 2. 4808 </para> 4809 4810 <para> 4811 The fourth argument is the hardware type. 4812 </para> 4813 4814 <para> 4815 When the left and right ports have been already allocated by 4816 the card driver, pass non-zero to the fifth argument 4817 (<parameter>integrated</parameter>). Otherwise, the opl3 module will 4818 allocate the specified ports by itself. 4819 </para> 4820 4821 <para> 4822 When the accessing the hardware requires special method 4823 instead of the standard I/O access, you can create opl3 instance 4824 separately with <function>snd_opl3_new()</function>. 4825 4826 <informalexample> 4827 <programlisting> 4828 <![CDATA[ 4829 struct snd_opl3 *opl3; 4830 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); 4831 ]]> 4832 </programlisting> 4833 </informalexample> 4834 </para> 4835 4836 <para> 4837 Then set <structfield>command</structfield>, 4838 <structfield>private_data</structfield> and 4839 <structfield>private_free</structfield> for the private 4840 access function, the private data and the destructor. 4841 The l_port and r_port are not necessarily set. Only the 4842 command must be set properly. You can retrieve the data 4843 from the opl3->private_data field. 4844 </para> 4845 4846 <para> 4847 After creating the opl3 instance via <function>snd_opl3_new()</function>, 4848 call <function>snd_opl3_init()</function> to initialize the chip to the 4849 proper state. Note that <function>snd_opl3_create()</function> always 4850 calls it internally. 4851 </para> 4852 4853 <para> 4854 If the opl3 instance is created successfully, then create a 4855 hwdep device for this opl3. 4856 4857 <informalexample> 4858 <programlisting> 4859 <![CDATA[ 4860 struct snd_hwdep *opl3hwdep; 4861 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); 4862 ]]> 4863 </programlisting> 4864 </informalexample> 4865 </para> 4866 4867 <para> 4868 The first argument is the <type>opl3_t</type> instance you 4869 created, and the second is the index number, usually 0. 4870 </para> 4871 4872 <para> 4873 The third argument is the index-offset for the sequencer 4874 client assigned to the OPL3 port. When there is an MPU401-UART, 4875 give 1 for here (UART always takes 0). 4876 </para> 4877 </section> 4878 4879 <section id="misc-devices-hardware-dependent"> 4880 <title>Hardware-Dependent Devices</title> 4881 <para> 4882 Some chips need user-space access for special 4883 controls or for loading the micro code. In such a case, you can 4884 create a hwdep (hardware-dependent) device. The hwdep API is 4885 defined in <filename><sound/hwdep.h></filename>. You can 4886 find examples in opl3 driver or 4887 <filename>isa/sb/sb16_csp.c</filename>. 4888 </para> 4889 4890 <para> 4891 The creation of the <type>hwdep</type> instance is done via 4892 <function>snd_hwdep_new()</function>. 4893 4894 <informalexample> 4895 <programlisting> 4896 <![CDATA[ 4897 struct snd_hwdep *hw; 4898 snd_hwdep_new(card, "My HWDEP", 0, &hw); 4899 ]]> 4900 </programlisting> 4901 </informalexample> 4902 4903 where the third argument is the index number. 4904 </para> 4905 4906 <para> 4907 You can then pass any pointer value to the 4908 <parameter>private_data</parameter>. 4909 If you assign a private data, you should define the 4910 destructor, too. The destructor function is set in 4911 the <structfield>private_free</structfield> field. 4912 4913 <informalexample> 4914 <programlisting> 4915 <![CDATA[ 4916 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); 4917 hw->private_data = p; 4918 hw->private_free = mydata_free; 4919 ]]> 4920 </programlisting> 4921 </informalexample> 4922 4923 and the implementation of the destructor would be: 4924 4925 <informalexample> 4926 <programlisting> 4927 <![CDATA[ 4928 static void mydata_free(struct snd_hwdep *hw) 4929 { 4930 struct mydata *p = hw->private_data; 4931 kfree(p); 4932 } 4933 ]]> 4934 </programlisting> 4935 </informalexample> 4936 </para> 4937 4938 <para> 4939 The arbitrary file operations can be defined for this 4940 instance. The file operators are defined in 4941 the <parameter>ops</parameter> table. For example, assume that 4942 this chip needs an ioctl. 4943 4944 <informalexample> 4945 <programlisting> 4946 <![CDATA[ 4947 hw->ops.open = mydata_open; 4948 hw->ops.ioctl = mydata_ioctl; 4949 hw->ops.release = mydata_release; 4950 ]]> 4951 </programlisting> 4952 </informalexample> 4953 4954 And implement the callback functions as you like. 4955 </para> 4956 </section> 4957 4958 <section id="misc-devices-IEC958"> 4959 <title>IEC958 (S/PDIF)</title> 4960 <para> 4961 Usually the controls for IEC958 devices are implemented via 4962 the control interface. There is a macro to compose a name string for 4963 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function> 4964 defined in <filename><include/asound.h></filename>. 4965 </para> 4966 4967 <para> 4968 There are some standard controls for IEC958 status bits. These 4969 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>, 4970 and the size of element is fixed as 4 bytes array 4971 (value.iec958.status[x]). For the <structfield>info</structfield> 4972 callback, you don't specify 4973 the value field for this type (the count field must be set, 4974 though). 4975 </para> 4976 4977 <para> 4978 <quote>IEC958 Playback Con Mask</quote> is used to return the 4979 bit-mask for the IEC958 status bits of consumer mode. Similarly, 4980 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for 4981 professional mode. They are read-only controls, and are defined 4982 as MIXER controls (iface = 4983 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>). 4984 </para> 4985 4986 <para> 4987 Meanwhile, <quote>IEC958 Playback Default</quote> control is 4988 defined for getting and setting the current default IEC958 4989 bits. Note that this one is usually defined as a PCM control 4990 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>), 4991 although in some places it's defined as a MIXER control. 4992 </para> 4993 4994 <para> 4995 In addition, you can define the control switches to 4996 enable/disable or to set the raw bit mode. The implementation 4997 will depend on the chip, but the control should be named as 4998 <quote>IEC958 xxx</quote>, preferably using 4999 the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 5000 </para> 5001 5002 <para> 5003 You can find several cases, for example, 5004 <filename>pci/emu10k1</filename>, 5005 <filename>pci/ice1712</filename>, or 5006 <filename>pci/cmipci.c</filename>. 5007 </para> 5008 </section> 5009 5010 </chapter> 5011 5012 5013 <!-- ****************************************************** --> 5014 <!-- Buffer and Memory Management --> 5015 <!-- ****************************************************** --> 5016 <chapter id="buffer-and-memory"> 5017 <title>Buffer and Memory Management</title> 5018 5019 <section id="buffer-and-memory-buffer-types"> 5020 <title>Buffer Types</title> 5021 <para> 5022 ALSA provides several different buffer allocation functions 5023 depending on the bus and the architecture. All these have a 5024 consistent API. The allocation of physically-contiguous pages is 5025 done via 5026 <function>snd_malloc_xxx_pages()</function> function, where xxx 5027 is the bus type. 5028 </para> 5029 5030 <para> 5031 The allocation of pages with fallback is 5032 <function>snd_malloc_xxx_pages_fallback()</function>. This 5033 function tries to allocate the specified pages but if the pages 5034 are not available, it tries to reduce the page sizes until 5035 enough space is found. 5036 </para> 5037 5038 <para> 5039 The release the pages, call 5040 <function>snd_free_xxx_pages()</function> function. 5041 </para> 5042 5043 <para> 5044 Usually, ALSA drivers try to allocate and reserve 5045 a large contiguous physical space 5046 at the time the module is loaded for the later use. 5047 This is called <quote>pre-allocation</quote>. 5048 As already written, you can call the following function at 5049 pcm instance construction time (in the case of PCI bus). 5050 5051 <informalexample> 5052 <programlisting> 5053 <![CDATA[ 5054 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, 5055 snd_dma_pci_data(pci), size, max); 5056 ]]> 5057 </programlisting> 5058 </informalexample> 5059 5060 where <parameter>size</parameter> is the byte size to be 5061 pre-allocated and the <parameter>max</parameter> is the maximum 5062 size to be changed via the <filename>prealloc</filename> proc file. 5063 The allocator will try to get an area as large as possible 5064 within the given size. 5065 </para> 5066 5067 <para> 5068 The second argument (type) and the third argument (device pointer) 5069 are dependent on the bus. 5070 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function> 5071 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type. 5072 For the continuous buffer unrelated to the bus can be pre-allocated 5073 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the 5074 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, 5075 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to 5076 use. 5077 For the PCI scatter-gather buffers, use 5078 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with 5079 <function>snd_dma_pci_data(pci)</function> 5080 (see the 5081 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers 5082 </citetitle></link> section). 5083 </para> 5084 5085 <para> 5086 Once the buffer is pre-allocated, you can use the 5087 allocator in the <structfield>hw_params</structfield> callback: 5088 5089 <informalexample> 5090 <programlisting> 5091 <![CDATA[ 5092 snd_pcm_lib_malloc_pages(substream, size); 5093 ]]> 5094 </programlisting> 5095 </informalexample> 5096 5097 Note that you have to pre-allocate to use this function. 5098 </para> 5099 </section> 5100 5101 <section id="buffer-and-memory-external-hardware"> 5102 <title>External Hardware Buffers</title> 5103 <para> 5104 Some chips have their own hardware buffers and the DMA 5105 transfer from the host memory is not available. In such a case, 5106 you need to either 1) copy/set the audio data directly to the 5107 external hardware buffer, or 2) make an intermediate buffer and 5108 copy/set the data from it to the external hardware buffer in 5109 interrupts (or in tasklets, preferably). 5110 </para> 5111 5112 <para> 5113 The first case works fine if the external hardware buffer is large 5114 enough. This method doesn't need any extra buffers and thus is 5115 more effective. You need to define the 5116 <structfield>copy</structfield> and 5117 <structfield>silence</structfield> callbacks for 5118 the data transfer. However, there is a drawback: it cannot 5119 be mmapped. The examples are GUS's GF1 PCM or emu8000's 5120 wavetable PCM. 5121 </para> 5122 5123 <para> 5124 The second case allows for mmap on the buffer, although you have 5125 to handle an interrupt or a tasklet to transfer the data 5126 from the intermediate buffer to the hardware buffer. You can find an 5127 example in the vxpocket driver. 5128 </para> 5129 5130 <para> 5131 Another case is when the chip uses a PCI memory-map 5132 region for the buffer instead of the host memory. In this case, 5133 mmap is available only on certain architectures like the Intel one. 5134 In non-mmap mode, the data cannot be transferred as in the normal 5135 way. Thus you need to define the <structfield>copy</structfield> and 5136 <structfield>silence</structfield> callbacks as well, 5137 as in the cases above. The examples are found in 5138 <filename>rme32.c</filename> and <filename>rme96.c</filename>. 5139 </para> 5140 5141 <para> 5142 The implementation of the <structfield>copy</structfield> and 5143 <structfield>silence</structfield> callbacks depends upon 5144 whether the hardware supports interleaved or non-interleaved 5145 samples. The <structfield>copy</structfield> callback is 5146 defined like below, a bit 5147 differently depending whether the direction is playback or 5148 capture: 5149 5150 <informalexample> 5151 <programlisting> 5152 <![CDATA[ 5153 static int playback_copy(struct snd_pcm_substream *substream, int channel, 5154 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); 5155 static int capture_copy(struct snd_pcm_substream *substream, int channel, 5156 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); 5157 ]]> 5158 </programlisting> 5159 </informalexample> 5160 </para> 5161 5162 <para> 5163 In the case of interleaved samples, the second argument 5164 (<parameter>channel</parameter>) is not used. The third argument 5165 (<parameter>pos</parameter>) points the 5166 current position offset in frames. 5167 </para> 5168 5169 <para> 5170 The meaning of the fourth argument is different between 5171 playback and capture. For playback, it holds the source data 5172 pointer, and for capture, it's the destination data pointer. 5173 </para> 5174 5175 <para> 5176 The last argument is the number of frames to be copied. 5177 </para> 5178 5179 <para> 5180 What you have to do in this callback is again different 5181 between playback and capture directions. In the 5182 playback case, you copy the given amount of data 5183 (<parameter>count</parameter>) at the specified pointer 5184 (<parameter>src</parameter>) to the specified offset 5185 (<parameter>pos</parameter>) on the hardware buffer. When 5186 coded like memcpy-like way, the copy would be like: 5187 5188 <informalexample> 5189 <programlisting> 5190 <![CDATA[ 5191 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, 5192 frames_to_bytes(runtime, count)); 5193 ]]> 5194 </programlisting> 5195 </informalexample> 5196 </para> 5197 5198 <para> 5199 For the capture direction, you copy the given amount of 5200 data (<parameter>count</parameter>) at the specified offset 5201 (<parameter>pos</parameter>) on the hardware buffer to the 5202 specified pointer (<parameter>dst</parameter>). 5203 5204 <informalexample> 5205 <programlisting> 5206 <![CDATA[ 5207 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), 5208 frames_to_bytes(runtime, count)); 5209 ]]> 5210 </programlisting> 5211 </informalexample> 5212 5213 Note that both the position and the amount of data are given 5214 in frames. 5215 </para> 5216 5217 <para> 5218 In the case of non-interleaved samples, the implementation 5219 will be a bit more complicated. 5220 </para> 5221 5222 <para> 5223 You need to check the channel argument, and if it's -1, copy 5224 the whole channels. Otherwise, you have to copy only the 5225 specified channel. Please check 5226 <filename>isa/gus/gus_pcm.c</filename> as an example. 5227 </para> 5228 5229 <para> 5230 The <structfield>silence</structfield> callback is also 5231 implemented in a similar way. 5232 5233 <informalexample> 5234 <programlisting> 5235 <![CDATA[ 5236 static int silence(struct snd_pcm_substream *substream, int channel, 5237 snd_pcm_uframes_t pos, snd_pcm_uframes_t count); 5238 ]]> 5239 </programlisting> 5240 </informalexample> 5241 </para> 5242 5243 <para> 5244 The meanings of arguments are the same as in the 5245 <structfield>copy</structfield> 5246 callback, although there is no <parameter>src/dst</parameter> 5247 argument. In the case of interleaved samples, the channel 5248 argument has no meaning, as well as on 5249 <structfield>copy</structfield> callback. 5250 </para> 5251 5252 <para> 5253 The role of <structfield>silence</structfield> callback is to 5254 set the given amount 5255 (<parameter>count</parameter>) of silence data at the 5256 specified offset (<parameter>pos</parameter>) on the hardware 5257 buffer. Suppose that the data format is signed (that is, the 5258 silent-data is 0), and the implementation using a memset-like 5259 function would be like: 5260 5261 <informalexample> 5262 <programlisting> 5263 <![CDATA[ 5264 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, 5265 frames_to_bytes(runtime, count)); 5266 ]]> 5267 </programlisting> 5268 </informalexample> 5269 </para> 5270 5271 <para> 5272 In the case of non-interleaved samples, again, the 5273 implementation becomes a bit more complicated. See, for example, 5274 <filename>isa/gus/gus_pcm.c</filename>. 5275 </para> 5276 </section> 5277 5278 <section id="buffer-and-memory-non-contiguous"> 5279 <title>Non-Contiguous Buffers</title> 5280 <para> 5281 If your hardware supports the page table as in emu10k1 or the 5282 buffer descriptors as in via82xx, you can use the scatter-gather 5283 (SG) DMA. ALSA provides an interface for handling SG-buffers. 5284 The API is provided in <filename><sound/pcm.h></filename>. 5285 </para> 5286 5287 <para> 5288 For creating the SG-buffer handler, call 5289 <function>snd_pcm_lib_preallocate_pages()</function> or 5290 <function>snd_pcm_lib_preallocate_pages_for_all()</function> 5291 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant> 5292 in the PCM constructor like other PCI pre-allocator. 5293 You need to pass <function>snd_dma_pci_data(pci)</function>, 5294 where pci is the struct <structname>pci_dev</structname> pointer 5295 of the chip as well. 5296 The <type>struct snd_sg_buf</type> instance is created as 5297 substream->dma_private. You can cast 5298 the pointer like: 5299 5300 <informalexample> 5301 <programlisting> 5302 <![CDATA[ 5303 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; 5304 ]]> 5305 </programlisting> 5306 </informalexample> 5307 </para> 5308 5309 <para> 5310 Then call <function>snd_pcm_lib_malloc_pages()</function> 5311 in the <structfield>hw_params</structfield> callback 5312 as well as in the case of normal PCI buffer. 5313 The SG-buffer handler will allocate the non-contiguous kernel 5314 pages of the given size and map them onto the virtually contiguous 5315 memory. The virtual pointer is addressed in runtime->dma_area. 5316 The physical address (runtime->dma_addr) is set to zero, 5317 because the buffer is physically non-contigous. 5318 The physical address table is set up in sgbuf->table. 5319 You can get the physical address at a certain offset via 5320 <function>snd_pcm_sgbuf_get_addr()</function>. 5321 </para> 5322 5323 <para> 5324 When a SG-handler is used, you need to set 5325 <function>snd_pcm_sgbuf_ops_page</function> as 5326 the <structfield>page</structfield> callback. 5327 (See <link linkend="pcm-interface-operators-page-callback"> 5328 <citetitle>page callback section</citetitle></link>.) 5329 </para> 5330 5331 <para> 5332 To release the data, call 5333 <function>snd_pcm_lib_free_pages()</function> in the 5334 <structfield>hw_free</structfield> callback as usual. 5335 </para> 5336 </section> 5337 5338 <section id="buffer-and-memory-vmalloced"> 5339 <title>Vmalloc'ed Buffers</title> 5340 <para> 5341 It's possible to use a buffer allocated via 5342 <function>vmalloc</function>, for example, for an intermediate 5343 buffer. Since the allocated pages are not contiguous, you need 5344 to set the <structfield>page</structfield> callback to obtain 5345 the physical address at every offset. 5346 </para> 5347 5348 <para> 5349 The implementation of <structfield>page</structfield> callback 5350 would be like this: 5351 5352 <informalexample> 5353 <programlisting> 5354 <![CDATA[ 5355 #include <linux/vmalloc.h> 5356 5357 /* get the physical page pointer on the given offset */ 5358 static struct page *mychip_page(struct snd_pcm_substream *substream, 5359 unsigned long offset) 5360 { 5361 void *pageptr = substream->runtime->dma_area + offset; 5362 return vmalloc_to_page(pageptr); 5363 } 5364 ]]> 5365 </programlisting> 5366 </informalexample> 5367 </para> 5368 </section> 5369 5370 </chapter> 5371 5372 5373 <!-- ****************************************************** --> 5374 <!-- Proc Interface --> 5375 <!-- ****************************************************** --> 5376 <chapter id="proc-interface"> 5377 <title>Proc Interface</title> 5378 <para> 5379 ALSA provides an easy interface for procfs. The proc files are 5380 very useful for debugging. I recommend you set up proc files if 5381 you write a driver and want to get a running status or register 5382 dumps. The API is found in 5383 <filename><sound/info.h></filename>. 5384 </para> 5385 5386 <para> 5387 To create a proc file, call 5388 <function>snd_card_proc_new()</function>. 5389 5390 <informalexample> 5391 <programlisting> 5392 <![CDATA[ 5393 struct snd_info_entry *entry; 5394 int err = snd_card_proc_new(card, "my-file", &entry); 5395 ]]> 5396 </programlisting> 5397 </informalexample> 5398 5399 where the second argument specifies the name of the proc file to be 5400 created. The above example will create a file 5401 <filename>my-file</filename> under the card directory, 5402 e.g. <filename>/proc/asound/card0/my-file</filename>. 5403 </para> 5404 5405 <para> 5406 Like other components, the proc entry created via 5407 <function>snd_card_proc_new()</function> will be registered and 5408 released automatically in the card registration and release 5409 functions. 5410 </para> 5411 5412 <para> 5413 When the creation is successful, the function stores a new 5414 instance in the pointer given in the third argument. 5415 It is initialized as a text proc file for read only. To use 5416 this proc file as a read-only text file as it is, set the read 5417 callback with a private data via 5418 <function>snd_info_set_text_ops()</function>. 5419 5420 <informalexample> 5421 <programlisting> 5422 <![CDATA[ 5423 snd_info_set_text_ops(entry, chip, my_proc_read); 5424 ]]> 5425 </programlisting> 5426 </informalexample> 5427 5428 where the second argument (<parameter>chip</parameter>) is the 5429 private data to be used in the callbacks. The third parameter 5430 specifies the read buffer size and the fourth 5431 (<parameter>my_proc_read</parameter>) is the callback function, which 5432 is defined like 5433 5434 <informalexample> 5435 <programlisting> 5436 <![CDATA[ 5437 static void my_proc_read(struct snd_info_entry *entry, 5438 struct snd_info_buffer *buffer); 5439 ]]> 5440 </programlisting> 5441 </informalexample> 5442 5443 </para> 5444 5445 <para> 5446 In the read callback, use <function>snd_iprintf()</function> for 5447 output strings, which works just like normal 5448 <function>printf()</function>. For example, 5449 5450 <informalexample> 5451 <programlisting> 5452 <![CDATA[ 5453 static void my_proc_read(struct snd_info_entry *entry, 5454 struct snd_info_buffer *buffer) 5455 { 5456 struct my_chip *chip = entry->private_data; 5457 5458 snd_iprintf(buffer, "This is my chip!\n"); 5459 snd_iprintf(buffer, "Port = %ld\n", chip->port); 5460 } 5461 ]]> 5462 </programlisting> 5463 </informalexample> 5464 </para> 5465 5466 <para> 5467 The file permissions can be changed afterwards. As default, it's 5468 set as read only for all users. If you want to add write 5469 permission for the user (root as default), do as follows: 5470 5471 <informalexample> 5472 <programlisting> 5473 <![CDATA[ 5474 entry->mode = S_IFREG | S_IRUGO | S_IWUSR; 5475 ]]> 5476 </programlisting> 5477 </informalexample> 5478 5479 and set the write buffer size and the callback 5480 5481 <informalexample> 5482 <programlisting> 5483 <![CDATA[ 5484 entry->c.text.write = my_proc_write; 5485 ]]> 5486 </programlisting> 5487 </informalexample> 5488 </para> 5489 5490 <para> 5491 For the write callback, you can use 5492 <function>snd_info_get_line()</function> to get a text line, and 5493 <function>snd_info_get_str()</function> to retrieve a string from 5494 the line. Some examples are found in 5495 <filename>core/oss/mixer_oss.c</filename>, core/oss/and 5496 <filename>pcm_oss.c</filename>. 5497 </para> 5498 5499 <para> 5500 For a raw-data proc-file, set the attributes as follows: 5501 5502 <informalexample> 5503 <programlisting> 5504 <![CDATA[ 5505 static struct snd_info_entry_ops my_file_io_ops = { 5506 .read = my_file_io_read, 5507 }; 5508 5509 entry->content = SNDRV_INFO_CONTENT_DATA; 5510 entry->private_data = chip; 5511 entry->c.ops = &my_file_io_ops; 5512 entry->size = 4096; 5513 entry->mode = S_IFREG | S_IRUGO; 5514 ]]> 5515 </programlisting> 5516 </informalexample> 5517 </para> 5518 5519 <para> 5520 The callback is much more complicated than the text-file 5521 version. You need to use a low-level I/O functions such as 5522 <function>copy_from/to_user()</function> to transfer the 5523 data. 5524 5525 <informalexample> 5526 <programlisting> 5527 <![CDATA[ 5528 static long my_file_io_read(struct snd_info_entry *entry, 5529 void *file_private_data, 5530 struct file *file, 5531 char *buf, 5532 unsigned long count, 5533 unsigned long pos) 5534 { 5535 long size = count; 5536 if (pos + size > local_max_size) 5537 size = local_max_size - pos; 5538 if (copy_to_user(buf, local_data + pos, size)) 5539 return -EFAULT; 5540 return size; 5541 } 5542 ]]> 5543 </programlisting> 5544 </informalexample> 5545 </para> 5546 5547 </chapter> 5548 5549 5550 <!-- ****************************************************** --> 5551 <!-- Power Management --> 5552 <!-- ****************************************************** --> 5553 <chapter id="power-management"> 5554 <title>Power Management</title> 5555 <para> 5556 If the chip is supposed to work with suspend/resume 5557 functions, you need to add power-management code to the 5558 driver. The additional code for power-management should be 5559 <function>ifdef</function>'ed with 5560 <constant>CONFIG_PM</constant>. 5561 </para> 5562 5563 <para> 5564 If the driver <emphasis>fully</emphasis> supports suspend/resume 5565 that is, the device can be 5566 properly resumed to its state when suspend was called, 5567 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag 5568 in the pcm info field. Usually, this is possible when the 5569 registers of the chip can be safely saved and restored to 5570 RAM. If this is set, the trigger callback is called with 5571 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume 5572 callback completes. 5573 </para> 5574 5575 <para> 5576 Even if the driver doesn't support PM fully but 5577 partial suspend/resume is still possible, it's still worthy to 5578 implement suspend/resume callbacks. In such a case, applications 5579 would reset the status by calling 5580 <function>snd_pcm_prepare()</function> and restart the stream 5581 appropriately. Hence, you can define suspend/resume callbacks 5582 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant> 5583 info flag to the PCM. 5584 </para> 5585 5586 <para> 5587 Note that the trigger with SUSPEND can always be called when 5588 <function>snd_pcm_suspend_all</function> is called, 5589 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag. 5590 The <constant>RESUME</constant> flag affects only the behavior 5591 of <function>snd_pcm_resume()</function>. 5592 (Thus, in theory, 5593 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed 5594 to be handled in the trigger callback when no 5595 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, 5596 it's better to keep it for compatibility reasons.) 5597 </para> 5598 <para> 5599 In the earlier version of ALSA drivers, a common 5600 power-management layer was provided, but it has been removed. 5601 The driver needs to define the suspend/resume hooks according to 5602 the bus the device is connected to. In the case of PCI drivers, the 5603 callbacks look like below: 5604 5605 <informalexample> 5606 <programlisting> 5607 <![CDATA[ 5608 #ifdef CONFIG_PM 5609 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) 5610 { 5611 .... /* do things for suspend */ 5612 return 0; 5613 } 5614 static int snd_my_resume(struct pci_dev *pci) 5615 { 5616 .... /* do things for suspend */ 5617 return 0; 5618 } 5619 #endif 5620 ]]> 5621 </programlisting> 5622 </informalexample> 5623 </para> 5624 5625 <para> 5626 The scheme of the real suspend job is as follows. 5627 5628 <orderedlist> 5629 <listitem><para>Retrieve the card and the chip data.</para></listitem> 5630 <listitem><para>Call <function>snd_power_change_state()</function> with 5631 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the 5632 power status.</para></listitem> 5633 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> 5634 <listitem><para>If AC97 codecs are used, call 5635 <function>snd_ac97_suspend()</function> for each codec.</para></listitem> 5636 <listitem><para>Save the register values if necessary.</para></listitem> 5637 <listitem><para>Stop the hardware if necessary.</para></listitem> 5638 <listitem><para>Disable the PCI device by calling 5639 <function>pci_disable_device()</function>. Then, call 5640 <function>pci_save_state()</function> at last.</para></listitem> 5641 </orderedlist> 5642 </para> 5643 5644 <para> 5645 A typical code would be like: 5646 5647 <informalexample> 5648 <programlisting> 5649 <![CDATA[ 5650 static int mychip_suspend(struct pci_dev *pci, pm_message_t state) 5651 { 5652 /* (1) */ 5653 struct snd_card *card = pci_get_drvdata(pci); 5654 struct mychip *chip = card->private_data; 5655 /* (2) */ 5656 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); 5657 /* (3) */ 5658 snd_pcm_suspend_all(chip->pcm); 5659 /* (4) */ 5660 snd_ac97_suspend(chip->ac97); 5661 /* (5) */ 5662 snd_mychip_save_registers(chip); 5663 /* (6) */ 5664 snd_mychip_stop_hardware(chip); 5665 /* (7) */ 5666 pci_disable_device(pci); 5667 pci_save_state(pci); 5668 return 0; 5669 } 5670 ]]> 5671 </programlisting> 5672 </informalexample> 5673 </para> 5674 5675 <para> 5676 The scheme of the real resume job is as follows. 5677 5678 <orderedlist> 5679 <listitem><para>Retrieve the card and the chip data.</para></listitem> 5680 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. 5681 Then enable the pci device again by calling <function>pci_enable_device()</function>. 5682 Call <function>pci_set_master()</function> if necessary, too.</para></listitem> 5683 <listitem><para>Re-initialize the chip.</para></listitem> 5684 <listitem><para>Restore the saved registers if necessary.</para></listitem> 5685 <listitem><para>Resume the mixer, e.g. calling 5686 <function>snd_ac97_resume()</function>.</para></listitem> 5687 <listitem><para>Restart the hardware (if any).</para></listitem> 5688 <listitem><para>Call <function>snd_power_change_state()</function> with 5689 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem> 5690 </orderedlist> 5691 </para> 5692 5693 <para> 5694 A typical code would be like: 5695 5696 <informalexample> 5697 <programlisting> 5698 <![CDATA[ 5699 static int mychip_resume(struct pci_dev *pci) 5700 { 5701 /* (1) */ 5702 struct snd_card *card = pci_get_drvdata(pci); 5703 struct mychip *chip = card->private_data; 5704 /* (2) */ 5705 pci_restore_state(pci); 5706 pci_enable_device(pci); 5707 pci_set_master(pci); 5708 /* (3) */ 5709 snd_mychip_reinit_chip(chip); 5710 /* (4) */ 5711 snd_mychip_restore_registers(chip); 5712 /* (5) */ 5713 snd_ac97_resume(chip->ac97); 5714 /* (6) */ 5715 snd_mychip_restart_chip(chip); 5716 /* (7) */ 5717 snd_power_change_state(card, SNDRV_CTL_POWER_D0); 5718 return 0; 5719 } 5720 ]]> 5721 </programlisting> 5722 </informalexample> 5723 </para> 5724 5725 <para> 5726 As shown in the above, it's better to save registers after 5727 suspending the PCM operations via 5728 <function>snd_pcm_suspend_all()</function> or 5729 <function>snd_pcm_suspend()</function>. It means that the PCM 5730 streams are already stoppped when the register snapshot is 5731 taken. But, remember that you don't have to restart the PCM 5732 stream in the resume callback. It'll be restarted via 5733 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> 5734 when necessary. 5735 </para> 5736 5737 <para> 5738 OK, we have all callbacks now. Let's set them up. In the 5739 initialization of the card, make sure that you can get the chip 5740 data from the card instance, typically via 5741 <structfield>private_data</structfield> field, in case you 5742 created the chip data individually. 5743 5744 <informalexample> 5745 <programlisting> 5746 <![CDATA[ 5747 static int __devinit snd_mychip_probe(struct pci_dev *pci, 5748 const struct pci_device_id *pci_id) 5749 { 5750 .... 5751 struct snd_card *card; 5752 struct mychip *chip; 5753 .... 5754 card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL); 5755 .... 5756 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 5757 .... 5758 card->private_data = chip; 5759 .... 5760 } 5761 ]]> 5762 </programlisting> 5763 </informalexample> 5764 5765 When you created the chip data with 5766 <function>snd_card_new()</function>, it's anyway accessible 5767 via <structfield>private_data</structfield> field. 5768 5769 <informalexample> 5770 <programlisting> 5771 <![CDATA[ 5772 static int __devinit snd_mychip_probe(struct pci_dev *pci, 5773 const struct pci_device_id *pci_id) 5774 { 5775 .... 5776 struct snd_card *card; 5777 struct mychip *chip; 5778 .... 5779 card = snd_card_new(index[dev], id[dev], THIS_MODULE, 5780 sizeof(struct mychip)); 5781 .... 5782 chip = card->private_data; 5783 .... 5784 } 5785 ]]> 5786 </programlisting> 5787 </informalexample> 5788 5789 </para> 5790 5791 <para> 5792 If you need a space to save the registers, allocate the 5793 buffer for it here, too, since it would be fatal 5794 if you cannot allocate a memory in the suspend phase. 5795 The allocated buffer should be released in the corresponding 5796 destructor. 5797 </para> 5798 5799 <para> 5800 And next, set suspend/resume callbacks to the pci_driver. 5801 5802 <informalexample> 5803 <programlisting> 5804 <![CDATA[ 5805 static struct pci_driver driver = { 5806 .name = "My Chip", 5807 .id_table = snd_my_ids, 5808 .probe = snd_my_probe, 5809 .remove = __devexit_p(snd_my_remove), 5810 #ifdef CONFIG_PM 5811 .suspend = snd_my_suspend, 5812 .resume = snd_my_resume, 5813 #endif 5814 }; 5815 ]]> 5816 </programlisting> 5817 </informalexample> 5818 </para> 5819 5820 </chapter> 5821 5822 5823 <!-- ****************************************************** --> 5824 <!-- Module Parameters --> 5825 <!-- ****************************************************** --> 5826 <chapter id="module-parameters"> 5827 <title>Module Parameters</title> 5828 <para> 5829 There are standard module options for ALSA. At least, each 5830 module should have the <parameter>index</parameter>, 5831 <parameter>id</parameter> and <parameter>enable</parameter> 5832 options. 5833 </para> 5834 5835 <para> 5836 If the module supports multiple cards (usually up to 5837 8 = <constant>SNDRV_CARDS</constant> cards), they should be 5838 arrays. The default initial values are defined already as 5839 constants for easier programming: 5840 5841 <informalexample> 5842 <programlisting> 5843 <![CDATA[ 5844 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 5845 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 5846 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 5847 ]]> 5848 </programlisting> 5849 </informalexample> 5850 </para> 5851 5852 <para> 5853 If the module supports only a single card, they could be single 5854 variables, instead. <parameter>enable</parameter> option is not 5855 always necessary in this case, but it would be better to have a 5856 dummy option for compatibility. 5857 </para> 5858 5859 <para> 5860 The module parameters must be declared with the standard 5861 <function>module_param()()</function>, 5862 <function>module_param_array()()</function> and 5863 <function>MODULE_PARM_DESC()</function> macros. 5864 </para> 5865 5866 <para> 5867 The typical coding would be like below: 5868 5869 <informalexample> 5870 <programlisting> 5871 <![CDATA[ 5872 #define CARD_NAME "My Chip" 5873 5874 module_param_array(index, int, NULL, 0444); 5875 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); 5876 module_param_array(id, charp, NULL, 0444); 5877 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); 5878 module_param_array(enable, bool, NULL, 0444); 5879 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); 5880 ]]> 5881 </programlisting> 5882 </informalexample> 5883 </para> 5884 5885 <para> 5886 Also, don't forget to define the module description, classes, 5887 license and devices. Especially, the recent modprobe requires to 5888 define the module license as GPL, etc., otherwise the system is 5889 shown as <quote>tainted</quote>. 5890 5891 <informalexample> 5892 <programlisting> 5893 <![CDATA[ 5894 MODULE_DESCRIPTION("My Chip"); 5895 MODULE_LICENSE("GPL"); 5896 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}"); 5897 ]]> 5898 </programlisting> 5899 </informalexample> 5900 </para> 5901 5902 </chapter> 5903 5904 5905 <!-- ****************************************************** --> 5906 <!-- How To Put Your Driver --> 5907 <!-- ****************************************************** --> 5908 <chapter id="how-to-put-your-driver"> 5909 <title>How To Put Your Driver Into ALSA Tree</title> 5910 <section> 5911 <title>General</title> 5912 <para> 5913 So far, you've learned how to write the driver codes. 5914 And you might have a question now: how to put my own 5915 driver into the ALSA driver tree? 5916 Here (finally :) the standard procedure is described briefly. 5917 </para> 5918 5919 <para> 5920 Suppose that you create a new PCI driver for the card 5921 <quote>xyz</quote>. The card module name would be 5922 snd-xyz. The new driver is usually put into the alsa-driver 5923 tree, <filename>alsa-driver/pci</filename> directory in 5924 the case of PCI cards. 5925 Then the driver is evaluated, audited and tested 5926 by developers and users. After a certain time, the driver 5927 will go to the alsa-kernel tree (to the corresponding directory, 5928 such as <filename>alsa-kernel/pci</filename>) and eventually 5929 will be integrated into the Linux 2.6 tree (the directory would be 5930 <filename>linux/sound/pci</filename>). 5931 </para> 5932 5933 <para> 5934 In the following sections, the driver code is supposed 5935 to be put into alsa-driver tree. The two cases are covered: 5936 a driver consisting of a single source file and one consisting 5937 of several source files. 5938 </para> 5939 </section> 5940 5941 <section> 5942 <title>Driver with A Single Source File</title> 5943 <para> 5944 <orderedlist> 5945 <listitem> 5946 <para> 5947 Modify alsa-driver/pci/Makefile 5948 </para> 5949 5950 <para> 5951 Suppose you have a file xyz.c. Add the following 5952 two lines 5953 <informalexample> 5954 <programlisting> 5955 <![CDATA[ 5956 snd-xyz-objs := xyz.o 5957 obj-$(CONFIG_SND_XYZ) += snd-xyz.o 5958 ]]> 5959 </programlisting> 5960 </informalexample> 5961 </para> 5962 </listitem> 5963 5964 <listitem> 5965 <para> 5966 Create the Kconfig entry 5967 </para> 5968 5969 <para> 5970 Add the new entry of Kconfig for your xyz driver. 5971 <informalexample> 5972 <programlisting> 5973 <![CDATA[ 5974 config SND_XYZ 5975 tristate "Foobar XYZ" 5976 depends on SND 5977 select SND_PCM 5978 help 5979 Say Y here to include support for Foobar XYZ soundcard. 5980 5981 To compile this driver as a module, choose M here: the module 5982 will be called snd-xyz. 5983 ]]> 5984 </programlisting> 5985 </informalexample> 5986 5987 the line, select SND_PCM, specifies that the driver xyz supports 5988 PCM. In addition to SND_PCM, the following components are 5989 supported for select command: 5990 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, 5991 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. 5992 Add the select command for each supported component. 5993 </para> 5994 5995 <para> 5996 Note that some selections imply the lowlevel selections. 5997 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI, 5998 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP. 5999 You don't need to give the lowlevel selections again. 6000 </para> 6001 6002 <para> 6003 For the details of Kconfig script, refer to the kbuild 6004 documentation. 6005 </para> 6006 6007 </listitem> 6008 6009 <listitem> 6010 <para> 6011 Run cvscompile script to re-generate the configure script and 6012 build the whole stuff again. 6013 </para> 6014 </listitem> 6015 </orderedlist> 6016 </para> 6017 </section> 6018 6019 <section> 6020 <title>Drivers with Several Source Files</title> 6021 <para> 6022 Suppose that the driver snd-xyz have several source files. 6023 They are located in the new subdirectory, 6024 pci/xyz. 6025 6026 <orderedlist> 6027 <listitem> 6028 <para> 6029 Add a new directory (<filename>xyz</filename>) in 6030 <filename>alsa-driver/pci/Makefile</filename> as below 6031 6032 <informalexample> 6033 <programlisting> 6034 <![CDATA[ 6035 obj-$(CONFIG_SND) += xyz/ 6036 ]]> 6037 </programlisting> 6038 </informalexample> 6039 </para> 6040 </listitem> 6041 6042 <listitem> 6043 <para> 6044 Under the directory <filename>xyz</filename>, create a Makefile 6045 6046 <example> 6047 <title>Sample Makefile for a driver xyz</title> 6048 <programlisting> 6049 <![CDATA[ 6050 ifndef SND_TOPDIR 6051 SND_TOPDIR=../.. 6052 endif 6053 6054 include $(SND_TOPDIR)/toplevel.config 6055 include $(SND_TOPDIR)/Makefile.conf 6056 6057 snd-xyz-objs := xyz.o abc.o def.o 6058 6059 obj-$(CONFIG_SND_XYZ) += snd-xyz.o 6060 6061 include $(SND_TOPDIR)/Rules.make 6062 ]]> 6063 </programlisting> 6064 </example> 6065 </para> 6066 </listitem> 6067 6068 <listitem> 6069 <para> 6070 Create the Kconfig entry 6071 </para> 6072 6073 <para> 6074 This procedure is as same as in the last section. 6075 </para> 6076 </listitem> 6077 6078 <listitem> 6079 <para> 6080 Run cvscompile script to re-generate the configure script and 6081 build the whole stuff again. 6082 </para> 6083 </listitem> 6084 </orderedlist> 6085 </para> 6086 </section> 6087 6088 </chapter> 6089 6090 <!-- ****************************************************** --> 6091 <!-- Useful Functions --> 6092 <!-- ****************************************************** --> 6093 <chapter id="useful-functions"> 6094 <title>Useful Functions</title> 6095 6096 <section id="useful-functions-snd-printk"> 6097 <title><function>snd_printk()</function> and friends</title> 6098 <para> 6099 ALSA provides a verbose version of the 6100 <function>printk()</function> function. If a kernel config 6101 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this 6102 function prints the given message together with the file name 6103 and the line of the caller. The <constant>KERN_XXX</constant> 6104 prefix is processed as 6105 well as the original <function>printk()</function> does, so it's 6106 recommended to add this prefix, e.g. 6107 6108 <informalexample> 6109 <programlisting> 6110 <![CDATA[ 6111 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n"); 6112 ]]> 6113 </programlisting> 6114 </informalexample> 6115 </para> 6116 6117 <para> 6118 There are also <function>printk()</function>'s for 6119 debugging. <function>snd_printd()</function> can be used for 6120 general debugging purposes. If 6121 <constant>CONFIG_SND_DEBUG</constant> is set, this function is 6122 compiled, and works just like 6123 <function>snd_printk()</function>. If the ALSA is compiled 6124 without the debugging flag, it's ignored. 6125 </para> 6126 6127 <para> 6128 <function>snd_printdd()</function> is compiled in only when 6129 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note 6130 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default 6131 even if you configure the alsa-driver with 6132 <option>--with-debug=full</option> option. You need to give 6133 explicitly <option>--with-debug=detect</option> option instead. 6134 </para> 6135 </section> 6136 6137 <section id="useful-functions-snd-bug"> 6138 <title><function>snd_BUG()</function></title> 6139 <para> 6140 It shows the <computeroutput>BUG?</computeroutput> message and 6141 stack trace as well as <function>snd_BUG_ON</function> at the point. 6142 It's useful to show that a fatal error happens there. 6143 </para> 6144 <para> 6145 When no debug flag is set, this macro is ignored. 6146 </para> 6147 </section> 6148 6149 <section id="useful-functions-snd-bug-on"> 6150 <title><function>snd_BUG_ON()</function></title> 6151 <para> 6152 <function>snd_BUG_ON()</function> macro is similar with 6153 <function>WARN_ON()</function> macro. For example, 6154 6155 <informalexample> 6156 <programlisting> 6157 <![CDATA[ 6158 snd_BUG_ON(!pointer); 6159 ]]> 6160 </programlisting> 6161 </informalexample> 6162 6163 or it can be used as the condition, 6164 <informalexample> 6165 <programlisting> 6166 <![CDATA[ 6167 if (snd_BUG_ON(non_zero_is_bug)) 6168 return -EINVAL; 6169 ]]> 6170 </programlisting> 6171 </informalexample> 6172 6173 </para> 6174 6175 <para> 6176 The macro takes an conditional expression to evaluate. 6177 When <constant>CONFIG_SND_DEBUG</constant>, is set, the 6178 expression is actually evaluated. If it's non-zero, it shows 6179 the warning message such as 6180 <computeroutput>BUG? (xxx)</computeroutput> 6181 normally followed by stack trace. It returns the evaluated 6182 value. 6183 When no <constant>CONFIG_SND_DEBUG</constant> is set, this 6184 macro always returns zero. 6185 </para> 6186 6187 </section> 6188 6189 </chapter> 6190 6191 6192 <!-- ****************************************************** --> 6193 <!-- Acknowledgments --> 6194 <!-- ****************************************************** --> 6195 <chapter id="acknowledgments"> 6196 <title>Acknowledgments</title> 6197 <para> 6198 I would like to thank Phil Kerr for his help for improvement and 6199 corrections of this document. 6200 </para> 6201 <para> 6202 Kevin Conder reformatted the original plain-text to the 6203 DocBook format. 6204 </para> 6205 <para> 6206 Giuliano Pochini corrected typos and contributed the example codes 6207 in the hardware constraints section. 6208 </para> 6209 </chapter> 6210 </book>