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