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